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.
Info |
---|
title | 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.
|
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/.
Info |
---|
icon | false |
---|
title | NBIA Search with Authentication REST API Query Structure |
---|
|
Code Block |
---|
<YOUR_ACCESS_TOKEN><BaseURL><Resource><QueryEndpoint>?<QueryParameters> |
|
For example, the API call below requests all modality values for the TCGA-BRCA collection.
Info |
---|
icon | false |
---|
title | Example NBIA Search with Authentication REST API Query |
---|
|
Code Block |
---|
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.
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.
Note |
---|
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. |
+---------+ +---------------+
| | | |
| |>--(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.
Code Block |
---|
title | 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.
Code Block |
---|
title | 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.
Code Block |
---|
title | 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.
Code Block |
---|
title | 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.
Code Block |
---|
title | Sample Request for Refreshing the Token |
---|
|
# Request for refreshing the token
curl -X -v -d "username=USERNAME&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.
Code Block |
---|
|
{"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.
Code Block |
---|
title | 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:
Code Block |
---|
title | 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 |
Code Block |
---|
|
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://nlst.cancerimagingarchive.net/nbia-api/services/getBodyPartValuesAndCounts?Modality=PT" |
Excerpt Include |
---|
| NBIA Search REST API Guide |
---|
| NBIA Search REST API Guide |
---|
nopanel | true |
---|
|
Return Values
This section lists and explains the return values of the APIs included in both tables above.
Note |
---|
If the value for an attribute is not populated in the specified collection, it will not appear in the returned values. |
Table of Content Zone |
---|
|
getBodyPartValues Code Block |
---|
| curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getBodyPartValues" |
Attribute | DICOM Tag | Description |
---|
BodyPartExamined | 0018, 0015 | Standard DICOM definition |
getCollectionValues Code Block |
---|
| curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getCollectionValues" |
Attribute | DICOM Tag | Description |
---|
Collection | N/A | 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. |
getContentsByName Code Block |
---|
| 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" |
Attribute | DICOM Tag | Description |
---|
SeriesInstanceUID | 0020, 000E | Has been de-identified as part of submission process | StudyInstanceUID | 0020, 000D | 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. | SeriesDate | 0008, 0021 | Standard DICOM definition | SeriesDescription | 0008, 103E | Standard DICOM definition. Has been inspected and cleaned of any PHI. | BodyPartExamined | 0018, 0015 | Standard DICOM definition | SeriesNumber | 0020, 0011 | Standard DICOM definition | Collection | N/A | 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. | PatientID | 0010, 0020 | Has been de-identified as part of submission process. | Manufacturer | 0008, 0070 | Standard DICOM definition | ManufacturerModelName | 0008, 1090 | Standard DICOM definition | SoftwareVersions | 0018, 1020 | Standard DICOM definition | ImageCount | N/A | Number of images in the specified series |
getImageThe license file, which includes the data usage agreement, is included in the returned ZIP file. Code Block |
---|
| 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" |
Attribute | DICOM Tag | Description |
---|
N/A | N/A | Set of images in a ZIP file |
getImageWithMD5Hash Code Block |
---|
| 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/A | N/A | Set of images in a ZIP file |
getManufacturerValues Code Block |
---|
| 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 Code Block |
---|
| curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValues" |
Attribute | DICOM Tag | Description |
---|
Modality | 0008, 0060 | Standard DICOM definition |
getNewPatientsInCollection Code Block |
---|
| curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/NewPatientsInCollection?Collection=CBIS-DDSM&Date=2010/08/16" |
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. | Collection | N/A | 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. | Phantom | 0010, 0200 | Indicates whether or not the subject is a quality control phantom. | SpeciesCode | 0010,2202 | The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient. | SpeciesDescription | 0010,2201 | The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient. |
getNewStudiesInPatientCollection Code Block |
---|
| curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/NewStudiesInPatientCollection?Collection=CBIS-DDSM&Date=2010/08/16" |
Attribute | DICOM Tag | Description |
---|
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 | 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 as part of submission process. | PatientSex | 0010, 0040 | Standard DICOM definition | EthnicGroup | 0010, 2160 | Standard DICOM definition | Collection | N/A | 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. | SeriesCount | N/A | Computed number of series | LongitudinalTemporalEventType | 0012, 0053 | The type of event to which Longitudinal Temporal Offset from Event (0012,0052) is relative. | LongitudinalTemportalOffsetFromEvent | 0012, 0052 | An 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 Code Block |
---|
| curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getPatient" |
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 as part of submission process. | PatientSex | 0010, 0040 | Standard DICOM definition | EthnicGroup | 0010, 2160 | Standard DICOM definition | Collection | N/A | 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. | Phantom | 0010, 0200 | Indicates whether or not the subject is a quality control phantom. | SpeciesCode | 0010,2202 | The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient. | SpeciesDescription | 0010,2201 | The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient. |
getPatientByCollectionAndModality Code Block |
---|
| curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getPatientByCollectionAndModality?Collection=VICTRE&Modality=MG" |
Attribute | DICOM Tag | Description |
---|
PatientId | 0010, 0020 | A list of patient IDs for a specified collection and modality |
getPatientStudy Code Block |
---|
| curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getPatientStudy" |
Attribute | DICOM Tag | Description |
---|
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 | 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 | N/A | 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. | SeriesCount | N/A | Computed number of series | LongitudinalTemporalEventType | 0012, 0053 | The type of event to which Longitudinal Temporal Offset from Event (0012,0052) is relative. | LongitudinalTemporalOffsetFromEvent | 0012, 0052 | An 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 Code Block |
---|
| curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getSeries |
Attribute | DICOM Tag | Description |
---|
SeriesInstanceUID | 0020, 000E | Has been de-identified as part of submission process | StudyInstanceUID | 0020, 000D | 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. | SeriesDate | 0008, 0021 | Standard 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 | SeriesNumber | 0020, 0011 | Standard DICOM definition | AnnotationsFlag | N/A | Indicates if there are annotations for a collection | Collection | N/A | 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. | PatientID | 0010, 0020 | Has been de-identified as part of submission process | Manufacturer | 0008, 0070 | Standard DICOM definition | ManufacturerModelName | 0008, 1090 | Standard DICOM definition | SoftwareVersions | 0018, 1020 | Standard DICOM definition | ImageCount | N/A | Computed number of images in this series | TimeStamp | N/A | Date the series was released | LicenseName | N/A | License that applies to this series | LicenseURI | N/A | URL of license source | CollectionURI | N/A | URI of collection | FileSize | N/A | File size |
Code Block |
---|
| 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" |
Attribute | DICOM Tag | Description |
---|
Series UID | 0020, 000E | Standard DICOM definition | Collection | N/A | 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. | 3rd Party Analysis | N/A | Data from third-party analysis results | Data Description URI | N/A | Location of the data description | Subject ID | N/A | Unique identifier for the subject | Study UID | 0020, 000D | Standard DICOM definition | Study Description | 0008, 1030 | Institution-generated description or classification of the Study (component) performed | Study Date | 0008, 0020 | Has been de-identified as part of submission process. Longitudinal information is preserved. | Series Description | 0020, 0011 | Standard DICOM definition. Has been inspected and cleaned of any PHI. | Manufacturer | 0008, 0070 | Standard DICOM definition | Modality | 0008, 0060 | Standard DICOM definition | SOP Class UID | N/A | Unique identifier of the SOP Class | Number of Images | N/A | Number of images in this series | File Size | N/A | File size in bytes | File Location | N/A | Location of the file in the file system | Series Number | 0020,0011 | Standard DICOM definition | License Name | N/A | License that applies to this series | License URL | N/A | URL of license source | Annotation Size | N/A | Size of annotation files in bytes |
getSeriesSize Code Block |
---|
| 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" |
Attribute | DICOM Tag | Description |
---|
TotalSizeInBytes | N/A | Byte size of the specified series | ObjectCount | N/A | Number of objects in the specified series |
getSingleImage Code Block |
---|
| 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" |
Attribute | DICOM Tag | Description |
---|
N/A | N/A | Single image in DICOM format |
getSOPInstanceUIDs Code Block |
---|
| 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" |
Attribute | DICOM Tag | Description |
---|
SOPInstanceUID | 0008, 0018 | Uniquely identifies the SOP Instance |
getUpdatedSeries Code Block |
---|
curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getUpdatedSeries?fromDate=01/01/2020" |
Attribute | DICOM Tag | Description |
---|
SeriesInstanceUID | 0020, 000E | Has been de-identified as part of submission process | StudyInstanceUID | 0020, 000D | 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. | SeriesDate | 0008, 0021 | Standard 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 | SeriesNumber | 0020, 0011 | Standard DICOM definition | AnnotationsFlag | N/A | Indicates if there are annotations for a collection | Collection | N/A | 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. | PatientID | 0010, 0020 | Has been de-identified as part of submission process. | Manufacturer | 0008, 0070 | Standard DICOM definition | ManufacturerModelName | 0008, 1090 | Standard DICOM definition | SoftwareVersions | 0018, 1020 | Standard DICOM definition | ImageCount | N/A | Number of images in the specified series |
|