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.

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.

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
• 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/v2/TCIA/query/getPatientStudy?Collection=TCGA-GBM&PatientID=GBM-0123&format=csv

This can be broken down as follows:

Getting Started with the TCIA API

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
  • 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.
    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. 

  • The baseURL for the TCIA API is: 

    https://services.cancerimagingarchive.net/services/v2

API Reference

The full API consists of a base URL followed by the api and the query parameters in that order.

For example, in the following URL:

https://services.cancerimagingarchive.net/services/v2/TCIA/query/getSeries?Collection=TCGA-GBM&PatientID=1.2.3&StudyInstanceUID=4.5.6&format=csv

• • The base URL is: https://services.cancerimagingarchive.net/services/v2/TCIA/query
  • The API endpoint is getSeries
  • And the four query parameters are provided as follows:  Collection=TCGA-GBM&PatientID=1.2.3&StudyInstanceUID=4.5.6&format=csv 
    
    
  • Data can be obtained in the following formats : CSV,HTML,XML and JSON. 
    

NOTE: The order in which the query parameters are provided does not matter

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.

Return Types

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.

• • Coding examples can be found on GitHub
  • Interface documentation can be found on Mashape
  • The interface is registered on ProgrammableWeb

REST API URL and Format

The full API consists of a base URL followed by the api and the query parameters in that order.

For example, in the following URL:

https://services.cancerimagingarchive.net/services/TCIA/TCIA/query/getSeries?Collection=TCGA-GBM&PatientID=1.2.3&StudyInstanceUID=4.5.6&format=csv

• • The base URL is: https://services.cancerimagingarchive.net/services/TCIA/TCIA/query
  • The API endpoint is getSeries
  • And the four query parameters are provided as follows:  Collection=TCGA-GBM&PatientID=1.2.3&StudyInstanceUID=4.5.6&format=csv
    
    
  • Data can be obtained in the following formats : CSV,HTML,XML and JSON.
    

NOTE: The order in which the query parameters are provided does not matter

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

Return Values

Collection

An object that represents Collection (project) values.

Modality

An object that represents Modality values.

BodyPartExamined

An object that represents BodyPartExamined values.

Manufacturer

An object that represents Manufacturer values.

Patient

An object that represents one patient.

Series

An object that represents one imaging series.

SeriesSize

An object that represents set of total byte size and object count filtered by query key SeriesInstanceUID.

Image

An object that represents set of images in zip file based on SeriesInstanceUID.

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:

Click Here to see the test data that has been loaded on these test servers have the following test data