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.

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


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


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


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 request. This 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.

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.

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.

{"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.

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

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

{"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.

# 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:

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


curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://nlst.cancerimagingarchive.net/nbia-api/services/getBodyPartValuesAndCounts?Modality=PT"

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

curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getBodyPartValues"


AttributeDICOM TagDescription
BodyPartExamined0018, 0015Standard DICOM definition

getCollectionValues

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

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.

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

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

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

curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValues"


AttributeDICOM TagDescription
Modality0008, 0060Standard DICOM definition

getNewPatientsInCollection

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 

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

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

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

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

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

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

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

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

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