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.

URLs to Access NLST Data

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.

NBIA Advanced REST API Query Structure

<YOUR_ACCESS_TOKEN><BaseURL><Resource><QueryEndpoint>?<QueryParameters>

For example, the API shown below requests all Body Part Values and Counts for the PT modality.

Example NBIA Advanced REST API Query

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
Access Token	cd2b2895-85d0-49c5-bd75-804f162da942
BaseURL	https://services.cancerimagingarchive.net
Resource	/nbia-api/services
Endpoint	getBodyPartValuesAndCounts
Query Parameters	Modality=PT

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.

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 do the following:

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.

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

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.

Call for Testing an NBIA REST API without a Token

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 likely be longer than this example.

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.

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

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.

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, 119 is the seconds before the token expires.

Sample Return Value

{"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.

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.

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.

Body Part Values and Counts API

The Body Part Values and Counts API returns the modality values and body part count for the modality. It optionally takes the following parameters.

Collection
Modality

Example Body Part Values and Counts Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getBodyPartValuesAndCounts?Modality=PT"

Sample Results

The API returns the body parts and their counts.

Sample Return Value

[
{"criteria":"ABDOMEN","count":"13"},
{"criteria":"CHEST","count":"298"},
{"criteria":"Chest","count":"1"},
{"criteria":"HEADNECK","count":"1"},{
"criteria":"Lung","count":"76"},
{"criteria":"THORAX_1_ROUTINE","count":"1"}
]

Collection Descriptions

This API takes a collection name and returns the collection's description.

The API takes one parameter:

collectionName (optional)

Example getCollectionDescriptions Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getCollectionDescriptions?collectionName=Anti-PD-1_Lung"

If successful, the API returns the collection description.

Sample Return Value

[{"description":"<p>\n\t<span class=\"conf-macro output-inline\" data-hasbody=\"true\" data-macro-name=\"excerpt\">This collection includes 46 lung cases treated with <span style=\"color: rgb(23,43,77);\">anti-PD1 immunotherapy</span> in 2016, each with pre-treatment imaging (CT,PT,SC) and most with 1 imaging follow-up timepoint.</span></p>\n<p>\n\t<span _ngcontent-cmj-c43=\"\" class=\"toolTip step show\" style=\"top: 1196.5px;\"><span _ngcontent-cmj-c43=\"\">Please see the <a href=\"https://doi.org/10.7937/tcia.2019.zjjwb9ip\">Anti-PD-1_Lung</a> wiki page to learn more about the images and to obtain any supporting metadata for this collection.</span></span></p>\n","id":700088325,"collectionDescTimestamp":null,"collectionName":"Anti-PD-1_Lung","userName":null,"licenseId":null,"descriptionURI":null}]

Collection or Series for DOI

The 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

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://imaging-qacm.nci.nih.gov/nbia-api/services/getCollectionOrSeriesForDOI" -d "DOI=https://doifor-CBIS-DDSM&CollectionOrSeries=collection"

Sample Return Value

[\{"collection":"CBIS-DDSM","seriesInstanceUID":null,"thirdPartyAnanlysis":null}]

Collection Values and Counts

The Collection Values and Counts API returns the collections and the subject count for the collection.

Example Collection Values And Counts Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k “https://services.cancerimagingarchive.net/nbia-api/services/getCollectionValuesAndCounts" -d "criteriaType0=CollectionCriteria&value0=CBIS-DDSM"

The API returns the collections with their counts.

Sample Response

[
{"criteria":"IDRI","count":"614"},
{"criteria":"IDRICONDUIT","count":"66"},
{"criteria":"LIDC","count":"397"},
{"criteria":"RIDER Pilot","count":"130"},
{"criteria":"SportInjury","count":"1"}
]

Create Saved Cart API

The Create Saved Cart API allows the creation of a saved cart.

The API takes four arguments:

list - A repeatable parameter for each series you wish to have in the saved cart
name- Name for the saved cart (note that names of saved carts must be unique)
description - Description of the saved cart
url - URL of the saved cart

Example Create Saved Cart Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/createSharedList" -d "list=88.8.133841977708353813381069288155921822331&list=88.8.326983478845196402838719404831299211067&name=LIST_NAME&description=mydescription&url=LIST_URL"

DICOM Metadata by Series UID API

The 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:

SeriesUID

The SeriesUID is available from the Drill Down API call.

Example Metadata Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getDicomTags?SeriesUID=9999.266036705757333804188405684898037929022

The API sends back triples of all DICOM element, name, data in the file.

Sample Response

[
{"element":"(0002,0001)","name":"File Meta Information Version","data":"00\\01"},
{"element":"(0002,0002)","name":"Media Storage SOP Class UID","data":"1.2.840.10008.5.1.4.1.1.2"}
...................................

Extended Simple Search with Modality and Body Part Paged API

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

CollectionCriteria
- value
ImageModalityCriteria
- value
AnatomicalSiteCriteria
- value
ManufacturerCriteria
- value
DateRangeCriteria
- fromDate - Formatted "dd/mm/yyyy"
- toDate - Formatted "dd/mm/yyyy"
PatientCriteria
- value
MinNumberOfStudiesCriteria
- value
SpeciesCriteria
- The code for the species
PhantomCriteria
- yes for phantoms
TimePointCriteria
- eventType the eventType for the timepoint
- fromDate - Formatted "dd/mm/yyyy"
- toDate - Formatted "dd/mm/yyyy"
SortField
- The field to sort on
SortDirection
- ascending or descending
Start
- The page to start on
Size
- How many items per page

Example Extended Simple Search with Modality and Body Part Paged Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getSimpleSearchWithModalityAndBodyPartPaged" -d "criteriaType0=TimePointCriteria&eventType0=DIAGNOSIS&fromDay0=-5&toDay0=10&sortField=subject&sortDirection=descending&start=0&size=9"

The API returns the results of the search.

Sample Response

{
   "resultSet":[
      {
         "subjectId":"Test-5910936489",
         "project":"Test",
         "id":819200,
         "modalities":[
            "CT"
         ],
         "bodyParts":[
            "LUNG"
         ],
         "species":[
            "L-877FC"
         ],
         "timepoints":{
            "DIAGNOSIS":[
               1,
               3
            ]
         },
         "totalNumberOfStudies":28,
         "totalNumberOfSeries":61,
         "studyIdentifiers":[
            {
               "seriesIdentifiers":[
                  917526,
                  917527,
                  917528
               ],
               "seriesAndModality":[
                  
               ],
               "studyIdentifier":851979
            },
            {
               "seriesIdentifiers":[
                  917529,
                  917530
               ],
               "seriesAndModality":[
                  
               ],
               "studyIdentifier":851980
            },
            {
               "seriesIdentifiers":[
                  917531,
                  917532
               ],
               "seriesAndModality":[
                  
               ],
               "studyIdentifier":851981
            }
         ]
      }
   ],
   "totalPatients":1,
   "bodyParts":[
      {
         "value":"LUNG",
         "count":1
      }
   ],
   "modalities":[
      {
         "value":"CT",
         "count":1
      }
   ],
   "collections":[
      {
         "value":"Test",
         "count":1
      }
   ],
   "species":[
      {
         "value":"L-877FC",
         "count":1
      }
   ],
   "maxTimepoints":{
      "DIAGNOSIS":3
   },
   "minTimepoints":{
      "DIAGNOSIS":1
   },
   "sort":"subject-descending"
}

Image with MD5 Hash API

This 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:

Collection - The collection to update
DOI - Digital Object Identifier

Example Image with MD5 Hash Query

Sample Call

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"

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 API

The 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

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getManifestForSimpleSearch" -d "criteriaType0=ThirdPartyAnalysis&value0=yes&sortField=subject&sortDirection=descending&start=0&size=1000000"

The API returns text that can be used as a manifest file for the NBIA Data Retriever.

Sample Response

downloadServerUrl=https://services.cancerimagingarchive.net/nbia-download/servlet/DownloadServlet
includeAnnotation=false
noOfrRetry=4
databasketId=manifest-1523866570303.tcia
manifestVersion=3.0
ListOfSeriesToDownload=
1.3.6.1.4.1.9328.50.3.336

Manifest Text API

The 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:

list - A repeatable parameter of series UIDs for each series you want to download
includeAnnotation - If "true" is used, the annotations are returned.

Example Manifest Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getManifestTextV2" -d "list=1.3.6.1.4.1.9328.50.3.336&includeAnnotation=false"

The API returns text that can be used as a manifest file for the NBIA Data Retriever.

Sample Response

downloadServerUrl=https://services.cancerimagingarchive.net/nbia-download/servlet/DownloadServlet
includeAnnotation=false
noOfrRetry=4
databasketId=manifest-1523866570303.tcia
manifestVersion=3.0
ListOfSeriesToDownload=
1.3.6.1.4.1.9328.50.3.336

Manifest for Text Search

This 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:

textValue

Example getManifestForTextSearch Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -X POST "https://services.cancerimagingarchive.net/nbia-api/services/getManifestForTextSearch" -d "textValue=CT"

Sample Response

downloadServerUrl=https://services.cancerimagingarchive.net/nbia-download/servlet/DownloadServlet
includeAnnotation=false
noOfrRetry=4
databasketId=manifest-1680987888150.tcia
manifestVersion=3.0
ListOfSeriesToDownload=
1.3.6.1.4.1.9328.50.4.563784
1.3.6.1.4.1.9328.50.4.568673
1.3.6.1.4.1.9328.50.4.568676
1.3.6.1.4.1.9328.50.4.568678
1.3.6.1.4.1.9328.50.4.569267
1.3.6.1.4.1.9328.50.4.569270
1.3.6.1.4.1.9328.50.4.569273
1.3.6.1.4.1.9328.50.4.569823
1.3.6.1.4.1.9328.50.4.571319
1.3.6.1.4.1.9328.50.4.571323
1.3.6.1.4.1.9328.50.4.571803
1.3.6.1.4.1.9328.50.4.571808
1.3.6.1.4.1.9328.50.4.572414
1.3.6.1.4.1.9328.50.4.572418
1.3.6.1.4.1.9328.50.4.572422
1.3.6.1.4.1.9328.50.4.572425
1.3.6.1.4.1.9328.50.4.572983
1.3.6.1.4.1.9328.50.4.573038
1.3.6.1.4.1.9328.50.4.573635
1.3.6.1.4.1.9328.50.4.573639
1.3.6.1.4.1.9328.50.4.574149
1.3.6.1.4.1.9328.50.4.574153
1.3.6.1.4.1.9328.50.4.578325
1.3.6.1.4.1.9328.50.4.578328
1.3.6.1.4.1.9328.50.4.578331
1.3.6.1.4.1.9328.50.4.578901
1.3.6.1.4.1.9328.50.4.579479
1.3.6.1.4.1.9328.50.4.579482
1.3.6.1.4.1.9328.50.4.579494
1.3.6.1.4.1.9328.50.4.580056
1.3.6.1.4.1.9328.50.4.579487
1.3.6.1.4.1.9328.50.4.579490
1.3.6.1.4.1.9328.50.4.580594
1.3.6.1.4.1.9328.50.4.581140
1.3.6.1.4.1.9328.50.4.590291
1.3.6.1.4.1.9328.50.4.590294
1.3.6.1.4.1.9328.50.4.590297
1.3.6.1.4.1.9328.50.4.590890
1.3.6.1.4.1.9328.50.4.591508
1.3.6.1.4.1.9328.50.4.591511
1.3.6.1.4.1.9328.50.4.591513
1.3.6.1.4.1.9328.50.4.591516
1.3.6.1.4.1.9328.50.4.591522
1.3.6.1.4.1.9328.50.4.591975
1.3.6.1.4.1.9328.50.4.592513
1.3.6.1.4.1.9328.50.4.593093
1.3.6.1.4.1.9328.50.4.593096
1.3.6.1.4.1.9328.50.4.593099
1.3.6.1.4.1.9328.50.4.593601
1.3.6.1.4.1.9328.50.4.594099
1.3.6.1.4.1.9328.50.4.594613
1.3.6.1.4.1.9328.50.4.595110
1.3.6.1.4.1.9328.50.4.595623
1.3.6.1.4.1.9328.50.4.596197
1.3.6.1.4.1.9328.50.4.596737
1.3.6.1.4.1.9328.50.4.600540
1.3.6.1.4.1.9328.50.4.600543
1.3.6.1.4.1.9328.50.4.601079
1.3.6.1.4.1.9328.50.4.601082
1.3.6.1.4.1.9328.50.4.601085
1.3.6.1.4.1.9328.50.4.601643
1.3.6.1.4.1.9328.50.4.604326
1.3.6.1.4.1.9328.50.4.604330
1.3.6.1.4.1.9328.50.4.604333
1.3.6.1.4.1.9328.50.4.604801
1.3.6.1.4.1.9328.50.4.604806
1.3.6.1.4.1.9328.50.4.607091
1.3.6.1.4.1.9328.50.4.607094
1.3.6.1.4.1.9328.50.4.607097
1.3.6.1.4.1.9328.50.4.618649
1.3.6.1.4.1.9328.50.4.610796
1.3.6.1.4.1.9328.50.4.610799
1.3.6.1.4.1.9328.50.4.610803
1.3.6.1.4.1.9328.50.4.611364
1.3.6.1.4.1.9328.50.4.611919
1.3.6.1.4.1.9328.50.4.612031
1.3.6.1.4.1.9328.50.4.612039
1.3.6.1.4.1.9328.50.4.612593
1.3.6.1.4.1.9328.50.4.612598
1.3.6.1.4.1.9328.50.4.613155
1.3.6.1.4.1.9328.50.4.613159
1.3.6.1.4.1.9328.50.4.613786
1.3.6.1.4.1.9328.50.4.613791
1.3.6.1.4.1.9328.50.4.613794
1.3.6.1.4.1.9328.50.4.614396
1.3.6.1.4.1.9328.50.4.614399

Manifest from Patient Study Series

This API takes a a parameter and generates a manifest file of patient IDs that match those parameters.

This API takes the following parameters:

patientIDs (required)
studyUIDs (optional)
seriesUIDs (optional)
anyOrAll (optional)
includeAnnotation (optional)

Example getManifestFromPatientStudySeries Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getManifestFromPatientStudySeries" -d "patientIDs=ISPY1_1001"

If successful, the API returns the following.

Sample Response

downloadServerUrl=https://nbia.cancerimagingarchive.net/nbia-download/servlet/DownloadServlet
includeAnnotation=true
noOfrRetry=4
databasketId=manifest-1691620358806.tcia
manifestVersion=3.0
ListOfSeriesToDownload=
1.3.6.1.4.1.14519.5.2.1.7695.1700.250955243295773832626617549482
1.3.6.1.4.1.14519.5.2.1.7695.1700.360389360742427667526070655843
1.3.6.1.4.1.14519.5.2.1.7695.1700.334491271566855314830260417024
1.3.6.1.4.1.14519.5.2.1.7695.1700.658441262671287309457346305705
1.3.6.1.4.1.14519.5.2.1.7695.1700.131126392922209124942161386151
1.3.6.1.4.1.14519.5.2.1.7695.1700.933316195746120155903339740103
1.3.6.1.4.1.14519.5.2.1.7695.1700.274616783627161175251743615553
1.3.6.1.4.1.14519.5.2.1.7695.1700.733313000644315272006192181431
1.3.6.1.4.1.14519.5.2.1.7695.1700.220092773361369396087067751186
1.3.6.1.4.1.14519.5.2.1.7695.1700.245270018412514241929134140425
1.3.6.1.4.1.14519.5.2.1.7695.1700.229054711046553504545787083659
1.3.6.1.4.1.14519.5.2.1.7695.1700.179162285704690412763684330250
1.3.6.1.4.1.14519.5.2.1.7695.1700.234808560418629209017784958053
1.3.6.1.4.1.14519.5.2.1.7695.1700.154616556555686498817341337478
1.3.6.1.4.1.14519.5.2.1.7695.1700.177623757250131970264857092191
1.3.6.1.4.1.14519.5.2.1.7695.1700.154110825244369885171851551255
1.3.6.1.4.1.14519.5.2.1.7695.1700.284567351304426376226790714264
1.3.6.1.4.1.14519.5.2.1.7695.1700.324328467511449053797650611970
1.3.6.1.4.1.14519.5.2.1.7695.1700.741335780571671051586458569948
1.3.6.1.4.1.14519.5.2.1.7695.1700.335719452327097001305227418372
1.3.6.1.4.1.14519.5.2.1.7695.1700.210538707954985296677398591978
1.3.6.1.4.1.14519.5.2.1.7695.1700.195983148423034180376334647727
1.3.6.1.4.1.14519.5.2.1.7695.1700.244863941836141483641489109194
1.3.6.1.4.1.14519.5.2.1.7695.1700.180831804100647525080922590445
1.3.6.1.4.1.14519.5.2.1.7695.1700.134282805412721876700374897836
1.3.6.1.4.1.14519.5.2.1.7695.1700.226038001772760333157260976449
1.3.6.1.4.1.14519.5.2.1.7695.1700.248017107754573666956949261473
1.3.6.1.4.1.14519.5.2.1.7695.1700.304222333797754930798522430195
1.3.6.1.4.1.14519.5.2.1.7695.1700.571620122698689331448512191875
1.3.6.1.4.1.14519.5.2.1.7695.1700.276008182492477899149189119200
1.3.6.1.4.1.14519.5.2.1.7695.1700.135612062012804030483357359425
1.3.6.1.4.1.14519.5.2.1.7695.1700.311831286327220528148178588078
1.3.6.1.4.1.14519.5.2.1.7695.1700.509490993107578827767081500491
1.3.6.1.4.1.14519.5.2.1.7695.1700.288985999148727959387883654619
1.3.6.1.4.1.14519.5.2.1.7695.1700.180006052978659726439424740707
1.3.6.1.4.1.14519.5.2.1.7695.1700.270834182764177195175091536181
1.3.6.1.4.1.14519.5.2.1.7695.1700.177962682118221509857252041052
1.3.6.1.4.1.14519.5.2.1.7695.1700.332791230985209928247615451914
1.3.6.1.4.1.14519.5.2.1.7695.1700.121164861481441093151316977794
1.3.6.1.4.1.14519.5.2.1.7695.1700.520396403274327587353342330294
1.3.6.1.4.1.14519.5.2.1.7695.1700.195950422361997478270837056988
1.3.6.1.4.1.14519.5.2.1.7695.1700.503697125043256633091008976690
1.3.6.1.4.1.5962.1.1.0.0.1548529146.50549.286
1.3.6.1.4.1.5962.1.1.0.0.1548529146.50549.288
1.3.6.1.4.1.5962.1.1.0.0.1548529146.50549.287
1.3.6.1.4.1.5962.1.1.0.0.1548529146.50549.285

MD5 Hierarchy

This API takes the following parameters:

SeriesInstanceUID (optional)
StudyInstanceUID (optional)
PatientID (optional)
Collection (optional)

Example getMD5Hierarchy Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getMD5Hierarchy" -d "Collection=LIDC"

Sample Response

3ef5cbc40b247c4a6f72a4f90f504ad1

Manufacturer Values and Counts API

The Manufacturer Values and Counts API returns the modality values plus the manufacturer count for the modality. It optionally takes the following parameters.

Collection
Modality
Body Part Examined

Example getManufacturerValuesAndCounts Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getManufacturerValuesAndCounts?Modality=PT"

The API returns the manufacturer and their counts.

Sample Response

[
{"criteria":"DeJarnette Research Systems","count":"2"},
{"criteria":"FUJI PHOTO FILM Co., ltd.","count":"4"}
]

MD5 Hash for Image API

Generates 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:

sopInstanceUid

Example MD5 Hash for Image Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getM5HashForImage?SOPInstanceUid=1.3.6.1.4.1.14519.5.2.1.6919.4624.302693755253199226108824913410"

The API returns the MD5 hash.

Modality Values and Counts API

The Modality Values and Counts API returns the modality values plus the subject count for the modality. It optionally takes the following parameters.

Collection
BodyPartExamined

Example Modality Values and Counts Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getModalityValuesAndCounts?Collection=LIDC"

The API returns the modalities and their counts.

Sample Response

[
{"criteria":"CT","count":"397"}
]

Restrictions for Simple Search API

The 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

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://localhost:8080/nbia-api/services/getRestrictionsForSimpleSearch" -d "criteriaType0=ThirdPartyAnalysis&value0=yes&sortField=subject&sortDirection=descending&start=0&size=1000000"

The API returns "Yes" if there are commercial restrictions and "No" if there are not.

Series Metadata API

The Series Metadata API allows returns the metadata needed by the client for a set of series as CSV.

The API takes one argument:

list- Comma-separated list of series to return

Example Series Metadata Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getSeriesMetadata2" -d "list=9999.293545899757968087866143572947417050996,9999.172212451609088872857235914630319746611"

The API returns ok if successful, and the error if one occurs.

Sample Response

Subject ID,Study UID,Study Description,Study Date,Series ID,Series Description,Number of images,File Size (Bytes),Collection Name,Modality,Manufacturer,3rd Party Analysis,Data Description URI,Series Number,License Name,License URL
STS_010,1.3.6.1.4.1.14519.5.2.1.5168.1900.154535988064062152660648619556,MRI LT LEG +C,2003-12-12,1.3.6.1.4.1.14519.5.2.1.5168.1900.104193299251798317056218297018,2. AXIAL T1 BOTH LEGS - RESEARCH,48,25273786,Soft-tissue-Sarcoma,MR,GE MEDICAL SYSTEMS,,https://doi.org/10.7937/K9/TCIA.2015.7GO2GSKS,2,Creative Commons Attribution 3.0 Unported License,https://creativecommons.org/licenses/by/3.0/

Species Tax API

The Species Tax API returns the species taxonomy and takes no parameters.

Example Species Tax Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k https://services.cancerimagingarchive.net/nbia-api/services/getSpeciesTax

The API returns the current species taxonomy.

Sample Response

[{"speciesCode":"447612001","speciesDescription":"Mus musculus"},{"speciesCode":"448771007","speciesDescription":"Canis lupus familiaris"},{"speciesCode":"337915000","speciesDescription":"Homo sapiens"}]

Species Values And Counts API

The 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

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getSpeciesValuesAndCounts"

The API returns the values and counts for species.

Sample Response

[{"criteria":"337915000","count":"33650"},{"criteria":"447612001","count":"393"},{"criteria":"448771007","count":"57"}]

Study Drill Down With Series IDs API

The 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

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getStudyDrillDownWithSeriesIds" -d "list=88.8.327219764444138790630242591550292040652&list=88.8.48940758713094405889891485363115655700"

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.

Sample Response

[ {"studyId" : "88.8.40100432719994870453539459050137164864",
  "date" : 671515200000,
  "description" : "CT CHEST W/O CONTRAST",
  "id" : 1310720,
  "seriesList" : [ {
    "seriesNumber" : "3",
    "seriesUID" : "88.8.326983478845196402838719404831299211067",
    "numberImages" : 9,
    "modality" : "CT",
    "manufacturer" : null,
    "annotationsFlag" : false,
    "annotationsSize" : 0,
    "patientId" : "Project-3076386612",
    "patientPkId" : "1277952",
    "studyId" : "88.8.40100432719994870453539459050137164864",
    "studyPkId" : 1310720,
    "totalSizeForAllImagesInSeries" : 4739336,
    "project" : "Project",
    "description" : "LUNG",
    "dataProvenanceSiteName" : null,
    "manufacturerModelName" : null,
    "softwareVersion" : null,
    "maxFrameCount" : "0",
    "seriesId" : "88.8.326983478845196402838719404831299211067",
    "seriesPkId" : 1376256,
    "exactSize" : 4739336  } ]} ]

Thumbnail API

The Get Thumbnail API returns the DICOM tags and values associated with the image.

seriesUID
objectUID

Example Thumbnail Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getThumbnail" -d "seriesUID=1.3.6.1.4.1.14519.5.2.1.3023.4024.536949365601910993926257264114&objectUID=1.3.6.1.4.1.14519.5.2.1.3023.4024.822829852603295162591249163632" --output Thumbnail.jpg

The API returns a JPG thumbnail.

Text Search API

The 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

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/getTextSearch" -d "textValue=lung"

Note that the returned JSON now includes the "hit" that was found by the Solr search engine.

Sample Response

[{
"subjectId":"Project-3076386612",
 "project":"Project",
 "id":1277952,
 "totalNumberOfStudies":1,
 "totalNumberOfSeries":1,
 "hit":"<em>seriesDesc</em>: <strong>LUNG</strong>",
 "studyIdentifiers":[{
 "seriesIdentifiers":[1376256],
 "studyIdentifier":1310720
 }]
}]

Updated Series API

This API returns the series that have been updated since a given date.

The API takes one argument:

fromDate - the date to get the updates have happened

Example Get Updated Series Query

Sample Call

curl -H "Authorization Bearer: YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getUpdatedSeries?fromDate=01/01/2020"

The API returns the updated series.

Sample Response

[
   {
      "SeriesInstanceUID":"1.3.6.1.4.1.5962.1.1.0.0.1560173490.85106.1",
      "StudyInstanceUID":"1.3.6.1.4.1.5962.1.1.0.1560173490.85106.1",
      "Modality":"SR",
      "SeriesDate":"2016-01-06 00:00:00.0",
      "SeriesDescription":"PDM Mouse Overview",
      "SeriesNumber":1,
      "Collection":"Project",
      "PatientID":"128783-104-T_VQ4",
      "Manufacturer":"PixelMed",
      "ManufacturerModelName":"XSLT",
      "SoftwareVersions":"0.1",
      "ImageCount":1
   }

Space shortcuts

Child pages

NBIA Advanced REST API Guide

What's New

Purpose of this Guide

NBIA Advanced REST API Base URL, Format, and Return Values

Secure Access to NBIA REST Services

Requesting a Token to Use with Restricted Data

Requesting a Token to Use with Public Data

How a Token is Returned/Granted/Given

Refreshing the Token

Logging Out

REST Advanced REST APIs

Body Part Values and Counts API

Example Body Part Values and Counts Query

Collection Descriptions

Example getCollectionDescriptions Query

Collection or Series for DOI

Example getCollectionOrSeriesForDOI Query

Collection Values and Counts

Example Collection Values And Counts Query

Create Saved Cart API

Example Create Saved Cart Query

DICOM Metadata by Series UID API

Example Metadata Query

Extended Simple Search with Modality and Body Part Paged API

Example Extended Simple Search with Modality and Body Part Paged Query

Image with MD5 Hash API

Example Image with MD5 Hash Query

Manifest for Simple Search API

Example Manifest for Simple Search Query

Manifest Text API

Example Manifest Query

Manifest for Text Search

Example getManifestForTextSearch Query

Manifest from Patient Study Series

Example getManifestFromPatientStudySeries Query

MD5 Hierarchy

Example getMD5Hierarchy Query

Manufacturer Values and Counts API

Example getManufacturerValuesAndCounts Query

MD5 Hash for Image API

Example MD5 Hash for Image Query

Modality Values and Counts API

Example Modality Values and Counts Query

Restrictions for Simple Search API

Example getRestrictionsForSimpleSearch Query

Series Metadata API

Example Series Metadata Query

Species Tax API

Example Species Tax Query

Species Values And Counts API

Example Species Values And Counts Query

Study Drill Down With Series IDs API

Example Study Drill Down With Series IDs Query

Thumbnail API

Example Thumbnail Query

Text Search API

Example Text Search Query

Updated Series API

Example Get Updated Series Query