Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

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:

BaseURLhttps://services.cancerimagingarchive.net/services/v2The BaseURL includes the version number of this API (v2 in this example)
Resource/TCIA 
QueryEndpoint/query/getPatientStudy 
Query ParametersCollection=TCGA-GBM
PatientID=GBM-0123
 
Formatformat=csvSome 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: 

      TCIA BaseURL
      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

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.

ResourceResourceURLQueryMetadata QueryDescription
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.

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

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

NA

NA

NA

 

 

getModalityValues

Set of all modality values (CT, MR, ...) filtered by query keys

CSV/HTML/XML/JSON

Collection (O)

BodyPartExamined (O)

Modality (O)

NA

 

 

getBodyPartValues

Set of all body part names filtered by query keys

CSV/HTML/XML/JSON

Collection (O)

BodyPartExamined (O)

Modality (O)

NA

 

 

getManufacturerValues

Set of all manufacturer names filtered by query keys

CSV/HTML/XML/JSON

Collection (O)

BodyPartExamined (O)

Modality (O)

NA

 

 

getPatientSet of patient objects filtered by query keysCSV/HTML/XML/JSONCollection (O)NANANa  

getPatientStudy

Set of patient/study objects filtered by query keys

CSV/HTML/XML/JSON

Collection (O)

PatientID (O)

StudyInstanceUID (O)

NA

 

 

getSeries

Set of series objects filtered by query keys

CSV/HTML/XML/JSON

Collection (O)

PatientID (O)

StudyInstanceUID (O)

Modality (O)

 

 

getSeriesSizeSet of total byte size and object count filtered by query keyCSV/HTML/XML/JSONSeriesInstanceUID (R)

NA

NA

NA

  

getImage

Set of images in a zip file

ZIP

SeriesInstanceUID (R)

NA

NA

NA

 

 

Return Values

Collection

An object that represents Collection (project) values.

AttributeDICOM TagDescription
CollectionNA

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.

AttributeDICOM TagDescription
Modality0008 0060Standard DICOM definition

BodyPartExamined

An object that represents BodyPartExamined values.

AttributeDICOM TagDescription
BodyPartExamined0018 0015Standard DICOM definition

Manufacturer

An object that represents Manufacturer values.

AttributeDICOM TagDescription
Manufacturer0008 0070Standard 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

CollectionNAA label used to name a set of images collected for a specific trial or other reason.
Assigned during the process of curating the data.
 PatientStudy

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

Attribute

DICOM Tag

Description

StudyInstanceUID0020 000DHas been de-identified as part of submission process.
StudyDate0008 0020Has been de-identified as part of submission process. Longitudinal information is preserved.
StudyDescription0008 1030Standard DICOM definition. Has been inspected and cleaned of any PHI
AdmittingDiagnosesDescription0008 1080Standard DICOM definition. Has been inspected and cleaned of any PHI
StudyID0020 0010Has been de-identified as part of submission process.
PatientAge0010 1010Standard DICOM definition
PatientID0010 0020

Has been de-identified as part of submission process.

PatientName0010 0010Has 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

CollectionNA

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.

SeriesCountNAComputed 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.
StudyInstanceUID0020 000DHas been de-identified as part of submission process.

Modality

0008 0060

Standard DICOM definition

ProtocolName0018 1030Standard DICOM definition. Has been inspected and cleaned of any PHI
SeriesDate0008 0021Standard DICOM definition

SeriesDescription

0008 103E

Standard DICOM definition. Has been inspected and cleaned of any PHI
BodyPartExamined0018 0015Entered on a per collection basis using relevant SNOMED terms.
SeriesNumber0020 0011Standard DICOM definition
AnnotationsFlagNA 
CollectionNA

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.

PatientID0010 0020Has been de-identified as part of submission process.
Manufacturer0008 0070Standard DICOM definition
ManufacturerModelName0008 1090Standard DICOM definition
SoftwareVersions0018 1020Standard DICOM definition
ImageCountNAComputed number of images in this series.


SeriesSize

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

AttributeDICOM TagDescription
TotalSizeInBytesNATotal byte size per series
ObjectCountNACount of total objects per series

Image

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

AttributeDICOM TagDescription
NANASet 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:

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

 

  • No labels