...
REST API URL and Format
The TCIA REST API defines one base URL for all queries: https://services.cancerimagingarchive.netfull API consists of a base URL followed by the api, the api_key and the query parameters in that order.
For example, in the following API: http://10.28.163.174:9099/services/TCIA/TCIA/query/getSeries?api_key=a9312dfe-4465-4e0b-8b76-8eeab0b77ce5&collection=TCGA-GBM&patient_id=1.2.3&study_instance_uid=4.5.6&
The base URL is: http://10.28.163.174:9099/services/TCIA/TCIA/query. Each query described below will use a URL that consists of the base URL with a further specification of the resource. For example, the first query getCollectionValues will use the URL: https/
The API endpoint is getSeries
The api_key is provided as follows: ?api_key=a9312dfe-4235-4e0b-8b76-8fghqab0b77ce5
And the three query parameters are provided as follows: &collection=TCGA-GBM&patient_id=1.2.3&study_instance_uid=4.5.6&
NOTE: The order in which the query parameters are provided does not matter.
The full API consists of a base URL followed by the api, the api_key and the query parameters in that order.
For example, in the following URL:
| Code Block |
|---|
http://services.cancerimagingarchive.net:9099/services/TCIA/TCIA/query/getSeries?api_key=a9312dfe-4465-4e0b-8b76-8eeab0b77ce5&collection=TCGA-GBM&patient_id=1.2.3&study_instance_uid=4.5.6
|
- The base URL is: http://services.cancerimagingarchive.net:9099/services/TCIA/TCIA/query
- The API endpoint is getSeries
- The api_key is provided as follows: &api_key=a9312dfe-4235-4e0b-8b76-8fghqab0b77ce5
- And the three query parameters are provided as follows: &collection=TCGA-GBM&patient_id=1.2.3&study_instance_uid=4.5.6
NOTE: The order in which the query parameters are provided does not matter
With the exception of the getImage query, all other query/getCollectionValuesAll queries return a comma separated value (CSV) file with results. The first line of the file contains the names of the columns in the response. Each subsequent line corresponds to one row from the TCIA database. The getImage query returns a zip of the images.
REST API Directory (Available)
The query keys in the table below are the literal strings used as keys for key/value pairs to specify query parameters. After each key is an indication if the key is required for the query (R) or optional (O). Omitting optional keys will lead to responses that are more broad. Right now we are just supporting = for the database operator. Do we want to support some substring matching?
The api_key described above is listed as a Query Key in the table below for simplicity and completeness. It is a required part of the API for all queries. For this collection, the defined value for the api_key is:
| Code Block |
|---|
a9312dfe-4235-4e0b-8b76-8fghqab0b77ce5
|
Query Name | Return Values | Query Key 1 | Query Key 2 | Query Key 3 | Query Key 4 | Query Key 5 | Query Key 6 | |
|---|---|---|---|---|---|---|---|---|
getCollectionValues | Set of all collection names | api_key (R) |
|
|
|
|
| |
getPatientStudy | Set of patient/study objects filtered by query keys | api_key (R) | collection (O) | patient_id (O) | study_instance_uid (O) |
| ||
getSeries | Set of series objects filtered by query keys | api_key (R) | collection (O) | patient_id (O) | study_instance_uid (O) |
| ||
getImage | Set of images in a zip file | api_key (R) | series_instance_uid (R) |
|
|
|
|
REST API Directory (Proposed)
Query Name | Return Values | Query Key 1 | Query Key 2 2 | Query Key 3 | Query Key 4 | Query Key 5 | Query Key 6 | Query Key 67 |
|---|---|---|---|---|---|---|---|---|
getCollectionValues | Set of all collection names | api_key (R) | collection (O) | modality (O) | body_part (O) | manufacturer (O) |
|
|
getModalityValues | Set of all modality values (CT, MR, ...) filtered by query keys | api_key (R) | collection (O) | modality (O) | body_part (O) | manufacturer (O) |
|
|
getBodyPartValues | Set of all body part names filtered by query keys | api_key (R) | collection (O) | modality (O) | body_part (O) | manufacturer (O) |
|
|
getManufacturerValues | Set of all manufacturer names filtered by query keys | api_key (R) | collection (O) | modality (O) | body_part (O) | manufacturer (O) |
|
|
getPatientStudy | Set of patient/study objects filtered by query keys | api_key (R) | collection (O) | modality (O) | body_part (O) | manufacturer (O) | patient_id (O) | study_instance_uid (O) |
getSeries | Set of series objects filtered by query keys | api_key (R) | collection (O) | modality (O) | body_part (O) | manufacturer (O) | patient_id (O) | study_instance_uid (O) |
getImages | Set of images in a zip file | api_key (R) | series_instance_uid (R) |
|
|
|
|
|
...