Purpose of this Guide

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

The NBIA Search with Authentication REST APIs, described on this page, allow you to perform basic queries on and download data for image analysis from public and restricted collections. This guide explains how to authenticate yourself by requesting a token and then using that token to query and download data from restricted collections.

Other NBIA REST APIs

  • If you do not require access to restricted collections you can use the NBIA Search REST API Guide, which provides the same functionality, but does not require requesting a security token.
  • The NBIA Advanced REST API Guide provides advanced features geared towards developers seeking to integrate searching and downloading TCIA data into their own web and desktop applications.

NBIA Search with Authentication REST API Base URL, Format, and Return Values

Access to any NBIA Search with Authentication REST API requires an access token.  If you want to access restricted collections, the TCIA Help Desk must give your user account permission to access them. 

The full API for data consists of a base URL followed by the API and query parameters, in that order. The base URL to access NBIA Advanced REST API data is https://services.cancerimagingarchive.net/nbia-api/services/v2/

NBIA Search with Authentication REST API Query Structure

<YOUR_ACCESS_TOKEN><BaseURL><Resource><QueryEndpoint>?<QueryParameters>

For example, the API call below requests all modality values for the TCGA-BRCA collection.

Example NBIA Search with Authentication REST API Query

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValues?Collection=TCGA-BRCA"

We can break this down as follows.

ObjectExample
Tokencd2b2895-85d0-49c5-bd75-804f162da942
BaseURL

https://services.cancerimagingarchive.net

Resource/nbia-api/services/v2
EndpointgetModalityValues
Query ParametersCollection=TCGA-BRCA

See Image Download APIs and Image Metadata APIs for more information about each NBIA Search with Authentication REST API.

Secure Access to NBIA REST Services

Access to any NBIA Search with Authentication API requires a token that you must requestThis token can then be used on subsequent requests to authorize access to resources. This token will expire in two hours but you can refresh it.

The NBIA REST API supports secure access to private data in the Client Credentials authorization flow with Spring Security and OAuth2. The Client Credentials authorization flow is also known as "signed fetch" or 2-legged OAuth. The following figure illustrates the typical use case for REST API calls made on the web using 2-legged OAuth. For more information regarding the specific workflow, consult the OAuth2 Specification

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(A)- Client Authentication --->| Authorization |
     | Client  |                                  |     Server    |
     |         |<--(B)---- Access Token ---------<|               |
     |         |                                  |               |
     +---------+                                  +---------------+

Figure 1: Client Credentials Flow

Requesting a Token

Access to any NBIA Advanced REST API requires an access token. A request for an access token takes the following structure. Note that USERNAME should be your TCIA username and PASSWORD should be your TCIA password.

Structure of a Request for a Token
curl -X -v -d "username=USERNAME&password=PASSWORD&client_id=NBIA&grant_type=password" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token

If you don't have a TCIA account, you can access public data using the "nbia_guest" account with no password, as follows.

Request a Token to Use with Public Data
curl -X -v -d "username=nbia_guest&password=&client_id=NBIA&grant_type=password" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token

How a Token is Returned/Granted/Given

A successful token request returns a standard access token in JSON format. The value after "access_token" will be longer than this example.

Sample Token Return Value
{"access_token":"cd2b2895-85d0-49c5-bd75-804f162da942","expires_in":7200,"refresh_expires_in":7200,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgO","not-before-policy":0,"session_state":"92a199c6-84ed-48aa-a0d2-059bbb99bc90","scope":"openid profile email"}

Make a note of the access token you received and pass it with the REST service call.

Sample NBIA Advanced REST API Call
# Request for modality values and counts        
    
curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -k "https://services.cancerimagingarchive.net/nbia-api/services/getModalityValuesAndCounts?Collection=LIDC-IDRI"

A successful service request returns the value in a defined format. 

Refreshing the Token

You can refresh your access token for an additional two hours by passing the refresh token from your original token request.

Sample Request for Refreshing the Token
# Request for refreshing the token  

curl -X -v -d  "client_id=nbia&grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN" -X POST -k https://nbia.cancerimagingarchive.net/nbia-api/oauth/token

In the following result, 7200 is the seconds before the token expires.

Sample Return Value
{"access_token":"YOUR_ACCESS_TOKEN","expires_in":7200,"refresh_expires_in":7200,"refresh_token":"YOUR_REFRESH_TOKEN","token_type":"Bearer","id_token":"YOUR_ID_TOKEN","not-before-policy":0,"session_state":"531425b6-425d-44f8-bc74-41200d6803c0","scope":"openid profile email"}

Logging Out

The following is an example request to log out. Logging out invalidates the token you previously requested.

Sample Request to Logout
# Request for logout
 
curl -X -v -d "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/logout"

The request does not return any values.

Accessing the National Lung Screening Trial (NLST) collection

Due to its size, the National Lung Screening Trial (NLST) collection lives on a separate NBIA server. Since this server only holds the public NLST collection, there is no reason to create an API token with your own credentials. To access these data via the Advanced REST API, you must change the URL to obtain the authentication token from https://nlst.cancerimagingarchive.net/nbia-api/oauth/token. You can then use https://nlst.cancerimagingarchive.net/nbia-api/services/ to make REST API calls. In both cases, the beginning of the URL is changed from "services" to "nlst."  Examples of requesting a token and performing an API query are shown below:

Request a Token to Use with Public Data
curl -X -v -d "username=nbia_guest&password=&client_id=NBIA&grant_type=password" -X POST -k https://nlst.cancerimagingarchive.net/nbia-api/oauth/token
Sample Call
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://nlst.cancerimagingarchive.net/nbia-api/services/getBodyPartValuesAndCounts?Modality=PT"

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. JSON is the default return format if no format parameter is specified.

Query Name

Return Values

Query Parameters

getBodyPartValues

Set of all body part names filtered by query keys

API example and return values for getBodyPartValues

Collection (O)

Modality (O)

getCollectionValues

Set of all collection names

API example and return values for getCollectionValues

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

name (R)

getManufacturerValues

Set of all manufacturer names filtered by query keys

API example and return values for getManufacturerValues

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

Collection (O)

BodyPartExamined (O)

NewPatientsInCollection

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

API example and return values for NewPatientsInCollection

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

Collection (R)

Date (R)

PatientID (R)

getPatient

Set of patient objects filtered by query keys

API example and return values for getPatient

Collection (O)

getPatientByCollectionAndModality

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

API example and return values for getPatientByCollectionAndModality

Collection (R)

Modality (R)

getPatientStudy

Set of patient/study objects filtered by query keys

API example and return values for getPatientStudy

Collection (R)

PatientID (O)

StudyInstanceUID (O)

getSeries

Set of series objects filtered by query keys

API example and return values for getSeries

Collection (O)

PatientID (O)

StudyInstanceUID (O)

Modality (O)

SeriesInstanceUID (O) 

BodyPartExamined (O

ManufacturerModelName (O)

Manufacturer (O)

SeriesInstanceUID (O)

getSeriesMetaData

All of the metadata for a given SeriesInstanceUID

API example and return values for getSeriesMetaData

SeriesInstanceUID (R)

getSeriesSize

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

API example and return values for getSeriesSize

SeriesInstanceUID (R)

getSOPInstanceUIDs

A list of SOPInstanceUIDs for a given series using the SeriesInstanceUID

API example and return values for getSOPInstanceUIDs

SeriesInstanceUID (R)

getUpdatedSeries

Set of series updated since a specified date

API example and return values for getUpdatedSeries

fromDate (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 not populated in the specified collection, it will not appear in the returned values.

getBodyPartValues

Sample Call
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getBodyPartValues"
AttributeDICOM TagDescription
BodyPartExamined0018, 0015Standard DICOM definition

getCollectionValues

Sample Call
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getImage?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992"
AttributeDICOM TagDescription
N/AN/ASet of images in a ZIP file

getImageWithMD5Hash

Sample Call
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getManufacturerValues"

Attribute

DICOM Tag

Description

Manufacturer

0008, 0070

Standard DICOM definition

getModalityValues

Sample Call
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValues"
AttributeDICOM TagDescription
Modality0008, 0060Standard DICOM definition

getNewPatientsInCollection

Sample Call
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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.

getNewStudiesInPatientCollection 

Sample Call
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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.

StudyDescription

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

AdmittingDiagnosesDescription

0008, 1080Standard DICOM definition. Has been inspected and cleaned of any PHI.

StudyID

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

PatientAge

0010, 1010Standard DICOM definition

PatientID

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

PatientName

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

PatientBirthDate

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

PatientSex

0010, 0040Standard DICOM definition

EthnicGroup

0010, 2160Standard 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.

SeriesCount

N/AComputed number of series

LongitudinalTemporalEventType

0012, 0053The type of event to which Longitudinal Temporal Offset from Event (0012,0052) is relative.

LongitudinalTemportalOffsetFromEvent

0012, 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.

getPatient

Sample Call
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getPatientByCollectionAndModality?Collection=VICTRE&Modality=MG"
AttributeDICOM TagDescription
PatientId0010, 0020A list of patient IDs for a specified collection and modality

getPatientStudy

Sample Call
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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
TimeStampN/ADate the series was released
LicenseNameN/ALicense that applies to this series
LicenseURIN/AURL of license source
CollectionURIN/AURI of collection
FileSizeN/AFile size

getSeriesMetaData

Sample Call
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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.

3rd Party Analysis

N/AData from third-party analysis results

Data Description URI

N/ALocation of the data description

Subject ID

N/AUnique identifier for the subject

Study UID

0020, 000DStandard DICOM definition

Study Description

0008, 1030Institution-generated description or classification of the Study (component) performed

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.

Manufacturer

0008, 0070Standard DICOM definition

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
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getSOPInstanceUIDs?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992"


AttributeDICOM TagDescription
SOPInstanceUID0008, 0018Uniquely identifies the SOP Instance

getUpdatedSeries

curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/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

AnnotationsFlag

N/AIndicates if there are annotations for a collection

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