The ClinicalTrials.gov application programming interface (API) supports three types of queries in the form of query URLs:
Each query URL returns a response in a specified file format (i.e., XML, JSON, CSV, or tree), as detailed below.
Query URLs find study records that satisfy a search expression and calculate a response based on those records. Standard header information, which includes version information, the search expression and other parameters, and any warning messages, is displayed for all responses. These values are described in the following table:
| Value | Description |
|---|---|
| API Version (APIVrs) | Version of the study structure, presented in the following format: [major release number].[significant release number].[minor research number] (e.g., 1.01.02). |
| Data Version (DataVrs) | Version of the study data, presented in the following format: YYYY:MM:DD HH:MM:SS.sss (e.g., 2019:01:27 22:15:45.397). |
| Expression | Query or search expression. |
| Number of Studies Available (NStudiesAvail) | Total number of study records available in the version of the study data. |
| Number of Studies Found (NStudiesFound) | Number of studies found that satisfy the search expression. |
| Minimum Rank (MinRank) | Starting number of a range of retrieved studies used to calculate the response where the study record with the highest relevance is ranked as 1. |
| Maximum Rank (MaxRank) | Ending number of a range of retrieved studies used to calculate the response where the study record with the highest relevance is ranked as 1. |
| Warning | Message indicating possible problems, such as the API Version requested is out of date, is missing, or has been retired. |
Query URL-specific results are listed below the standard header information, as described in the next section.
The response to a Full Studies query URL provides all publicly available fields for a few studies. A sample query URL and an excerpt from the response are displayed below.
https://clinicaltrials.gov/api/query/full_studies?expr=heart+attack&fmt=xml
PlaceHolder
View the entire Full Studies sample full studies response in XML, JSON, or tree format.
NStudiesReturned, which immediately follows the standard header information in a Full Studies response, indicates the number of studies found within the range specified by the minimum and maximum rank parameters. If neither rank is specified, the study record with the highest relevance (i.e., rank 1) is returned by default. Generally, up to 100 studies can be returned at once.
The Full Studies response includes a list of study records that satisfy the search expression and are within the range specified by the minimum rank and maximum rank parameters in the query URL. Each study record is represented by a FullStudy object that contains all the values for each publicly available study field in a study structure.
Use the Full Studies interactive demonstration to explore and develop requests and responses for this type of query URL.
The response to a Study Fields query URL provides information for selected publicly available fields for many studies. An excerpt from a sample query URL and an excerpt from the response for the following query URL are displayed below.
https://ClinicalTrials.gov/api/query/study_fields?expr=heart+attack&fields=NCTId,Condition,BriefTitle
PlaceHolder
View the entire Study Fields sample response in XML, JSON, or CSV format.
NStudiesReturned, which immediately follows the standard header information in a Study Fields response, indicates the number of studies found within the range specified by the minimum rank and maximum rank parameters. If neither rank is specified, the 20 most relevant study records (i.e., ranks 1-20) are returned by default. Generally, up to 1,000 studies can be returned at once.
The Study Fields response includes only the fields specified in the query URL and their values for each of the retrieved study records. The Data Element-to-API Field Crosswalks page lists all publicly available study fields, and the study structure page describes how study fields are organized on ClinicalTrials.gov. Frequently selected study fields include the following:
The Study Fields response includes a list of study records that satisfy the search expression and are within the range specified by the minimum rank and maximum rank parameters in the query URL. Each study record is represented by a StudyFields object that contains all the values for the specified fields. Generally, a study may have no, one, or multiple values for each study field.
Use the Study Fields interactive demonstration to explore and develop requests and responses for this type of query URL.
The response to a Field Values query URL provides all values for a single study field for many studies. A sample query URL and an excerpt from the response are displayed below.
https://ClinicalTrials.gov/api/query/field_values?expr=heart+attack&field=Intervention
PlaceHolder
View the entire Field Values sample response in XML, JSON, or CSV format.
NStudiesUsed, which immediately follows the standard header information in a Field Values response, indicates the number of studies found within the range specified by the minimum rank and maximum rank parameters. If neither rank is specified, all studies found are returned by default. The following values described in the following table are also provided:
| Value | Description |
|---|---|
| NUniqueValues | Number of unique values in the specified study field across all studies in the database. |
| NUniqueValuesFound | Number of unique values in the specified study field among only studies retrieved by the search. |
| NStudiesMissingValue | Number of studies with no values in the specified field across all studies in the database. |
| NStudiesFoundMissingValue | Number of studies retrieved by the search with no values in the specified study field among only studies retrieved by the search. |
| NStudiesWithValue | Number of studies with values in the specified study field in the database and also with values in the specified study field in at least one of the studies retrieved by the search; values appearing only in studies not retrieved by the search are excluded. |
| NStudiesFoundWithValue | Number of studies with values in the specified study field retrieved by the search. |
Note: To list values for a study field for all study records in the database, use the ALL operator in the search expression.
Use the Field Values interactive demonstration to explore and develop requests and responses for this type of query URL.