This document describes v2 of the TCIA programmatic Interface or REST API implementation. This API is designed for use by developers of image analysis and data mining tools to directly query the public resources of TCIA and retrieve information into their applications. The API complements the existing web interface but eliminates the need for users to visit the TCIA web pages to select and download images then upload them into their viewing and analysis applications. The TCIA Programmatic Interface is based on a middleware platform called Project Bindaas, developed by Emory University and uses REST web service technologies.
The API is a RESTful interface, accessed through web URLs. There is no software that an application developer needs to download in order to use the API. The application developer can build their own access routines using just the API documentation provided. The interface employs a set of predefined query functions (see REST API Directory) that access TCIA databases.
If you are interested in using the API and have any questions, please contact us at cancerimagingarchive@mail.nih.gov.
The following characteristics apply to all TCIA APIs:
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. |
The following characteristics apply to all TCIA APIs:
https://services.cancerimagingarchive.net/services/v2 |
The full API consists of a base URL followed by the api and the query parameters in that order.
Resource | ResourceURL | Query | Metadata Query | Description |
---|---|---|---|---|
TCIA | /TCIA/query |
| ||
/getPatient | ||||
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 |
Click here to see more details on the return values.
There are two RESTful servers provided by TCIA. A test system is loaded with a small set of known data to allow you to test your applications. The production system is configured to use the full TCIA database. The query format is the same for both systems. The base URLs are:
Type | URL |
---|---|
Production | https://services.cancerimagingarchive.net/services/v2/TCIA/query |
Test | https://services-test.cancerimagingarchive.net/services/v2/TCIA/query |
Click Here to see the test data that has been loaded on these test servers have the following test data