Child pages
  • TCIA Programmatic Interface (REST API) Usage Guide v1

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

Compare with Current View Page History

« Previous Version 26 Next »

Summary

TCIA is currently in an alpha testing phase of our REST API implementation.  If you are interested in participating in testing the API please contact us at cancerimagingarchive@mail.nih.gov.

REST API URL and Format

This section would benefit from an overview and architecture diagram. The next sections on the API assume you have that understanding.  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&patient_id=1.2.3&study_instance_uid=4.5.6

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

With the exception of the getImage query, all other queries return a comma separated value (CSV) 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 (Available as of 7-Jun-2013)

The query keys in the table below are the literal strings used as keys for key/value pairs to specify query parameters. After each key is an indication if the key is required for the query (R) or optional (O). Omitting optional keys will lead to responses that are more broad.

 For this API, you will be assigned an api_key for your application. You must incude the api_key in a HTTP request header "api_key" when making API calls. Your request will be rejected if you fail to or provide incorrect api_key. You can find code samples using the TCIA API on Github

Query Name

Return Values

Output Format

Query Key 1

Query Key 2

Query Key 3

Query Key 4

Query Key 5

getCollectionValues

Set of all collection names

CSV

 

 

 

 

 

getModalityValues

Set of modality values filtered by query keys

CSV

collection (O)

modality (O)

body_part_examined (O)

 

 

getBodyPartValues

Set of body parts examined filtered by query keys

CSV

collection (O)

modality (O)

body_part_examined (O)

 

 

getPatient

Set of patient objects filtered by query keys

CSV

collection (O)

 

 

 

 

getPatientStudy

Set of patient/study objects filtered by query keys

CSV

collection (O)

patient_id (O)

study_instance_uid (O)

 

 

getSeries

Set of series objects filtered by query keys

CSV

collection (O)

patient_id (O)

study_instance_uid (O)

modality (O)

 

getImage

Set of images in a zip file

ZIP

series_instance_uid (R)

 

 

 

 

REST API Directory (Proposed for Near Future, Subject to Discussion)

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

 

 

 

 

 

 

getModalityValues

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

CSV

Collection (O)

BodyPartExamined (O)

Modality (O)

 

 

 

getBodyPartValues

Set of all body part names filtered by query keys

CSV

Collection (O)

BodyPartExamined (O)

Modality (O)

 

 

 

getManufacturerValues

Set of all manufacturer names filtered by query keys

CSV

collection (O)

modality (O)

body_part (O)

manufacturer (O)

 

 

getPatientSet of patient objects filtered by query keysCSVCollection (O)     

getPatientStudy

Set of patient/study objects filtered by query keys

CSV

collection (O)

modality (O)

body_part (O)

manufacturer (O)

patient_id (O)

study_instance_uid (O)

getSeries

Set of series objects filtered by query keys

CSV

collection (O)

modality (O)

body_part (O)

manufacturer (O)

patient_id (O)

study_instance_uid (O)

getImages

Set of images in a zip file

ZIP

series_instance_uid (R)

 

 

 

 

 

Return Values

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

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.

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

ImageCount

Computed

Number of images in this study

series_in_study

Computed

A count of the number of series in this study (1, 2, 3, ..)

modalities_in_study

Computed

A list of the modalities found in this study (CT, MR, ..)

Series

An object that represents one imaging series.

Attribute

DICOM Tag

Description

PatientID0010 0020Has been de-identified as part of submission process.

StudyInstanceUID

0020 000D

Has been de-identified as part of submission process.

SeriesInstanceUID

0020 000E

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

SeriesDate0008 0021Standard 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.

SeriesNumber0020 0011Standard DICOM definition

Manufacturer

0008 0070

Standard DICOM definition

ManufacturerModelName

0008 1090

Standard DICOM definition

SoftwareVersions

0018 1020

Standard DICOM definition

series_number

0020 0011

Standard DICOM definition

AnnoftationsFlag

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.

ImageCount

Computed

A count of the number of images in this series

  • No labels