Page History

Summary

This document describes v2 v3 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 cancerimagingarchive@mail.nih.gov 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:APIs.

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 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 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
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 Since the API-KEY be sent via HTTP headers.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 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 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/

...

v3/TCIA/query/getPatientStudy?Collection=TCGA-GBM&PatientID=GBM-0123&format=csv
This can be broken down as follows:

BaseURL	https://services.cancerimagingarchive.net/services/

v2

v3	The BaseURL includes the version number of this API (

v2

v3 in this example)
Resource	/TCIA


QueryEndpoint	/query/getPatientStudy


Query Parameters	Collection=TCGA-GBM & PatientID=GBM-0123


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.

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:
  Code Block
  language text
  title TCIA BaseURL
  https://services.cancerimagingarchive.net/services/v2

Coding examples and a SDK (in Python & Java) can be found on here
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.

...

For example, in the following URL:

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

...

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.

Resource	ResourceURL	Query
TCIA	/TCIA/query
		/getPatient
SharedList	/SharedList/query	/ContentsByName

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:

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

...

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

Query Name

Return Values

Output Format

Query Key 1

Query Key 2

Query Key 3

Query Key 4

Query Key 5

Query Key 6

getCollectionValues

Set of all collection names

CSV/HTML/XML/JSON

NA

getModalityValues

Resource	QueryEndpoint	Query Parameters All query parameters are optional 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

Collection (O)

BodyPartExamined (O)

getBodyPartValues

Modality (O)

NA

Set of all body part names filtered by query keys
	/query/getManufacturerValues	Collection / Modality / BodyPartExamined	CSV/HTML/XML/JSON

Collection (O)

BodyPartExamined (O)

Modality (O)

NA

getManufacturerValues

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/PatientsByModality	Collection (

O

R)

BodyPartExamined (O)

Modality (

O

R)

NA

getPatientSet of patient objects filtered by query keys

CSV/HTML/XML/JSON

Collection (O)NANANa

Returns a list of PatientIDs, given a specific Collection Name and Modality
	/query/getPatientStudy	Collection / PatientID / StudyInstanceUID	CSV/HTML/XML/JSON

getPatientStudy

Set of patient/study objects filtered by query keys

CSV

/

HTML

query/

XML/JSON

getSeries

Collection

(O)

PatientID (O)

StudyInstanceUID (O)

NA

getSeries

/ StudyInstanceUID / PatientID / SeriesInstanceUID / Modality / BodyPartExamined / ManufacturerModelName / Manufacturer	CSV/HTML/XML/JSON	Set of series objects filtered by query keys
	/query/getSeriesSize	SeriesInstanceUID (R)	CSV/HTML/XML/JSON

Collection (O)

PatientID (O)

StudyInstanceUID (O)

Modality (O)

getSeriesSize

Set of total byte size and object count filtered by query key

CSV

/

HTML

query/

XML/JSONgetImage

getImage

SeriesInstanceUID (R)

NA

ZIP	Set of images in a zip file

ZIP

/query/NewPatientsInCollection

Date

SeriesInstanceUID

(R)

NA

...

Collection

...

An object that represents Collection (project) values.

Attribute	DICOM Tag	Description
Collection	NA	A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.

Modality

An object that represents Modality values.

Attribute	DICOM Tag	Description
Modality	0008 0060	Standard DICOM definition

BodyPartExamined

An object that represents BodyPartExamined values.

Attribute	DICOM Tag	Description
BodyPartExamined	0018 0015	Standard DICOM definition

Manufacturer

An object that represents Manufacturer values.

Attribute	DICOM Tag	Description
Manufacturer	0008 0070	Standard DICOM definition

Patient

An object that represents one patient.

Attribute	DICOM Tag	Description
PatientID	0010 0020	Has been de-identified as part of submission process.
PatientName	0010 0010	Has been de-identified as part of submission process.
PatientBirthDate	0010 0030	Has been de-identified (emptied) as part of submission process.
PatientSex	0010 0040	Standard DICOM definition
EthnicGroup	0010 2160	Standard DICOM definition
Collection	NA	A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.

Expand

title	PatientStudy

An object that represents one DICOM imaging study performed on one patient.

Attribute	DICOM Tag	Description
StudyInstanceUID	0020 000D	Has been de-identified as part of submission process.
StudyDate	0008 0020	Has been de-identified as part of submission process. Longitudinal information is preserved.
StudyDescription	0008 1030	Standard DICOM definition. Has been inspected and cleaned of any PHI
AdmittingDiagnosesDescription	0008 1080	Standard DICOM definition. Has been inspected and cleaned of any PHI
StudyID	0020 0010	Has been de-identified as part of submission process.
PatientAge	0010 1010	Standard DICOM definition
PatientID	0010 0020	Has been de-identified as part of submission process.
PatientName	0010 0010	Has been de-identified as part of submission process.
PatientBirthDate	0010 0030	Has been de-identified (emptied) as part of submission process.
PatientSex	0010 0040	Standard DICOM definition
EthnicGroup	0010 2160	Standard DICOM definition
Collection	NA	A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.
SeriesCount	NA	Computed number of series.

Series

An object that represents one imaging series.

Attribute	DICOM Tag	Description
SeriesInstanceUID	0020 000E	Has been de-identified as part of submission process.
StudyInstanceUID	0020 000D	Has been de-identified as part of submission process.
Modality	0008 0060	Standard DICOM definition
ProtocolName	0018 1030	Standard DICOM definition. Has been inspected and cleaned of any PHI
SeriesDate	0008 0021	Standard DICOM definition
SeriesDescription	0008 103E	Standard DICOM definition. Has been inspected and cleaned of any PHI
BodyPartExamined	0018 0015	Entered on a per collection basis using relevant SNOMED terms.
SeriesNumber	0020 0011	Standard DICOM definition
AnnotationsFlag	NA
Collection	NA	A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.
PatientID	0010 0020	Has been de-identified as part of submission process.
Manufacturer	0008 0070	Standard DICOM definition
ManufacturerModelName	0008 1090	Standard DICOM definition
SoftwareVersions	0018 1020	Standard DICOM definition
ImageCount	NA	Computed number of images in this series.

...

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

Attribute	DICOM Tag	Description
TotalSizeInBytes	NA	Total byte size per series
ObjectCount	NA	Count of total objects per series

Image

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

Attribute	DICOM Tag	Description
NA	NA	Set of images in a zip file

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:

...

(R)	CSV/HTML/XML/JSON	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
	/query/NewStudiesInPatientCollection	Date (R) Collection (R) PatientID	CSV/HTML/XML/JSON	Returns a set of Studies that have been added to a specified collection, and optionally to a patient since a specified date Date is specified as (YYYY-MM-DD) Use the getCollectionValues to get the list of available collections
	/query/getSOPInstanceUIDs	SeriesInstanceUID (R)	CSV/HTML/XML/JSON	Return a list of SOPInstanceUID for a given series using the SeriesInstanceUID
	/query/getSingleImage	SeriesInstanceUID (R) SOPInstanceUID (R)	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
/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:

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

The returned metadata conforms to the following JSON schema

...

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/

...

v3/TCIA/query

...

/getPatientStudy/metadata

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

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

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

...

Space shortcuts

Child pages

Versions Compared

Old Version 10

New Version 42

Key

Summary

What's new

Getting Started with the TCIA API

Getting Started with the TCIA API

API Reference

Return Types

Incorporating the TCIA Programmatic Interface into Your Application

REST API URL and Format

REST API Directory

Modality

BodyPartExamined

Manufacturer

Patient

Series

Image

Testing the API

API Metadata

Return Values