Access to API data is currently provided via two types of URLs:
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).
| Name | Info URL | Description |
|---|---|---|
| Data Version | Classic.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 | Classic.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 | Classic.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 | Classic.ClinicalTrials.gov/api/info/study_structure | Returns all available data elements for a single study record. |
| Study Fields List | Classic.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 | Classic.ClinicalTrials.gov/api/info/study_statistics | Returns an annotated version of the Study Structure info URL. |
| Search Areas | Classic.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 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.
| Name | Example Query URL | Description | Default Returned | Format |
|---|---|---|---|---|
| Full Studies | Classic.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 | Classic.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 | Classic.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). |
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). |