This document describes v4 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 email@example.com.
Previously access to the APIs required an API-KEY. An API-KEY is no longer required to access the public TCIA collections.
The following characteristics apply to all TCIA APIs.
Version 4 (current)
Version 3 (Documentation for Version 3 can be found here)
Version 2 (Documentation for Version 2 can be found here)
Getting access to the API:
The following characteristics apply to all TCIA APIs:
|BaseURL||The BaseURL includes the version number of this API (v4 in this example)|
|Query Parameters||Collection=TCGA-GBM & |
|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 full API consists of a base URL followed by the api and the query parameters in that order.
Query ParametersAll query parameters are
optional unless stated otherwise
|/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 / |
|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|
Returns a list of PatientIDs, given a specific Collection Name and Modality
|/query/getPatientStudy||Collection / PatientID / |
|CSV/HTML/XML/JSON||Set of patient/study objects filtered by query keys|
Collection / StudyInstanceUID /
|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|
Returns a set of Patients that have been added to a specified collection since a specified date.
Please note, there is a bug if you include a Date argument to NewPatientsInCollection under v3 of the API. This was fixed in v4.
Returns a set of Studies that have been added to a specified collection, and optionally to a patient since a specified dateDate is specified as (YYYY-MM-DD)
Use the getCollectionValues to get the list of available collections
Return a list of SOPInstanceUID for a given series using the SeriesInstanceUID
|Raw DICOM Object||Returns a SINGLE DICOM Object that is identified by its SeriesInstanceUID and SOPInstanceUID. This API will always be used following the /getSOPInstanceUIDs|
|/query/ContentsByName||name (R)||JSON||Given the name of a shared list return its contents.|
The API now supports the ability to programmatically access the metadata about your API. This information is provided as a JSON document and includes:
Name of API
Free text description
List of Query Parameters
Supported Return Types
A description of the returned attributes: Name, DICOM Tag and Description
Let us say we wanted metadata for the getPatientStudy query from our earlier example. The query would look as follows:
Or in other words, the query would have the following structure:
(Warning) Don’t forget to include the api-key in either HTTP headers or the URL of the API.
Click here to see more details on the return values.