...
| 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
The following characteristics apply to all TCIA APIs:
- 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:
| Code Block | ||||
|---|---|---|---|---|
| ||||
https://services.cancerimagingarchive.net/services/v2 |
- 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.
For example, in the following URL:
| Code Block |
|---|
https://services.cancerimagingarchive.net/services/v2/TCIA/query/getSeries?Collection=TCGA-GBM&PatientID=1.2.3&StudyInstanceUID=4.5.6&format=csv
|
...
NOTE: The order in which the query parameters are provided does not matterWith the exception of the getImage query, all other queries return one of these data formats : CSV,HTML,XML and JSON 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.
| Resource | ResourceURL | Query | Metadata Query | Description | |
|---|---|---|---|---|---|
| TCIA | /TCIA/query |
| |||
| /getPatient | |||||
| SharedList | /SharedList/query | /ContentsByName |
...
Return Types
...
Your software that uses the programmatic interface requires an API-KEY. In this version of the programmatic interface, the API-KEY is used to identify the software application. 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. Please see the coding examples in github: https://github.com/nadirsaghar/TCIA-REST-API-Client for guidance on how to incorporate the API-Key into your code. Once you have acquired an API-Key you will need to implement a minimal amount of software in your application to invoke the REST API.
- Coding examples can be found on GitHub
- Interface documentation can be found on Mashape
- The interface is registered on ProgrammableWeb
REST API URL and Format
The full API consists of a base URL followed by the api and the query parameters in that order.
For example, in the following URL:
| Code Block |
|---|
https://services.cancerimagingarchive.net/services/TCIA/TCIA/query/getSeries?Collection=TCGA-GBM&PatientID=1.2.3&StudyInstanceUID=4.5.6&format=csv
|
...
NOTE: The order in which the query parameters are provided does not matter
With the exception of the getImage query, all other queries return one of these data formats : CSV,HTML,XML and JSON 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
Query Name | Return Values | Output Format | Query Key 1 | Query Key 2 | Query Key 3 | Query Key 4 |
|---|
Query Key 5
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 |
Return Values
Click here to see more details on the return values.
...