ctgov

Paginating ClinicalTrials.gov API v2 client with free-text endpoint normalization.

Zero dependencies. Pure standard library. No API key.

pip install ctgov

Why

Two things the registry makes harder than they should be.

1. You cannot get more than 1,000 studies

The API caps a response at 1,000 and hands back a nextPageToken. Existing wrappers stop there, so "how do I pull more than 1000 studies?" is the question that keeps getting asked and never answered.

ctgov follows the token for you. Your result set is bounded by your query, not by the page size.

from ctgov import Client

client = Client()
studies = client.studies("AREA[Phase]PHASE3", max_studies=5000)   # pages automatically
print(len(studies))                                                # 5000

for study in client.iter_studies("cancer"):     # streams; one page in memory at a time
    ...

2. Endpoints are prose, so you cannot compare across trials

Straight from the API, an outcome measure looks like this:

You cannot group, filter, or compare on that. ctgov structures it:

Query to structured rows in one call

from ctgov import endpoints

rows = [r for r in endpoints("AREA[Phase]PHASE3", max_studies=200)
        if r["normalization_confidence"] >= 0.7]

for r in rows[:3]:
    print(r["endpoint_canonical"], r["horizon_days"], r["condition_primary"])

Each row carries the study context (phase, condition, enrollment, sponsor, allocation, masking), the normalized endpoint fields, and the untouched raw text, so any row can be audited rather than taken on trust.

Straight into pandas:

import pandas as pd
df = pd.DataFrame(endpoints("AREA[Condition]diabetes", max_studies=500))
df.groupby("endpoint_canonical")["horizon_days"].median().sort_values()

Counting without downloading

client.count("AREA[Phase]PHASE3", filters={"advanced": "AREA[HasResults]true"})   # 14748

What you get per endpoint

Honesty about coverage

Normalization is deterministic and rule-based — no model inference, so it is reproducible, auditable, and free to run. It does not classify everything, and it says so rather than guessing: across 124,790 endpoints from 14,170 trials started since 2020, 72% get a domain, 90% a measure type, 61% a parsed time horizon, and 35% a recognised concept. The rest is a genuine long tail of disease-specific measures ("Swollen Joint Count", "Bowel Filling Properties: Distension/Distal Ileum") and is labelled unclassified with raw text retained.

normalization_confidence exists so you can pick your own precision/recall tradeoff.

Being a good citizen

NLM asks for no more than 20 requests/second per IP. ctgov defaults to roughly 3/s and retries with exponential backoff. Please set a contactable user agent:

Client(user_agent="my-project (me@example.com)")

Relationship to pytrials

pytrials is a good, focused API wrapper. ctgov is not a replacement for it so much as a different scope: pagination past the 1,000 cap, and a normalization layer over the free-text outcome fields. If you only need to pull a few hundred studies as a DataFrame, pytrials is a smaller dependency and will serve you fine.

Licence and attribution

MIT. Source data is ClinicalTrials.gov (U.S. National Library of Medicine), public domain.

This product uses publicly available data from the U.S. National Library of Medicine (NLM), National Institutes of Health, Department of Health and Human Services; NLM is not responsible for the product and does not endorse or recommend this or any other product.