Skip to end of metadata
Go to start of metadata

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

  1. 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.
  2. 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 authentication token. You must contact the TCIA Help Desk to receive the client_id and client_secret needed to generate a token. The TCIA Help Desk must give your user account permission to access restricted collections. 

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 Search with Authentication REST APIs is https://services.cancerimagingarchive.net/nbia-api/services/v2/

NBIA Search with Authentication REST API Query Structure

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

The credentials you pass differ based on whether the collections include public or restricted data. You must contact the TCIA Help Desk for permission to access private collections and receive the client_id and client_secret values required for RESTful access to those collections. 

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

This flow includes the following steps:

  1. The client authenticates with the authorization server and requests an access token from the token endpoint.
  2. The authorization server authenticates the client, and if valid, issues an access token.

This token can then be used on subsequent requests to authorize access to resources. The REST API server also supports token expiration and extension by refresh. The time it takes tokens to expire is currently two hours but is configurable.

To access TCIA using an NBIA Search with Authentication REST API, you must do the following:

Requesting a Token

Access to any NBIA Search with Authentication REST API requires an authentication token. You must contact the TCIA Help Desk to receive the client_id and client_secret needed to generate a token. 

A request for a token takes the following structure. Refer to the table below for the correct username and password to pass in the call.

Structure of a Request for a Token
username=<username>&password=<password>&client_id=<theClientIDFromHelpDesk>&client_secret=<theClientSecretFromHelpDesk>&grant_type=password" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token


DataUsernamePassword
Public and RestrictedYour usernameYour password
Publicnbia_guestLeave blank

Request a token by interacting with the application in the following way.

  1. The application requests credentials. The credentials you pass are different depending on if you want to access public or restricted data (see above).
  2. The application sends a request to the service using the credentials you provided as a query string for the body. 

    • grant_type=password
    • username
    • password
  3. The service responds with access token details and expiration information.

    • access_token
    • expires_in
    • token_type

    The application makes a request for resources using the returned access token. All APIs listed for accessing public data also support secure access to restricted data with an additional parameter for the access token. 

How a Token is Returned/Granted/Given

A successful token request returns a standard access token in JSON format.

Sample Token Return Value
{"access_token":"f7889076-b3e4-4768-9419-3cd973adda76","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":7199}

Using the Token in an API Call

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

Sample NBIA Search with Authentication REST API Call
# Request for modality values
curl -H "Authorization:Bearer c428d42c-9eed-4f5d-8007-416d46be9b52" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValuesAndCounts?Collection=LIDC-IDRI"

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

Request for Refreshing the Token

The time it takes tokens to expire is configurable but is currently two hours.

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

$ curl -X -v -d "refresh_token=7c2414a1-1f2f-4c9e-82a0-69fcb9fd18ed&client_id=nbiaRestAPIClient&client_secret=ItsBetweenUAndMe&grant_type=refresh_token" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token
        
/nbia-api/oauth/token"

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

Sample Return Value
{"access_token":"bbe4aa2c-7235-41ad-9770-31619d3dbd15","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":119}

Example Request to Logout

Sample Request to Logout
# Request for logout   
      
$ curl -H "Authorization:Bearer caa278aa-e7a9-45b8-a7ec-2c83d4b03cc0" -k "https://services.cancerimagingarchive.net/nbia-api/logout"

Result

Sample Return Value
 You Have Logged Out successfully.

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)

getNewPatientsInCollection

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

API example and return values for getNewPatientsInCollection

CSV/HTML/XML/JSON

Collection (R)

Date (R)

getNewStudiesInPatientCollection 

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

API example and return values for getNewStudiesInPatientCollection

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.

getBodyPartValues

Sample Call
curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getBodyPartValues"
AttributeDICOM TagDescription
BodyPartExamined0018, 0015Standard DICOM definition

getCollectionValues

Sample Call
curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValues"
AttributeDICOM TagDescription
Modality0008, 0060Standard DICOM definition

getNewPatientsInCollection

Sample Call
curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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.

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
curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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
max_TimeStamp (NBIA at TCIA 7.8)N/ALast update to the series

getSeriesMetaData

Sample Call
curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -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.

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
curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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

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