Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Panel

Table of Contents
maxLevel2

Summary

Get images in your apps with the new TCIA REST APIImage ModifiedThis document describes 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.

...

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.

...

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

...

  • 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 (note 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: 
BaseURLhttps://services.cancerimagingarchive.net/services/v4The BaseURL includes the version number of this API (v4 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.
  • 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. 

ResourceQueryEndpoint

Query Parameters

All query parameters are
optional unless stated otherwise
 

Format

Description
/TCIA





/query/getCollectionValuesNoneCSV/HTML/XML/JSONSet of all collection names

/query/getModalityValuesCollection / BodyPartExaminedCSV/HTML/XML/JSONSet of all modality values (CT, MR, ...) filtered by query keys

/query/getBodyPartValuesCollection / ModalityCSV/HTML/XML/JSONSet of all body part names filtered by query keys

/query/getManufacturerValuesCollection / Modality /
BodyPartExamined
CSV/HTML/XML/JSONSet of all manufacturer names filtered by query keys

/query/getPatientCollectionCSV/HTML/XML/JSONSet of patient objects filtered by query keys

/query/PatientsByModalityCollection (R)
Modality (R
CSV/HTML/XML/JSON

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


/query/getPatientStudyCollection / PatientID /
StudyInstanceUID
CSV/HTML/XML/JSONSet of patient/study objects filtered by query keys

/query/getSeries

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

CSV/HTML/XML/JSONSet of series objects filtered by query keys

/query/getSeriesSizeSeriesInstanceUID (R)CSV/HTML/XML/JSONSet of total byte size and object count filtered by query key

/query/getImageSeriesInstanceUID (R)ZIPSet of images in a zip file

/query/NewPatientsInCollection

Date (R)
Collection (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 

Please note, there is a bug if you include a Date argument to NewPatientsInCollection under v3 of the API. This was fixed in v4.


/query/NewStudiesInPatientCollectionDate (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/getSOPInstanceUIDsSeriesInstanceUID (R)CSV/HTML/XML/JSON

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


/query/getSingleImageSeriesInstanceUID (R)
SOPInstanceUID (R)
Raw DICOM ObjectReturns a SINGLE DICOM Object that is identified by its SeriesInstanceUID and SOPInstanceUID. This API will always be used following the /getSOPInstanceUIDs
/SharedList




/query/ContentsByNamename (R)JSONGiven the name of a shared list return its contents.

...

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/v4/TCIA/query/getPatientStudy/metadata 

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

...