Summary
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.
...
If you are interested in using the API and have any questions, please contact us at cancerimagingarchive@mail.nih.gov.
What's new
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.
- 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
Getting Started with the TCIA API
The following characteristics apply to all TCIA APIs:
...
- 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 | QueryEndpoint | Query Parameters All query parameters areoptional unless stated otherwise | Format | Description |
|---|---|---|---|---|
| /TCIA |
| |||
| /query/getCollectionValues | None | CSV/HTML/XML/JSON | Set of all collection names | |
| /query/getModalityValues | Collection / BodyPartExamined | CSV/HTML/XML/JSON | Set of all modality values (CT, MR, ...) filtered by query keys | |
| /query/getBodyPartValues | Collection / Modality | CSV/HTML/XML/JSON | Set of all body part names filtered by query keys | |
| /query/getManufacturerValues | Collection / Modality / BodyPartExamined | CSV/HTML/XML/JSON | Set of all manufacturer names filtered by query keys | |
| /query/getPatient | Collection | CSV/HTML/XML/JSON | Set of patient objects filtered by query keys | |
| /query/getPatientStudy | Collection / PatientID / StudyInstanceUID | CSV/HTML/XML/JSON | Set of patient/study objects filtered by query keys | |
| /query/getSeries | Collection / StudyInstanceUID / PatientID / SeriesInstanceUID | CSV/HTML/XML/JSON | Set of series objects filtered by query keys | |
| /query/getSeriesSize | SeriesInstanceUID (R) | CSV/HTML/XML/JSON | Set of total byte size and object count filtered by query key | |
| /query/getImage | SeriesInstanceUID (R) | ZIP | Set of images in a zip file | |
| /SharedList | ||||
| /query/ContentsByName | name (R) | JSON | Given the name of a shared list return its contents. |
API Metadata
The API now supports the ability to programmatically access the metadata about your API. This information is provided as a JSON document and includes:
...
(Warning) Don’t forget to include the api-key in either HTTP headers or the URL of the API.
Return Values
Click here to see more details on the return values.
Testing the API
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:
...