API URLs
If you are looking for information about clinical studies, please visit ClinicalTrials.gov.

API URLs

Access to API data is currently provided via two types of URLs:

  1. Info URLs, which access information about the version and structure of the ClinicalTrials.gov study records
  2. Query URLs, which perform a search, rank the retrieved study records, and return derived information about them

Both types return information in XML format by default. To obtain information in JSON or another format, use the format parameter (e.g., fmt=JSON).

Info URLs

Name Info URL Description
Data Version ClinicalTrials.gov/api/info/data_vrs Returns the date when the ClinicalTrials.gov dataset was posted. Although a new dataset is posted each weekday, typically only a small number of study records changes each day.
API Version ClinicalTrials.gov/api/info/api_vrs Returns the current version number of the ClinicalTrials.gov API. The API version number changes when the study structure changes (e.g., fields added) or when the API features change.
API Definitions ClinicalTrials.gov/api/info/api_defs Returns detailed definitions.
The Study Structure, Study Fields List, Study Statistics, and Search Areas info URLs listed below retrieve key components of API Definitions.
Study Structure ClinicalTrials.gov/api/info/study_structure Returns all available data elements for a single study record.
Study Fields List ClinicalTrials.gov/api/info/study_fields_list Returns all data elements that can contain text values and are used by the Study Statistics and Search Areas info URLs listed below.
Study Statistics ClinicalTrials.gov/api/info/study_statistics Returns an annotated version of the Study Structure info URL.
Search Areas ClinicalTrials.gov/api/info/search_areas Returns groups of weighted study fields, or "search areas", that can be searched at once (e.g., BasicSearch consists of 58 API fields).

Query URLs

Query URLs need the expr parameter to set a search expression. If no search expression is provided in a Query URL, the query will retrieve all study records.

Note that queries can retrieve large numbers of study records. Each query URL type has default and maximum numbers of studies that can be returned. Use the minimum rank (min_rnk) and maximum rank (max_rnk) parameters to select the range of study records to process and return. To retrieve more study records, issue multiple queries with sequential ranges for the minimum rank and maximum rank until all records have been retrieved.

Need Help?
Use one of the interactive demonstrations to create a query URL, see it in action, and view its syntax.
Name Example Query URL Description Default Returned Format
Full Studies ClinicalTrials.gov/api/query/full_studies?expr=heart+attack Returns all content for a small set of study records. Returns one study record by default.

Returns up to 100 study records per query when the minimum rank and maximum rank parameters are set.

Returns in tree format when the format parameter is set (fmt=tree).
Study Fields ClinicalTrials.gov/api/query/study_fields?expr=heart+attack&fields=NCTId,Condition,BriefTitle Returns values from selected API fields for a large set of study records. Select the fields returned using the fields parameter (shown in the Query Parameters table). For a complete list of fields, use the Study Fields List info URL. Returns 20 study records by default.

Returns up to 1,000 study records when minimum rank and maximum rank parameters are set.

Returns in JSON or CSV format when the format parameter is set (fmt=JSON or fmt=CSV, respectively).
Field Values ClinicalTrials.gov/api/query/field_values?expr=heart+attack&field=Condition Returns all values found in a single API field for a set of study records. Select the field values returned by using the field parameter (shown in the Query Parameters table). For a complete list of fields, use the Study Fields List info URL. Returns all field values found by the search by default.

Returns only the values found in a range of study records when the minimum rank and maximum rank parameters are set.

Returns in JSON or CSV format when the format parameter is set (fmt=JSON or fmt=CSV, respectively).

Query Parameters

Note: Parameter values must be URL encoded, which means that certain characters must be converted (e.g., replace a space with "+" and "&" with "%26").

Parameter Description
fmt Format of response can be either XML (default) or JSON for all types of query URLs. Study Fields and Field Values query URLs also support CSV format. Full Studies query URLs support tree format.
expr Search expression that follows the API search syntax. If absent, defaults to the search expression ALL, which returns all study records.
min_rnk Minimum Rank sets the lower limit on the range of study records used to return results. If absent, defaults to 1.
max_rnk Maximum Rank sets the upper limit on the range of study records used to return results. Different query URL types have different limits on the number of results that can be returned, as described in the Query URLs table. If absent, defaults to the minimum rank plus the number of study records allowed for that query URL type.
fields Specifies which fields to return results for in a Study Fields query. A complete list of fields is provided by the Study Fields List info URL. If absent, defaults to an empty list, which produces an empty result. Select the study fields returned by setting the fields parameter using a comma-delimited list (e.g., fields=NCTId,Condition,BriefTitle).
field Specifies which field to collect values for in a Field Values query. A complete list of fields is provided by the Study Fields List info URL. An area must be specified to get FieldTexts; there is no default. Select the study field by setting the field parameter to a field name (e.g., field=Condition).
This page last reviewed in September 2019