Panel | ||||
---|---|---|---|---|
|
What's New
In August 2023, the following APIs were added to this guide.
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 Rdiology Portal.
The NBIA Advanced REST APIs, described on this page, provide capabilities to access restricted collections, which require login authentication. They also provide advanced features that are geared towards developers seeking to integrate searching and downloading TCIA data into their own web and desktop applications.
For information about creating basic queries and downloading data for image analysis, refer to the NBIA Search REST API Guide and NBIA Search with Authentication REST API Guide.
NBIA Advanced REST API Base URL, Format, and Return Values
Access to any NBIA Advanced 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.
Note | ||
---|---|---|
| ||
To access National Lung Screening Trial (NLST) data, get the authentication token from https://nlst.cancerimagingarchive.net/nbia-api/oauth/token, then use https://nlst.cancerimagingarchive.net/nbia-api/services/ to make REST API calls. |
Info | ||||
---|---|---|---|---|
| ||||
|
For example, the API shown below requests all Body Part Values and Counts for the PT modality.
Info | ||||
---|---|---|---|---|
| ||||
|
We can break this down as follows.
Object | Example |
---|---|
Access Token | cd2b2895-85d0-49c5-bd75-804f162da942 |
BaseURL | |
Resource | /nbia-api/services |
Endpoint | getBodyPartValuesAndCounts |
Query Parameters | Modality=PT |
Note |
---|
If the value for an attribute is not populated in the specified collection, it will not appear in the returned values. |
All APIs return results in JSON format except for the Thumbnail API (JPG), Manifest Text API (TXT), and Series Metadata API (CSV).
Secure Access to NBIA REST Services
Access to any NBIA Advanced REST 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 NBIA Advanced 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 Advanced REST API, you must request a token to use with restricted data. This token will expire in two hours and you can refresh it. Refer to REST Advanced REST APIs for example calls.
Requesting a Token to Use with Restricted Data
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 | ||
---|---|---|
| ||
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 |
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=your TCIA username
- password=your TCIA password
The service responds with access token details and expiration information.
- access_token
- expires_in
- refresh_expires_in
- refresh_token
- not-before-policy
- session_state
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.
Requesting a Token to Use with Public Data
If you don't have a TCIA account and want to test an API on this page, you can access public data using the NBIA guest account with no password, as follows.
Code Block | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
{"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 | ||
---|---|---|
| ||
# 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
The time it takes tokens to expire is configurable but is currently two hours. You can refresh your access token for an additional two hours by passing the refresh token from your original token request.
Code Block | ||
---|---|---|
| ||
# 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 | ||
---|---|---|
| ||
# 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.
REST Advanced REST APIs
The TCIA Radiology Portal’s search features use the following Advanced REST APIs.
If the value for an attribute is null in the specified collection, it will not appear in the returned values.
Table of Content Zone | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Body Part Values and Counts APIThe Body Part Values and Counts API returns the modality values and body part count for the modality. It optionally takes the following parameters.
Example Body Part Values and Counts Query
Sample Results The API returns the body parts and their counts.
Collection DescriptionsThis API takes a collection name and returns the collection's description. The API takes one parameter:
Example getCollectionDescriptions Query
If successful, the API returns the collection description.
Collection or Series for DOIThe Collection or Series for DOI API returns the collection and/or series with the Digital Object Identifier (DOI). It does not take any parameters. Example getCollectionOrSeriesForDOI Query
Collection Values and CountsThe Collection Values and Counts API returns the collections and the subject count for the collection. Example Collection Values And Counts Query
The API returns the collections with their counts.
Create Saved Cart APIThe Create Saved Cart API allows the creation of a saved cart. The API takes four arguments:
Example Create Saved Cart Query
DICOM Metadata by Series UID APIThe DICOM Metadata by Series UID API provides the functionality in the portal where the DICOM data is retrieved from a series. The API takes one argument:
The SeriesUID is available from the Drill Down API call. Example Metadata Query
The API sends back triples of all DICOM element, name, data in the file.
Extended Simple Search with Modality and Body Part Paged APIThe Extended Simple Search with Modality and Body Part Paged API is used to run queries for the Simple Search GUI in the NBIA client. This API uses a variety of criteria as seen in the NBIA client, as well as the pages of data the client requests. The available criteria types and their components follow. Since the simple search can take an unlimited number of criteria each of the criteria items is appended with a number signifying its order in the query, starting with 0.
Example Extended Simple Search with Modality and Body Part Paged Query
The API returns the results of the search.
Image with MD5 Hash APIThis API takes a series UID and returns a zip file with the images and a CSV file containing the MD5 hashes. The API takes two arguments:
Example Image with MD5 Hash Query
The API returns the images and a CSV file in the zip file that records the file name and a hash. Manifest for Simple Search APIThe Manifest Text for Simple Search API allows the creation of a manifest file that can be used to execute the NBIA Data Retriever. The API takes the same arguments as the Simple Search GUI. Example Manifest for Simple Search Query
The API returns text that can be used as a manifest file for the NBIA Data Retriever.
Manifest Text APIThe Manifest Text API allows the creation of a manifest file that can be used to execute the NBIA Data Retriever. The API takes two arguments:
Example Manifest Query
The API returns text that can be used as a manifest file for the NBIA Data Retriever.
Manifest for Text SearchThis API takes a text value and generates a manifest file of series. This is an API version of the text search in the NBIA Radiology Portal GUI. See Performing a Text Search for more information. This API takes the following parameter:
Example getManifestForTextSearch Query
Manifest from Patient Study SeriesThis API takes a a parameter and generates a manifest file of patient IDs that match those parameters. This API takes the following parameters:
Example getManifestFromPatientStudySeries Query
If successful, the API returns the following.
MD5 HierarchyThis API takes the following parameters:
Example getMD5Hierarchy Query
Manufacturer Values and Counts APIThe Manufacturer Values and Counts API returns the modality values plus the manufacturer count for the modality. It optionally takes the following parameters.
Example getManufacturerValuesAndCounts Query
The API returns the manufacturer and their counts.
MD5 Hash for Image APIGenerates an MD5 Hierarchy for a given Collection, PatientID, StudyInstanceUID, or SeriesInstanceUID, which can be compared to a previously generated hierarchy to determine if any changes have occurred to the data. The API takes one argument:
Example MD5 Hash for Image Query
The API returns the MD5 hash. Modality Values and Counts APIThe Modality Values and Counts API returns the modality values plus the subject count for the modality. It optionally takes the following parameters.
Example Modality Values and Counts Query
The API returns the modalities and their counts.
Restrictions for Simple Search APIThe Restrictions on Simple Search API returns whether any series returned by simple search has commercial restrictions. The API takes the same parameters as the Simple Search GUI. Example getRestrictionsForSimpleSearch Query
The API returns "Yes" if there are commercial restrictions and "No" if there are not. Series Metadata APIThe Series Metadata API allows returns the metadata needed by the client for a set of series as CSV. The API takes one argument:
Example Series Metadata Query
The API returns ok if successful, and the error if one occurs.
Species Tax APIThe Species Tax API returns the species taxonomy and takes no parameters. Example Species Tax Query
The API returns the current species taxonomy.
Species Values And Counts APIThe Get Species Values And Counts API returns the values and counts for species and takes the same parameters as the Simple Search GUI. Example Species Values And Counts Query
The API returns the values and counts for species.
Study Drill Down With Series IDs APIThe Study Drill Down API provides the functionality in the portal where the user drills down to the studies and series associated with a given user. The API takes a list of series to query, using the parameter "list," that is repeated for each series instance UIDs you want to retrieve. Example Study Drill Down With Series IDs Query
The Study Drill Down With Series Ids API returns JSON with the information to populate the drill down to study screen. There can be multiple studies.
Thumbnail APIThe Get Thumbnail API returns the DICOM tags and values associated with the image.
Example Thumbnail Query
The API returns a JPG thumbnail. Text Search APIThe text search API is used to run queries for Text Search in the portal. The text search takes an argument, textValue. Example Text Search Query
Note that the returned JSON now includes the "hit" that was found by the Solr search engine.
Updated Series APIThis API returns the series that have been updated since a given date. The API takes one argument:
Example Get Updated Series Query
The API returns the updated series.
|