The following APIs were published in February 2021:
This guide documents the NBIA REST Search APIs released since NBIA at TCIA version 7.5 in April 2020.
The National Biomedical Imaging Archive (NBIA) software is the radiology portal for DICOM images at The Cancer Imaging Archive. This document describes the NBIA’s representational state transfer application programming interfaces (REST API). The APIs are designed for use by image analysis and data mining tools to directly query the public and private resources of the TCIA Radiology Portal and retrieve information into their applications. The API complements the existing web interface but eliminates the need for users to visit the TCIA web pages to select and download images and then upload them into their viewing and analysis applications.
The API is a RESTful interface, accessed through web URLs. There is no software that an application needs to download to use the APIs. The application can build its own access routines using only the API documentation provided here. The interface employs predefined query functions (see NBIA Search REST API Guide v1) that access databases.
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 data is https://services.cancerimagingarchive.net/nbia-api/services.
Access to any NBIA Search 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.
If you want to access restricted collections, the TCIA Help Desk must give your user account permission to access them.
You access a resource by sending an HTTPS request to the NBIA Search API server. The server replies with a response that either contains the data you requested or a status indicator.
An NBIA Search API query takes the following structure:
<Token><BaseURL><Resource><QueryEndpoint>?<QueryParameters> |
For example, the API shown below requests all Body Part Values and Counts for the PT modality.
curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -k "https://services.cancerimagingarchive.net/nbia-api/services/getBodyPartValuesAndCounts?Modality=PT" |
We can break this down as follows.
Object | Example |
---|---|
Token | cd2b2895-85d0-49c5-bd75-804f162da942 |
BaseURL | |
Resource | /nbia-api/services |
Endpoint | getBodyPartValuesAndCounts |
Query Parameters | Modality=PT |
All APIs return results in JSON format except for the NBIA Search REST API Guide v1 (JPG), NBIA Search REST API Guide v1 (TXT), and NBIA Search REST API Guide v1 (CSV).
Access to any NBIA Search 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.
Figure 1: Client Credentials Flow
This flow includes the following steps:
This token can then be used on subsequent requests to authorize access to resources. The NBIA Search REST 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 REST API, you must do the following:
Access to any NBIA Search 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.
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 sends a request to the service using the credentials you provided as a query string for the body.
The service responds with access token details and expiration information.
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.
All public collections are accessible through the nbia_guest account without a password. Do the following to request a token to use when accessing public data.
# Request for token to access public data $ curl -X -v -d "username=nbia_guest&password=&client_id=theClientIDFromHelpDesk&client_secret=theClientSecretFromHelpDesk&grant_type=password" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token |
Most data in TCIA are fully public. However, certain collections require special permissions to access them. To access these collections, you must first register for a TCIA account (be sure to scroll down on this page and click "CLICKING HERE" to accept the terms and conditions) and then contact the TCIA Help Desk for permission to access the restricted data. The TCIA Help Desk will also give you the client_id and client_secret. An example follows that shows how to request NBIA REST services for restricted data.
# Request for token for a specific user to access restricted data $ curl -X -v -d "username=MyUsername&password=MyPassword&client_id=theClientIDFromHelpDesk&client_secret=theClientSecretFromHelpDesk&grant_type=password" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token |
A successful token request returns a standard access token in JSON format.
{"access_token":"f7889076-b3e4-4768-9419-3cd973adda76","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":7199} |
Make a note of the access token you received and pass it with the REST service call.
# Request for modality values $ curl -H "Authorization:Bearer f7889076-b3e4-4768-9419-3cd973adda76" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValues" |
A successful service request returns the value in a defined format. The example of the returned result for the preceding service call is as follows. Note that this result may not represent the full list of modalities in the database and is subject to change.
[{"Modality":"CR"},{"Modality":"CT"},{"Modality":"DX"},{"Modality":"HC"},{"Modality":"HISTOPATHOLOGY"},{"Modality":"MR"},{"Modality":"PR"},{"Modality":"PT"},{"Modality":"RTDOSE"},{"Modality":"RTPLAN"},{"Modality":"RTSTRUCT"},{"Modality":"SC"},{"Modality":"SR"},{"Modality":"US"},{"Modality":"XA"} {"Modality":"CTPT"}{"Modality":"FUSION"}{"Modality":"KO"}{"Modality":"MG"}{"Modality":"REG"}{"Modality":"RWV"}{"Modality":"SEG"}] |
The time it takes tokens to expire is configurable but is currently two hours.
# Request for refreshing the token $ curl -X -v -d "refresh_token=7c2414a1-1f2f-4c9e-82a0-69fcb9fd18ed&client_id=theClientIDFromHelpDesk&client_secret=theClientSecretFromHelpDesk&grant_type=refresh_token" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token |
In the following result, 119
is the seconds before the token expires.
{"access_token":"bbe4aa2c-7235-41ad-9770-31619d3dbd15","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":119} |
# Request for logout $ curl -H "Authorization:Bearer caa278aa-e7a9-45b8-a7ec-2c83d4b03cc0" -k "https://services.cancerimagingarchive.net/nbia-api/logout" |
The result:
You Have Logged Out successfully. |
The TCIA Radiology Portal’s search uses the following REST APIs.
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
The API returns the body parts and their counts.
Collection Values and Counts APIThe 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 NBIA Search REST API Guide v1 call. Example Metadata Query
The API sends back triples of all DICOM element, name, data in the file.
DICOM Tags By Image ID APIThe DICOM Tag By Image ID API returns the DICOM tags and values associated with the image.
The values used in this API can be derived by using the results of the imagePkId in the NBIA Search REST API Guide v1. Example DICOM Tags By Image ID Query
The API returns the tags and values.
Drill Down APIThe Drill Down API provides the functionality in the search client where the user drills down the studies and series associated with a given patient. The API takes a list of series to query, using the parameter "list," that repeats for each series you want to retrieve. During the workflow these values come from the series identifiers in the NBIA Search REST API Guide v1. Example Drill Down Query
The Drill Down API returns JSON with the information to populate the drill down to study screen. There can be multiple studies.
Drill Down Using Series UIDs APIThe Drill Down Using Series UIDs API provides the functionality in the portal where the user drills down the studies and series associated with a set of IDs. In this case, the API takes Series Instance UIDs so the users can access this information outside of the Search Client workflow using any Series Instance UIDs that they are interested in. The API simply takes a list of Series UIDs to query, using the parameter "list," that repeats for each Series UID you want to retrieve. Example Drill Down Using Series UIDs Query
The Drill Down Using Series UIDs API returns JSON with the information to populate the drill down to study screen. You can retrieve multiple studies.
Drill Down to Images APIThe Drill Down to Images API allows the developer to drill down to the images in a series and have the information available to create a WADO call that can retrieve the images themselves. This API is used to create the Thumbnails screen in the portal. The API takes a list of series to query, using the parameter "list," that repeats for each series for which you want to retrieve images. Example Drill Down to Images Query
The API returns the information needed to populate the Thumbnails screen.
The information needed to create a WADO call is the following snippet from this code:
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 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.
The Extended Simple Search with Modality and Body Part Paged API is used to run queries for the Simple Search 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 API 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.
Get Licenses APIThe Get Licenses API retrieves collection descriptions. The API takes no arguments. Example Get Licenses Query
Get Updated Series APIThis API returns the series that have been updated since a given date. The API takes one argument:
Example Get Updated Series API Query
The API returns the updated series.
Manifest APIThe Manifest 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.
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 Manufacturer Values and Counts Query
The API returns the manufacturer and their counts.
Manufacturer Tree APIThe Manufacturer Tree API returns the manufacturer and software in a tree structure. Example Manufacturer Values and Counts Query
The API returns the manufacturer and their counts.
Modality Values and Counts APIThe Modality Values and Counts API will return the modality values plus the subject count for the modality it takes the following parameters optionally
Example Modality Values and Counts Query
The API returns the modalities and their counts
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.
Simple Search Criteria Values APIThe Simple Search Criteria Values API returns the possible criteria values to the client.
Example Simple Search Criteria Values Query
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 simple search. Example Species Values And Counts Query
The API returns the values and counts for species.
Study Drill Down APIThe Study Drill Down API provides the functionality in the portal where the user drills down the studies and series associated with a given user. The API simply takes a list of series to query, using the parameter "list", that is repeated for each series you want to retrieve. Example Study Drill Down Query
The Study Drill Down API returns JSON with the information to populate the drill down to study screen. You can retrieve multiple studies.
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
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.
|