Purpose of this Guide

The National Biomedical Imaging Archive (NBIA) REST APIs are provided to access the search and download functions used in the TCIA radiology portal.

The NBIA Search REST APIs, described on this page, allow you to perform basic queries on and download data for image analysis from public collections. 

The NBIA Search with Authentication REST APIs, described in the NBIA Search with Authentication REST API Guide, allow you to use the same APIs described on this page to query and download data from restricted collections.

The NBIA Advanced REST APIs, described in the NBIA Advanced REST API Guide, provide advanced features geared towards developers seeking to integrate searching and downloading TCIA data into their own web and desktop applications.    

Run APIs Live on the Cloud

The APIs on this page are available in a Jupyter notebook, which you can use to run the APIs live on the cloud without an account.

NBIA Search REST API URL and Format

A call includes a base URL followed by the API and query parameters, in that order. The base URL to access public data is https://services.cancerimagingarchive.net/nbia-api/services/v1.

For example, in the following URL:

https://services.cancerimagingarchive.net/nbia-api/services/v1/getSeries?Collection=RIDER%20Pilot&PatientID=1.3.6.1.4.1.9328.50.1.0001&StudyInstanceUID=1.3.6.1.4.1.9328.50.1.2&format=csv

  • The base URL is https://services.cancerimagingarchive.net/nbia-api/services/v1/.
  • The API endpoint is getSeries.
  • The four query parameters are provided as follows: Collection=RIDER Pilot&PatientID=1.3.6.1.4.1.9328.50.1.0001&StudyInstanceUID=1.3.6.1.4.1.9328.50.1.2&format=csv
  • Data can be obtained in the following formats: CSV, HTML, XML, and JSON.
  • The order in which the query parameters are provided does not matter.  
  • NBIA Search REST APIs can only access public data.  If you want to use these APIs to access restricted collections, see NBIA Search with Authentication REST API Guide.

Image Download APIs

Use the APIs in the following table to download images from TCIA. 

Query Name

Return Values

Output Format

Query Parameters

Usage

getImage

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

The naming scheme for the NewFileNames parameter changes from sequential numbers to acquisition number - instance number (in correct order).

API example and return values for getImage

ZIP

SeriesInstanceUID (R)

NewFileNames (O) - Accepted values are Yes and No.

Used for bulk transfer of all images in a series.

getImageWithMD5Hash

All images in the series and MD5 hash values

API example and return values for getImageWithMD5Hash

ZIPSeriesInstanceUID (R)Used for bulk transfer of images with the ability to check MD5Hash.

getSingleImage

A single DICOM Object that is identified by its SeriesInstanceUID and SOPInstanceUID. This API will always be used following the getSOPInstanceUIDs.

API example and return values for getSingleImage

Raw DICOM Object

SeriesInstanceUID (R)

SOPInstanceUID (R)

Used to retrieve a single image.

Image Metadata APIs

Use the APIs in the following table to explore the metadata of objects in the TCIA database. Queries return a file in one of these data formats: CSV, HTML, XML, and JSON. 

Query Name

Return Values

Output Format

Query Parameters

getBodyPartValues

Set of all body part names filtered by query keys

API example and return values for getBodyPartValues

CSV/HTML/XML/JSON

Collection (O)

Modality (O)

getCollectionValues

Set of all collection names

API example and return values for getCollectionValues

CSV/HTML/XML/JSON

None

getContentsByName

Return the contents of your cart. To get the name of the cart contents, you must add data to your cart in the TCIA Radiology Portal, and then select Share My Cart. An example of the URL that appears is https://nbia.cancerimagingarchive.net/nbia-search/?saved-cart=nbia-54241629300063058. The cart name is what follows the equal sign, so in this example, the cart name is nbia-54241629300063058.

API example and return values for getContentsByName

CSV/HTML/XML/JSONname (R)

getManufacturerValues

Set of all manufacturer names filtered by query keys

API example and return values for getManufacturerValues

CSV/HTML/XML/JSON

Collection (O)

BodyPartExamined (O)

Modality (O)

getModalityValues

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

API example and return values for getModalityValues

CSV/HTML/XML/JSON

Collection (O)

BodyPartExamined (O)

NewPatientsInCollection

Set of patients, in a specified collection, since a specified date

API example and return values for NewPatientsInCollection

CSV/HTML/XML/JSON

Collection (R)

Date (R)

NewStudiesInPatientCollection 

Set of new studies for given patient and collection since a specified date

API example and return values for NewStudiesInPatientCollection

CSV/HTML/XML/JSON

Collection (R)

Date (R)

PatientID (R)

getPatient

Set of patient objects filtered by query keys

API example and return values for getPatient

CSV/HTML/XML/JSON

Collection (O)

getPatientByCollectionAndModality

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

API example and return values for getPatientByCollectionAndModality

CSV/HTML/XML/JSON

Collection (R)

Modality (R)

getPatientStudy

Set of patient/study objects filtered by query keys

API example and return values for getPatientStudy

CSV/HTML/XML/JSON

Collection (R)

PatientID (O)

StudyInstanceUID (O)

getSeries

Set of series objects filtered by query keys

API example and return values for getSeries

CSV/HTML/XML/JSON

Collection (O)

PatientID (O)

StudyInstanceUID (O)

Modality (O)

SeriesInstanceUID (O) 

BodyPartExamined (O

ManufacturerModelName (O)

Manufacturer (O)

getSeriesMetaData

All of the metadata for a given SeriesInstanceUID

API example and return values for getSeriesMetaData

CSV/HTML/XML/JSONSeriesInstanceUID (R)

getSeriesSize

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

API example and return values for getSeriesSize

CSV/HTML/XML/JSONSeriesInstanceUID (R)

getSOPInstanceUIDs

A list of SOPInstanceUIDs for a given series using the SeriesInstanceUID

API example and return values for getSOPInstanceUIDs

CSV/HTML/XML/JSON

SeriesInstanceUID (R)

getUpdatedSeries

Set of series updated since a specified date

API example and return values for getUpdatedSeries

CSV/HTML/XML/JSONfromDate (R)

Return Values

This section lists and explains the return values of the APIs included in both tables above.

If the value for an attribute is null in the specified collection, it will not appear in the returned values.

getBodyPartValues

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getBodyPartValues
AttributeDICOM TagDescription
BodyPartExamined0018, 0015Standard DICOM definition

getCollectionValues

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getCollectionValues
AttributeDICOM TagDescription
CollectionN/AA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.

getContentsByName

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getContentsByName?name=TCIA_TCGA-PRAD_08-09-2016-v3
AttributeDICOM TagDescription

SeriesInstanceUID

0020, 000EHas been de-identified as part of submission process

StudyInstanceUID

0020, 000DHas been de-identified as part of submission process.

Modality

0008, 0060Standard DICOM definition

ProtocolName

0018, 1030Standard DICOM definition. Has been inspected and cleaned of any PHI.

SeriesDate

0008, 0021Standard DICOM definition

SeriesDescription

0008, 103EStandard DICOM definition. Has been inspected and cleaned of any PHI.

BodyPartExamined

0018, 0015Standard DICOM definition

SeriesNumber

0020, 0011Standard DICOM definition

Collection

N/AA 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, 0020Has been de-identified as part of submission process.

Manufacturer

0008, 0070Standard DICOM definition

ManufacturerModelName

0008, 1090Standard DICOM definition

SoftwareVersions

0018, 1020Standard DICOM definition

ImageCount

N/ANumber of images in the specified series

getImage

The license file, which includes the data usage agreement, is included in the returned ZIP file.

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getImage?SeriesInstanceUID=1.3.6.1.4.1.9328.50.1.216116555221814778114703363464001196508
AttributeDICOM TagDescription
N/AN/ASet of images in a ZIP file

getImageWithMD5Hash

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getImageWithMD5Hash?SeriesInstanceUID=1.3.6.1.4.1.14519.5.2.1.6919.4624.313514201353787659031503464798

Attribute

DICOM Tag

Description

N/AN/ASet of images in a ZIP file

getManufacturerValues

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getManufacturerValues

Attribute

DICOM Tag

Description

Manufacturer

0008, 0070

Standard DICOM definition

getModalityValues

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getModalityValues
AttributeDICOM TagDescription
Modality0008, 0060Standard DICOM definition

NewPatientsInCollection

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/NewPatientsInCollection?Collection=CBIS-DDSM&Date=2010/08/16
AttributeDICOM TagDescription
PatientID0010, 0020Has been de-identified as part of submission process.
PatientName0010, 0010Has been de-identified as part of submission process.
CollectionN/AA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.
Phantom0010, 0200Indicates whether or not the subject is a quality control phantom.
SpeciesCode0010,2202The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient.
SpeciesDescription0010,2201The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient.

NewStudiesInPatientCollection 

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/NewStudiesInPatientCollection?Collection=CBIS-DDSM&Date=2010/08/16
AttributeDICOM TagDescription

StudyInstanceUID

0020, 000DHas been de-identified as part of submission process.

StudyDate

0008, 0020Has been de-identified as part of submission process. Longitudinal information is preserved.

StudyID

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

PatientID

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

PatientName

0010, 0010Has been de-identified as part of submission process.

Collection

N/AA 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

N/AComputed number of series

getPatient

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getPatient
AttributeDICOM TagDescription
PatientId0010, 0020Has been de-identified as part of submission process.
PatientName0010, 0010Has been de-identified as part of submission process.
PatientBirthDate0010, 0030Has been de-identified as part of submission process.
PatientSex0010, 0040Standard DICOM definition
EthnicGroup0010, 2160Standard DICOM definition
CollectionN/AA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.
Phantom 0010, 0200Indicates whether or not the subject is a quality control phantom.
SpeciesCode0010,2202The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient.
SpeciesDescription 0010,2201The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient.

getPatientByCollectionAndModality

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getPatientByCollectionAndModality?Collection=VICTRE&Modality=MG
AttributeDICOM TagDescription
PatientId0010, 0020A list of patient IDs for a specified collection and modality

getPatientStudy

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getPatientStudy
AttributeDICOM TagDescription
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, 0020Has been de-identified as part of submission process.
PatientName0010, 0010Has been de-identified as part of submission process.
PatientBirthDate0010, 0030Has been de-identified (emptied) as part of submission process.
PatientSex0010, 0040Standard DICOM definition
EthnicGroup0010, 2160Standard DICOM definition
CollectionN/AA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.
SeriesCountN/AComputed number of series

longitudinalTemporalEventType

0012, 0053The type of event to which Longitudinal Temporal Offset from Event (0012,0052) is relative.
longitudinalTemporalOffsetFromEvent0012, 0052An offset in days from a particular event of significance. May be fractional. In the context of a clinical trial, this is often the days since enrollment, or the baseline imaging Study.

getSeries

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getSeries
AttributeDICOM TagDescription
SeriesInstanceUID0020, 000EHas been de-identified as part of submission process
StudyInstanceUID0020, 000DHas been de-identified as part of submission process
Modality0008, 0060Standard DICOM definition
ProtocolName0018, 1030Standard DICOM definition. Has been inspected and cleaned of any PHI.
SeriesDate0008, 0021Standard DICOM definition
SeriesDescription0008, 103EStandard 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
AnnotationsFlagN/AIndicates if there are annotations for a collection
CollectionN/AA 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
ImageCountN/AComputed number of images in this series
max_TimeStamp (NBIA at TCIA 7.8)N/ALast update to the series

getSeriesMetaData

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getSeriesMetaData?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992
AttributeDICOM TagDescription

Series UID

0020, 000EStandard DICOM definition

Collection

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

Data Description URI

N/ALocation of the data description

Subject ID

N/AUnique identifier for the subject

Study UID

0020, 000DStandard DICOM definition

Study Date

0008, 0020Has been de-identified as part of submission process. Longitudinal information is preserved.

Series Description

0020, 0011Standard DICOM definition. Has been inspected and cleaned of any PHI.

Modality

0008, 0060Standard DICOM definition

SOP Class UID

N/AUnique identifier of the SOP Class

Number of Images

N/ANumber of images in this series

File Size

N/AFile size in bytes

File Location

N/ALocation of the file in the file system

Series Number

0020,0011Standard DICOM definition

License Name

N/ALicense that applies to this series

License URL

N/AURL of license source

Annotation Size

N/ASize of annotation files in bytes

getSeriesSize

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getSeriesSize?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992
AttributeDICOM TagDescription

TotalSizeInBytes

N/AByte size of the specified series

ObjectCount

N/ANumber of objects in the specified series

getSingleImage

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getSingleImage?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992&SOPInstanceUID:1.3.6.1.4.1.9590.100.1.2.289923739312470966435676008311959891294
AttributeDICOM TagDescription
N/AN/ASingle image in DICOM format

getSOPInstanceUIDs

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getSOPInstanceUIDs?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992


AttributeDICOM TagDescription
SOPInstanceUID0008, 0018Uniquely identifies the SOP Instance

getUpdatedSeries

Sample Call
https://services.cancerimagingarchive.net/nbia-api/services/v1/getUpdatedSeries?fromDate=01/01/2020
AttributeDICOM TagDescription

SeriesInstanceUID

0020, 000EHas been de-identified as part of submission process

StudyInstanceUID

0020, 000DHas been de-identified as part of submission process

Modality

0008, 0060Standard DICOM definition

ProtocolName

0018, 1030Standard DICOM definition. Has been inspected and cleaned of any PHI.

SeriesDate

0008, 0021Standard DICOM definition

SeriesDescription

0008, 103EStandard DICOM definition. Has been inspected and cleaned of any PHI.

BodyPartExamined

0018, 0015Entered on a per collection basis using relevant SNOMED terms

SeriesNumber

0020, 0011Standard DICOM definition

Collection

N/AA 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, 0020Has been de-identified as part of submission process.

Manufacturer

0008, 0070Standard DICOM definition

ManufacturerModelName

0008, 1090Standard DICOM definition

SoftwareVersions

0018, 1020Standard DICOM definition

ImageCount

N/ANumber of images in the specified series
  • No labels