Page History

Summary

This document describes v3 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 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 help@cancerimagingarchive.net.

Note that

...

Previously access to the APIs required an API-KEY.  An API-KEY is no longer required to access the public TCIA collections.

What's new

The following characteristics apply to all TCIA APIs.

Version 4 (current)

• The getSeries API has been modified to include new query parameters.
• Bug fixes.

Version 3 (Documentation for Version 3 can be found here)

• Two new APIs have been added (/getSingleImage, /getSOPInstanceUIDs).
• Three new APIs have been added (/NewPatientsInCollection, /NewStudiesInPatientsCollection, /PatientsByModality).
• The getSeries API has been modified to include new query parameters.
• Bug fixes.
  

Version 2 (Documentation for Version 2 can be found here)

• 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 access to the API:

• Every request must contain an Previously access to the APIs required an API-KEY.  An API-KEY is no longer required to access the public TCIA collections. Simply call the RESTful endpoints.
•  To support existing code without changes, 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:
• If you don't have a TCIA account, please create one by visiting https://public.cancerimagingarchive.net/ncia/login.jsf
If you already have a TCIA account, please send a request to help@cancerimagingarchive.net  Since the API-KEY is no longer needed, the underlying service will simply ignore it.

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
• An API request takes the following structure:
  <BaseURL><Resource><QueryEndpoint>?<QueryParameters><Format> 
  For example, the API shown below is a request to get all studies in the TCGA-GBM collection for patient GBM-0123 as CSV
  https://services.cancerimagingarchive.net/services/v3v4/TCIA/query/getPatientStudy?Collection=TCGA-GBM&PatientID=GBM-0123&format=csv
  This can be broken down as follows: 

...

Example:
Let us say we wanted metadata for the getPatientStudy query from our earlier example. The query would look as follows:
https://services.cancerimagingarchive.net/services/v3v4/TCIA/query/getPatientStudy/metadata 

...