...
- You access a resource by sending an HTTP request to the TCIA API server. The server replies with a response that either contains the data you requested, or a status indicator.
- Every request must contain an API-KEY. The key can be included in the url by adding an extra query parameter api_key or it can be included in the HTTP headers. We strongly recommend that the API-KEY be sent via HTTP headers.
- You can obtain one API-KEY and use that for your application; you do not need a separate API-KEY for each user of your software.. To obtain an API-Key please send a request to help@cancerimagingarchive.net or contact TCIA's help desk by phone at: +1 314-747-4254.
- You can access the metadata of an API by appending /metadata to the end of a QueryEndpoint, without any QueryParameters (See below). The metadata is in JSON format and conforms to this schema
- Most APIs can return results as CSV/JSON/XML/HTML. You can specify the return format by including the query parameter format
- An API request takes the following structure:
<BaseURL><Resource><QueryEndpoint>?<QueryParameters><Format>
For example, the API shown below is a request to get all studies in the TCGA-GBM collection for patient GBM-0123 as CSV
This can be broken down as follows:
| BaseURL | https://services.cancerimagingarchive.net/services/v2 | The BaseURL includes the version number of this API (v2 in this example) |
|---|---|---|
| Resource | /TCIA | |
| QueryEndpoint | /query/getPatientStudy | |
| Query Parameters | Collection=TCGA-GBM PatientID=GBM-0123 | |
| Format | format=csv | Some APIs support CSV/HTML/XML/JSON, while others only support a single return type. Therefore this is required only in instances where multiple return types are supported. |
Getting Started with the TCIA API
...
- You access a resource by sending an HTTP request to the TCIA API server. The server replies with a response that either contains the data you requested, or a status indicator.
- You can access the metadata of an API by appending /metadata to the end of the query. See examples. The metadata is in JSON format and conforms to this schema
- Most APIs can return results as CSV/JSON/XML/HTML. You can specify the return format by including the query parameter format
- Every request must contain an API-KEY. The key can be included in the url by adding an extra query parameter api_key or it can be included in the HTTP headers.
You can obtain one API-KEY and use that for your application; you do not need a separate API-KEY for each user of your software.. To obtain an API-Key please send a request to help@cancerimagingarchive.net or contact TCIA's help desk by phone at: +1 314-747-4254.
- The baseURL for the TCIA API is:
...
- An API request takes the following structure:
<BaseURL><Resource><QueryEndpoint>?<QueryParameters><Format>
For example, the API shown below is a request to get all studies in the TCGA-GBM collection for patient GBM-0123 as CSV
https://services.cancerimagingarchive.net/services/v2/TCIA/query/getPatientStudy?Collection=TCGA-GBM&PatientID=GBM-0123&format=csv
This can be broken down as follows:
...
| BaseURL | https://services.cancerimagingarchive.net/services/v2 | The BaseURL includes the version number of this API (v2 in this example) |
|---|---|---|
| Resource | /TCIA | |
| QueryEndpoint | /query/getPatientStudy | |
| Query Parameters | Collection=TCGA-GBM PatientID=GBM-0123 | |
| Format | format=csv | Some APIs support CSV/HTML/XML/JSON, while others only support a single return type. Therefore this is required only in instances where multiple return types are supported. |
- Coding examples can be found on GitHub
- Interface documentation can be found on Mashape
- The interface is registered on ProgrammableWeb
...
API Reference
The full API consists of a base URL followed by the api and the query parameters in that order.
| Resource | ResourceURLQueryEndpoint | Query Parameters | Metadata QueryFormat | Description | |
|---|---|---|---|---|---|
| /TCIA |
| ||||
| /query/getCollectionValues | |||||
| /query/getModalityValues | |||||
| /query/getBodyPartValues | /TCIA/query | ||||
| /query/getManufacturerValues | |||||
| /query/getPatient | |||||
| /query/ | /query/ | ||||
| /query/ | |||||
| /query/ | |||||
| /query/ | |||||
| /query/ | |||||
| /query/ | |||||
| /query/ | |||||
| SharedList | /SharedList/query | /ContentsByName |
Query Name | Return Values | Output Format | Query Key 1 | Query Key 2 | Query Key 3 | Query Key 4 |
|---|---|---|---|---|---|---|
getCollectionValues | Set of all collection names | CSV/HTML/XML/JSON | NA | NA | NA | NA |
getModalityValues | Set of all modality values (CT, MR, ...) filtered by query keys | CSV/HTML/XML/JSON | Collection (O) | BodyPartExamined (O) | Modality (O) | NA |
getBodyPartValues | Set of all body part names filtered by query keys | CSV/HTML/XML/JSON | Collection (O) | BodyPartExamined (O) | Modality (O) | NA |
getManufacturerValues | Set of all manufacturer names filtered by query keys | CSV/HTML/XML/JSON | Collection (O) | BodyPartExamined (O) | Modality (O) | NA |
| getPatient | Set of patient objects filtered by query keys | CSV/HTML/XML/JSON | Collection (O) | NA | NA | Na |
getPatientStudy | Set of patient/study objects filtered by query keys | CSV/HTML/XML/JSON | Collection (O) | PatientID (O) | StudyInstanceUID (O) | NA |
getSeries | Set of series objects filtered by query keys | CSV/HTML/XML/JSON | Collection (O) | PatientID (O) | StudyInstanceUID (O) | Modality (O) |
| getSeriesSize | Set of total byte size and object count filtered by query key | CSV/HTML/XML/JSON | SeriesInstanceUID (R) | NA | NA | NA |
getImage | Set of images in a zip file | ZIP | SeriesInstanceUID (R) | NA | NA | NA |
...