Page History

Summary

...

This document describes

...

the various representational state transfer application programming interface (REST API) implementations that can be used to access TCIA data and resources. The APIs form a RESTful interface, accessed through web URLs.

...

 An application developer

...

does not need to download

...

any software to use the

...

APIs. The application developer can build their own access routines using

...

only the API documentation provided.

...

If you are interested in using the API and have any questions, please contact us at help@cancerimagingarchive.net.

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)

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

• 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

Getting access to the API:

• 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 can be included in the url by adding an extra query parameter api_key or it can be included in the HTTP headers.  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 requests all studies in the TCGA-GBM collection for patient GBM-0123 as CSV (note that in this example, patID is not a valid TCGA-GBM ID and this call will return only column headers).

https://services.cancerimagingarchive.net/services/v4/TCIA/query/getPatientStudy?Collection=TCGA-GBM&PatientID=GBM-0123&format=csv

This can be broken down as follows:

...

Two RESTful interfaces currently exist, as follows:

• The TCIA REST APIs, originally developed using Project Bindaas with Emory University, do not require authentication but only allows access to public collections. The TCIA REST API Guide describes these APIs.  Anyone may use these APIs without asking for an API key or secret, since they only access public collections.
• The National Biomedical Imaging Archive (NBIA) REST APIs power the search and download functions used in the TCIA radiology portal, and allow access to both public and private collections. The NBIA Search REST API Guide describes these APIs. In order to use these APIs, a developer must request a Client ID and Client Secret from the TCIA Help Desk, then use that Client ID and Client Secret to obtain an OAuth2 token. That token must be passed to the server in the http headers of API calls. This process is outlined in the Guide.

The APIs complement the existing web interfaces and can be used in programmatic viewing and analysis applications.

The following guides to the two RESTful interfaces are available:

• TCIA REST API Guide
• NBIA Search REST API Guide

Note that new versions of the APIs may introduce new data types that have not yet been documented. 

If you are interested in using the APIs and have any questions, please contact the TCIA Help Desk. 

• Coding examples and an SDK (in Python & Java) 
• Interface documentation can be found on Mashape. The table below contains the most up-to-date documentation of the API. 
• 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. 

...

Query Parameters

...

Format

...

Returns a list of PatientIDs, given a specific Collection Name and Modality

...

Collection / StudyInstanceUID /
PatientID / SeriesInstanceUID /
Modality / BodyPartExamined /
ManufacturerModelName /
Manufacturer

...

Date (R)
Collection (R) 

...

Returns a set of Patients that have been added to a specified collection since a specified date.
Date is specified as (YYYY-MM-DD).
Use the getCollectionValues to get the list of available collections. 

...

Returns a set of Studies that have been added to a specified collection, and optionally to a patient since a specified date.

...

Return a list of SOPInstanceUID for a given series using the SeriesInstanceUID.

...

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:

• Name of API
• Free text description
• List of Query Parameters
• Supported Return Types
• A description of the returned attributes: Name, DICOM Tag and Description

Or in other words, the query would have the following structure:
<BaseURL><Resource><QueryEndpoint>/metadata

Return Values

...