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 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/.
| Info |
|---|
| icon | false |
|---|
| title | NBIA Search with Authentication REST API Query Structure |
|---|
|
| Code Block |
|---|
<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.
| 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. |
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:
- The client authenticates with the authorization server and requests an access token from the token endpoint.
- 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.
| Code Block |
|---|
| title | Structure of a Request for a Token |
|---|
|
curl -d "username=<username>&password=<password>&client_id=<theClientIDFromHelpDesk>&client_secret=<theClientSecretFromHelpDesk>&grant_type=password" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token |
| Data | Username | Password |
|---|
| Public and Restricted | Your username | Your password |
| Public | nbia_guest | Leave blank |
Request a token by interacting with the application in the following way.
- The application requests credentials. The credentials you pass are different depending on if you want to access public or restricted data (see above).
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
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.
| Code Block |
|---|
| title | 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.
| Code Block |
|---|
| title | 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.
| Code Block |
|---|
| title | 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.
| Code Block |
|---|
|
{"access_token":"bbe4aa2c-7235-41ad-9770-31619d3dbd15","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":119} |
Example Request to Logout
| Code Block |
|---|
| title | 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
| Code Block |
|---|
|
You Have Logged Out successfully. |
| 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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 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" |
| Attribute | DICOM Tag | Description |
|---|
| N/A | N/A | Set of images in a ZIP file |
getImageWithMD5Hash| Code Block |
|---|
| 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/A | N/A | Set of images in a ZIP file |
getManufacturerValues| Code Block |
|---|
| 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| Code Block |
|---|
| curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 cd2b2895-85d0-49c5-bd75-804f162da942" -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 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" |
| 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 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" |
| 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 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" |
| Attribute | DICOM Tag | Description |
|---|
| N/A | N/A | Single image in DICOM format |
getSOPInstanceUIDs| Code Block |
|---|
| 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" |
| Attribute | DICOM Tag | Description |
|---|
| SOPInstanceUID | 0008, 0018 | Uniquely identifies the SOP Instance |
getUpdatedSeries| Code Block |
|---|
curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -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 |
|