| Table of Contents |
|---|
Summary
This document describes the initial public release 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.
...
If you are interested in using the API and have any questions, please contact us at cancerimagingarchive@mail.nih.gov.
Incorporating the TCIA Programmatic Interface into Your Application
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.
REST API URL and Format
The full API consists of a base URL followed by the api and the query parameters in that order.
...
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 | Query Key 6 |
|---|---|---|---|---|---|---|---|---|
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) |
|
|
getImage | Set of images in a zip file | ZIP | SeriesInstanceUID (R) | NA | NA | NA |
|
|
Return Values
Collection
An object that represents Collection (project) values.
| Attribute | DICOM Tag | Description |
|---|---|---|
| Collection | NA | A label used to name a set of images collected for a specific trial or other reason. |
Modality
An object that represents Modality values.
| Attribute | DICOM Tag | Description |
|---|---|---|
| Modality | 0008 0060 | Standard DICOM definition |
BodyPartExamined
An object that represents BodyPartExamined values.
| Attribute | DICOM Tag | Description |
|---|---|---|
| BodyPartExamined | 0018 0015 | Standard DICOM definition |
Manufacturer
An object that represents Manufacturer values.
| Attribute | DICOM Tag | Description |
|---|---|---|
| Manufacturer | 0008 0070 | Standard DICOM definition |
Patient
An object that represents one patient.
Attribute | DICOM Tag | Description |
|---|---|---|
PatientID | 0010 0020 | Has been de-identified as part of submission process. |
PatientName | 0010 0010 | Has been de-identified as part of submission process. |
PatientBirthDate | 0010 0030 | Has been de-identified (emptied) as part of submission process. |
PatientSex | 0010 0040 | Standard DICOM definition |
EthnicGroup | 0010 2160 | Standard DICOM definition |
| Collection | NA | A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data. |
PatientStudy
An object that represents one DICOM imaging study performed on one patient.
Attribute | DICOM Tag | Description |
|---|---|---|
| StudyInstanceUID | 0020 000D | Has been de-identified as part of submission process. |
| StudyDate | 0008 0020 | Has been de-identified as part of submission process. Longitudinal information is preserved. |
| StudyDescription | 0008 1030 | Standard DICOM definition. Has been inspected and cleaned of any PHI |
| AdmittingDiagnosesDescription | 0008 1080 | Standard DICOM definition. Has been inspected and cleaned of any PHI |
| StudyID | 0020 0010 | Has been de-identified as part of submission process. |
| PatientAge | 0010 1010 | Standard DICOM definition |
| PatientID | 0010 0020 | Has been de-identified as part of submission process. |
| PatientName | 0010 0010 | Has been de-identified as part of submission process. |
| PatientBirthDate | 0010 0030 | Has been de-identified (emptied) as part of submission process. |
| PatientSex | 0010 0040 | Standard DICOM definition |
| EthnicGroup | 0010 2160 | Standard DICOM definition |
| Collection | NA | A label used to name a set of images collected for a specific trial or other reason. |
| SeriesCount | NA | Computed number of series. |
Series
An object that represents one imaging series.
Attribute | DICOM Tag | Description |
|---|---|---|
| SeriesInstanceUID | 0020 000E | Has been de-identified as part of submission process. |
| StudyInstanceUID | 0020 000D | Has been de-identified as part of submission process. |
Modality | 0008 0060 | Standard DICOM definition |
| ProtocolName | 0018 1030 | Standard DICOM definition. Has been inspected and cleaned of any PHI |
| SeriesDate | 0008 0021 | Standard DICOM definition |
SeriesDescription | 0008 103E | Standard DICOM definition. Has been inspected and cleaned of any PHI |
| BodyPartExamined | 0018 0015 | Entered on a per collection basis using relevant SNOMED terms. |
| SeriesNumber | 0020 0011 | Standard DICOM definition |
| AnnotationsFlag | NA | |
| Collection | NA | A label used to name a set of images collected for a specific trial or other reason. |
| PatientID | 0010 0020 | Has been de-identified as part of submission process. |
| Manufacturer | 0008 0070 | Standard DICOM definition |
| ManufacturerModelName | 0008 1090 | Standard DICOM definition |
| SoftwareVersions | 0018 1020 | Standard DICOM definition |
| ImageCount | NA | Computed number of images in this series. |
Image
An object that represents set of images in zip file based on SeriesInstanceUID.
| Attribute | DICOM Tag | Description |
|---|---|---|
| NA | NA | Set of images in a zip file |
Production / Test URLs and Test Data
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:
...