What's New

Purpose of This Guide

This document describes the NBIA representational state transfer application programming interface (REST API) implementation for Release 6.0 and up. The API is designed for use by image analysis and data mining tools to directly query the public and private resources of NBIA and retrieve information into their applications. The API complements the existing web interface but eliminates the need for users to visit the NBIA 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 API. The application can build its own access routines using only the API documentation provided here. The interface employs predefined query functions (see NBIA REST API Guide, REST Search APIs, and User Administration APIs) that access NBIA databases.


Each API has a public and private version, used to access public or private data. 


If you are interested in using the API and have questions, contact .

NBIA v1 APIs



Each NBIA v1 API can access either public or restricted data. A different base URL distinguishes public and private data access. To access public data using an NBIA v1 API, refer to NBIA REST API Guide, below. Access to restricted data using an NBIA v1 API requires a token and a different base URL, https://imaging.nci.nih.gov/nbia-api/services/v2/. Find more information about how to request a token at Accessing Private Resources with NBIA REST Services.

NBIA v1 API URL and Format to Access Public Data

The full API for public resources consists of a base URL followed by the API and query parameters, in that order. The base URL to access public data is https://[installation location]/nbia-api/services/v1/.

For example, in the following URL:

https://imaging.nci.nih.gov/nbia-api/services/v1/getSeries?Collection=RIDER%20Pilot&PatientID=1.3.6.1.4.1.9328.50.1.0001&StudyInstanceUID=1.3.6.1.4.1.9328.50.1.2&format=csv

  • The base URL is https://[installation location]/nbia-api/services/v1/.
  • The API endpoint is getSeries.
  • The four query parameters are provided as follows:  Collection=RIDER Pilot&PatientID=1.3.6.1.4.1.9328.50.1.0001&StudyInstanceUID=1.3.6.1.4.1.9328.50.1.2&format=csv.
  • Data can be obtained in the following formats: CSV, HTML, XML, and JSON.

The order in which the query parameters are provided does not matter.

With the exception of the getImage query, all other queries return a file in one of these data formats: CSV, HTML, XML, and JSON, along with results. The first line of the file contains the names of the columns in the response. Each subsequent line corresponds to one row from the NBIA database. The getImage query returns a ZIP file of the images.

Example Call to Access Public Data

The following is an example call using curl to access public data using an API from the NBIA REST API Guide.

curl -s -X

GET https://imaging.nci.nih.gov/nbia-api/services/v1/getBodyPartValues?Collection=QIN%20PET%20Phantom-Demo

NBIA v1 API URL and Format to Access Private Data

Access to restricted data using an NBIA v1 API requires a token and a different base URL, https://[installation location]/nbia-api/services/v2/. More information about how to request a token is at Accessing Private Resources with NBIA REST Services.

NBIA v1 API Directory

Query NameReturn ValuesOutput FormatQuery Parameters
getBodyPartValuesSet of all body part names filtered by query keysCSV/HTML/XML/JSON

Collection (O)

Modality (O)

getCollectionValuesSet of all collection namesCSV/HTML/XML/JSONNone
getImageSet of images in a zip fileZIPSeriesInstanceUID (R)
getManufacturerValuesSet of all manufacturer names filtered by query keysCSV/HTML/XML/JSON

Collection (O)

BodyPartExamined (O)

Modality (O)

getModalityValuesSet of all modality values (CT, MR, ...) filtered by query keysCSV/HTML/XML/JSON

Collection (O)

BodyPartExamined (O)

getPatient


Set of patient objects filtered by query keysCSV/HTML/XML/JSONCollection (O)
getPatientStudySet of patient/study objects filtered by query keysCSV/HTML/XML/JSON

Collection (R)

PatientID (O)

StudyInstanceUID (O)

getSeriesSet of series objects filtered by query keysCSV/HTML/XML/JSON

Collection (O)

PatientID (O)

StudyInstanceUID (O)

Modality (O)

getSingleImageA single DICOM Object that is identified by its SeriesInstanceUID and SOPInstanceUID. This API will always be used following the /getSOPInstanceUIDs.Raw DICOM Object

SeriesInstanceUID (R)

SOPInstanceUID (R)

getSOPInstanceUIDsA list of SOPInstanceUIDs for a given series using the SeriesInstanceUID

CSV/HTML/XML/JSON

SeriesInstanceUID (R)

Return Values for NBIA v1 APIs

This section lists and explains the return values of the NBIA v1 REST APIs.

BodyPartExamined

An object that represents BodyPartExamined values.

AttributeDICOM TagDescription
BodyPartExamined0018 0015Standard DICOM definition

Collection

An object that represents Collection (project) values.

AttributeDICOM TagDescription
CollectionNAA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.

Image

An object that represents set of images in a ZIP file based on SeriesInstanceUID.

AttributeDICOM TagDescription
NANASet of images in a ZIP file

Manufacturer

An object that represents Manufacturer values.

AttributeDICOM TagDescription
Manufacturer0008 0070Standard DICOM definition

Modality

An object that represents Modality values.

AttributeDICOM TagDescription
Modality0008 0060Standard DICOM definition

Patient

An object that represents one patient.

AttributeDICOM TagDescription
PatientID0010 0020Has been de-identified as part of submission process.
PatientName0010 0010Has been de-identified as part of submission process.
PatientBirthDate0010 0030Has been de-identified as part of submission process.
PatientSex0010 0040Standard DICOM definition
EthnicGroup0010 2160Standard DICOM definition
CollectionNAA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.

PatientStudy

An object that represents one DICOM imaging study performed on one patient.

AttributeDICOM TagDescription
StudyInstanceUID0020 000DHas been de-identified as part of submission process.
StudyDate0008 0020Has been de-identified as part of submission process. Longitudinal information is preserved.
StudyDescription0008 1030Standard DICOM definition. Has been inspected and cleaned of any PHI
AdmittingDiagnosesDescription0008 1080Standard DICOM definition. Has been inspected and cleaned of any PHI
StudyID0020 0010Has been de-identified as part of submission process.
PatientAge0010 1010Standard DICOM definition
PatientID0010 0020Has been de-identified as part of submission process.
PatientName0010 0010Has been de-identified as part of submission process.
PatientBirthDate0010 0030Has been de-identified (emptied) as part of submission process.
PatientSex0010 0040Standard DICOM definition
EthnicGroup0010 2160Standard DICOM definition
CollectionNAA 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
Computed number of series.

Series

An object that represents one imaging series.

AttributeDICOM TagDescription
AnnotationsFlagNA
BodyPartExamined0018 0015Entered on a per collection basis using relevant SNOMED terms.
CollectionNAA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.
ImageCountNAComputed number of images in this series.
Manufacturer0008 0070Standard DICOM definition
ManufacturerModelName0008 1090Standard DICOM definition
Modality0008 0060Standard DICOM definition
PatientID0010 0020Has been de-identified as part of submission process.
ProtocolName0018 1030Standard DICOM definition. Has been inspected and cleaned of any PHI.
SeriesDate0008 0021Standard DICOM definition
SeriesDescription0008 103EStandard DICOM definition. Has been inspected and cleaned of any PHI.
SeriesInstanceUID0020 000EHas been de-identified as part of submission process.
StudyInstanceUID0020 000DHas been de-identified as part of submission process.
SeriesNumber0020 0011Standard DICOM definition
SoftwareVersions0018 1020Standard DICOM definition

Accessing Private Resources with NBIA REST Services

Starting with NBIA Release 6.1, the NBIA REST API supports secure access to private resources 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 Internet 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

   The flow illustrated in the preceding Figure includes the following steps:

   (A)  The client authenticates with the authorization server and
        requests an access token from the token endpoint.

   (B)  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 REST Server also supports token expiration and extension token by refresh.

Accessing a Private Resource

Do the following to access a private resource.

  1. Application requests credentials, shown below, from the resource owner/user.
    • username
    • password
  2. Application sends a request to the service using the given credentials as a query string for the body. 
    • grant_type = password
    • username
    • password

    It should look like this:

    grant_type=password&username=my_username&password=my_password

    These must be passed as well:

    • client_id
    • client_secret

    Which would become:

    grant_type=password&username=my_username&password=my_password&client_id=theClientIDFromApplicationSupport&client_secret=theClientSecretFromApplicationSupport
  3. The service responds with access token details and expiration information:
    • access_token
    • expires_in
    • token_type

  4. The application makes a request for private resources using the returned access token. All APIs listed for accessing public resources support secure access of private resources with an additional parameter for the access token. 

Example Request for Token

There are many ways to create a REST client using NBIA REST Services. An example in curl follows to show how to request NBIA REST Services for private resources.

# Request for access token

$ curl -X -v -d "username=Tester1&password=Tester1&client_id=theClientIDFromApplicationSupport&client_secret=theClientSecretFromApplicationSupport&grant_type=password" -X POST -k "https://imaging.nci.nih.gov/nbia-api/oauth/token"

# Request for access token
          
$ curl -X -v -d  "username=Tester1&password=Tester1&client_id=theClientIDFromApplicationSupport&client_secret=theClientSecretFromApplicationSupport&grant_type=password" -X POST -k "https://imaging.nci.nih.gov/nbia-api/oauth/token"

The REST client developer must contact  to get a valid client_id, client_secret and, of course, the username and password, to access the private resource.

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}

Example Request for Accessing a Private Resource

Make a note of the access token you receive and pass it with the REST service call.

# Request for modality values
              
$ curl -H "Authorization:Bearer f7889076-b3e4-4768-9419-3cd973adda76" -k "https://imaging.nci.nih.gov/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"}]

Example Request for Refreshing the Token

# Request for refreshing the token  

$curl -X -v -d "refresh_token=671bb72b-f929-4ef5-a4d7-b52341a6007a&client_id=theClientIDFromApplicationSupport&client_secret=theClientSecretFromApplicationSupport&grant_type=refresh_token" -X POST "
-k "https://imaging.nci.nih.gov
        
/nbia-api/oauth/token"

The result:

{"access_token":"bbe4aa2c-7235-41ad-9770-31619d3dbd15","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":119}

Example Request for Logout

# Request for logout

$curl -H "Authorization:Bearer bbe4aa2c-7235-41ad-9770-31619d3dbd15" -k "https://imaging.nci.nih.gov/nbia-api/logout"

The result:  

 You Have Logged Out successfully.


NBIA Search REST APIs


As of NBIA 6.4, the application has a REST search API that is used to perform the backend services of the search pages within the portal. The search API uses authorization by default, so that users can access private data. For developers that just need access to public data, each NBIA instance includes a guest user name. Ask the NBIA administrator for this user name; the password for the public user is ignored. Since the purpose of the search API is to provide programmatic access to backend functionality, all service endpoints return JSON except the JNLP endpoint that returns a text file that can be used to invoke Download Manager.

Use of NBIA Search APIs requires a token. More information about how to request a token is at Accessing Private Resources with NBIA REST Services.

Advanced Search API

The advanced search API is used in the portal to create queries for the advanced search.  The Advanced Search API is bound to the NBIA configuration DataSourceItem.xml and is like a map of tables and columns.

Developers who want to use the API should focus on:

  • sourceName - The entity to be queried
  • itemName - The field to be queried
<dataSource>
        <sourcePackageName>gov.nih.nci.nbia.internaldomain</sourcePackageName>
        <sourceLabel>Patient</sourceLabel>
        <sourceName>Patient</sourceName>
        <sourceItem>
            <itemLabel>Patient ID</itemLabel>
            <itemName>patientId</itemName>
            <itemType>java.lang.String</itemType>
        </sourceItem>
        <sourceItem>
            <itemLabel>Patient Name</itemLabel>
            <itemName>patientName</itemName>
            <itemType>java.lang.String</itemType>
        </sourceItem>
        <sourceItem>
            <itemLabel>Patient Gender</itemLabel>
            <itemName>patientSex</itemName>
            <itemType>java.lang.String</itemType>
            <itemPrimaryValue>true</itemPrimaryValue>
        </sourceItem>

Developers should also familiarize themselves with the available operators.

  • For numbers ">","<",">=","<=","=","!="
  • "starts with","ends with","contains","equals"

The queries consist of two main items:

  • A series of search criteria, which since they can repeat a number at the end provides the order in which to be processed, starting at zero
    • itemName 
    • sourceName
    • value - The value to be used as criteria
    • operator 
  • stateRelation, which is whether to use "and" or "or "in the logic between the search criteria values can be
    • AND
    • OR

Example Advanced Search Query 

curl -H "Authorization:Bearer 946bddb4-d076-4fb1-8dff-81fb64d6f921" -k "https://services.cancerimagingarchive.net/nbia-api/services/getDynamicSearch" -d "itemName0=project&sourceName0=TrialDataProvenance&value0=Project&stateRelation=AND&operator0=equals"

Since the API is for programmatic use, JSON is returned, providing the information returned in the initial search screen.

[ {
subjectId" : "Project-2305981223",
  "project" : "Project",
  "id" : 163840,
  "totalNumberOfStudies" : 1,
  "totalNumberOfSeries" : 3,
  "studyIdentifiers" : [ {
    "seriesIdentifiers" : [ 262144, 262148, 262160 ],
    "studyIdentifier" : 196608
  } ]
}, {
  "subjectId" : "Project-3076386612",
  "project" : "Project",
  "id" : 1277952,
  "totalNumberOfStudies" : 1,
  "totalNumberOfSeries" : 1,
  "studyIdentifiers" : [ {
    "seriesIdentifiers" : [ 1376256 ],
    "studyIdentifier" : 1310720
  } ]
}, {
  "subjectId" : "Project-7591268101",
  "project" : "Project",
  "id" : 163841,
  "totalNumberOfStudies" : 1,
  "totalNumberOfSeries" : 1,
  "studyIdentifiers" : [ {
    "seriesIdentifiers" : [ 262145 ],
    "studyIdentifier" : 196609
  } ] } ]

Note that the series identifiers are those that fulfill the search criteria.

Body Part Values and Counts API

The Body Part Values and Counts API will return the modality values plus the body part count for the modality it takes the following parameters optionally

  • Collection
  • Modality

Example Body Part Values and Counts Query

curl -H "Authorization:Bearer c428d42c-9eed-4f5d-8007-416d46be9b52" -k "https://services.cancerimagingarchive.net/nbia-api/services/getBodyPartValuesAndCounts?Modality=PT"

The API returns the body parts and their counts

[
{"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 Description API 

The Collection Description API retrieves Collection Descriptions

The API optionally takes one argument:

  • collectionName - The name of the Collection. If omitted, all collections are returned.

Example Collection Description Query 

C:\>curl -H "Authorization:Bearer 1724fb17-b3a5-488c-9c6f-877f489e0489" -k "https://services.cancerimagingarchive.net/nbia-api/services/getCollectionDescriptions?collectionName=IDRI"

The API returns the Search Criteria Descriptions.

[{"description":"mydescription",
"id":25034752,
"collectionDescTimestamp":null,
"collectionName":"Project",
"userName":null,
"licenseId":1}]

Collection Values and Counts API

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

Example Collection Values and Counts Query

curl -H "Authorization:Bearer ac89b752-1c29-4bd6-b999-a12483c9c171" -k "https://services.cancerimagingarchive.net/nbia-api/services/getExtendedSimpleSearch" -d "criteriaType0=CollectionCriteria&value0=Project"

 The API returns the collections with their counts.

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

Create Saved Cart API

The Create Saved Cart API creates a saved cart.

The API takes four arguments:

  • list - A repeatable parameter for each series you want to have in the saved cart
  • name- Name for the saved cart
  • description - Description of the saved cart
  • url - URL of the saved cart

Example Create Saved Cart Query

curl -H "Authorization:Bearer 5e3d3b2a-2533-4257-ba76-aa498ab8d269" -k "https://services.cancerimagingarchive.net/nbia-api/services/createSharedList" -d "list=88.8.133841977708353813381069288155921822331&list=88.8.326983478845196402838719404831299211067&name=scottslist&description=mydescription&url=testurl"

Delete Saved Cart API

The Delete Saved Cart API deletes a saved cart.

The API takes one argument:

  • name- Name for the saved cart

Example Delete Saved Cart Query

curl -H "Authorization:Bearer 5e3d3b2a-2533-4257-ba76-aa498ab8d269" -k "https://services.cancerimagingarchive.net/nbia-api/services/deleteSharedList" -d "name=scottslist"

Drill Down API

The 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 Drill Down Query 

curl -H "Authorization:Bearer 946bddb4-d076-4fb1-8dff-81fb64d6f921" -k "https://services.cancerimagingarchive.net/nbia-api/services/getStudyDrillDown" -d "list=1376256&list=262144"

The Drill Down API returns JSON with the information to populate the drill down to study screen. There can be multiple studies.

[ {"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  } ]} ]

DICOM Metadata by SeriesUID API 

The DICOM metadata by SeriesUID API provides the functionality in the portal where the DICOM data is retrieved from a series.

The API takes one argument:

  • SeriesUID

Example Metadata Query 

C:\curl>curl -H "Authorization:Bearer 25bbea7c-4b8d-4f64-9d95-6ad62313c7d6" -k "https://services.cancerimagingarchive.net/nbia-api/services/getDicomTags?SeriesUID=9999.266036705757333804188405684898037929022

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

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

Drill Down Using Series UIDs API

The Drill Down Using Series UIDs API provides the functionality in the portal where the user drills down the studies and series associated with a given user.

The API takes a list of Series UIDs to query, using the parameter "list", that is repeated for each Series UID you want to retrieve.

Example Drill Down Using Series UIDs Query 

curl -H "Authorization:Bearer 5e3e2193-55dc-43b5-b11a-70fee2ccf50f" -k "https://services.cancerimagingarchive.net/nbia-api/services/getStudyDrillDownWithSeriesIds" -d "list=88.8.327219764444138790630242591550292040652&list=88.8.48940758713094405889891485363115655700"

The Drill Down Using Series UIDs API returns JSON with the information to populate the drill down to study screen. You can include multiple studies in the query.

[ {"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  } ]} ]

Drill Down to Images API

The 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," which repeats for each series for which you want to retrieve images.

Example Drill Down to Images Query 

curl -H "Authorization:Bearer 946bddb4-d076-4fb1-8dff-81fb64d6f921" -k "https://services.cancerimagingarchive.net/nbia-api/services/getImageDrillDown" -d "list=1376256&list=262144"

 The API returns the information needed to populate the Thumbnails screen.

[ {  "imagePkId" : 1409028,
  "contentDate" : null,
  "contentTime" : null,
  "seriesPkId" : 1376256,
  "instanceNumber" : 73,
  "sopInstanceUid" : "88.8.73811183841243046367164226375699603900",
  "seriesInstanceUid" : "88.8.326983478845196402838719404831299211067",
  "studyInstanceUid" : "88.8.40100432719994870453539459050137164864",
  "size" : 526592,
  "fileURI" : "C:\\projects\\NBIA\\nbia-install_6.3\\CTP-server\\CTP\\storage\\0000000000\\000\\000\\006.dcm",
  "project" : null,
  "siteName" : null,
  "frameNum" : 0
}, {
  "imagePkId" : 1409024,
  "contentDate" : null,
  "contentTime" : null,
  "seriesPkId" : 1376256,
  "instanceNumber" : 85,
8<------------------------------------------------------------------------------->8

The information needed to create a WADO call is the following snippet from this code:

  "sopInstanceUid" : "88.8.73811183841243046367164226375699603900",
  "seriesInstanceUid" : "88.8.326983478845196402838719404831299211067",
  "studyInstanceUid" : "88.8.40100432719994870453539459050137164864",

Extended Simple Search API

The Extended Simple Search API adds two new fields to the return values. 

Example Extended Simple Search Query 

curl -H "Authorization:Bearer ac89b752-1c29-4bd6-b999-a12483c9c171" -k "https://services.cancerimagingarchive.net/nbia-api/services/getExtendedSimpleSearch" -d "criteriaType0=CollectionCriteria&value0=Project"

 The API returns the simple search with additional information.

[ {
subjectId" : "Project-2305981223",
  "project" : "Project",
  "id" : 163840,
  "totalNumberOfStudies" : 1,
  "totalNumberOfSeries" : 3,
  "studyIdentifiers" : [ {
    "seriesIdentifiers" : [ 262144, 262148, 262160 ],
    "studyIdentifier" : 196608
  } ]
  "diskSpace": 54321012,
  "imageCount 43212,
} ]

Host Name API

The Host Name returns a short host name used by the client to display which machine in a load-balanced environment is running.

Example Host Name Query

C:\curl>curl -H "Authorization:Bearer 6ea24d8c-00a3-4a9f-b4e9-faaaf949c598" -k "https://services.cancerimagingarchive.net/nbia-api/services/getHostName" -d

The API returns a short host name.

 tcia-public-rh-1

Manifest API

The Manifest API allows the creation of a manifest file that can be used to execute the Downloader App.

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 

curl -H "Authorization:Bearer d98c390f-b53d-4456-beb3-110e63663762" -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 Downloader App.

downloadServerUrl=https://imaging-devcm.nci.nih.gov/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 API from Saved Cart

The Manifest API from Saved Cart allows the creation of a manifest file that can be used to execute the NBIA Data Retriever.

The API takes two arguments:

  • sharedList - The name of the saved cart
  • includeAnnotation - If "true" is used, the annotations are returned.

Example Manifest from Saved Cart Query 

curl -H "Authorization:Bearer a99171a1-b289-4700-9e4e-1bd73ce1bbb5" -k "https://services.cancerimagingarchive.net/nbia-api/services/getManifestTextFromSharedList" -d "sharedList=scottslist&includeAnnotation=false"

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

downloadServerUrl=https://imaging-devcm.nci.nih.gov/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 API from JNLP Data

The Manifest API from JNLP data allows the creation of a manifest file that can be used to execute the Downloader App.

The API takes two arguments:

  • jnlpArgument- The value of the argument in the JNLP file
  • includeAnnotation - If "true" is used, the annotations are returned.

Example Manifest from JNLP Data Query 

curl -H "Authorization:Bearer 3b2bf812-a97e-454e-af94-623b868a2955" -k "https://services.cancerimagingarchive.net/nbia-api/services/getManifestFromJNLPFileData" -d "jnlpArgument=C:\Apps\nbia\apache-tomcat-7.0.68\temp\jnlp-data1521628213301.txt&includeAnnotation=false"

The API returns text that can be used as a manifest file for the Downloader App.

downloadServerUrl=https://imaging-devcm.nci.nih.gov/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

Manufacturer Values and Counts API

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

  • Collection
  • Modality
  • Body Part Examined

Example Manufacturer Values and Counts Query

curl -H "Authorization:Bearer c428d42c-9eed-4f5d-8007-416d46be9b52" -k "https://services.cancerimagingarchive.net/nbia-api/services/getManufacturerValuesAndCounts?Modality=PT"

The API returns the manufacturer and their counts.

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

Manufacturer Tree API

The Manufacturer Tree API will return the manufacturer and software in a structure that allows the build of a tree.

Example Manufacturer Values and Counts Query

curl -H "Authorization:Bearer  3ecccd7d-9d72-4424-bd81-757d79cd44aa" -k "https://services.cancerimagingarchive.net/nbia-api/services/getManufacturerTree"

The API returns the manufacturer and their counts.

{"data":{"criteria":"root","value":"All Manufactures"},
"children":[{"data":{"criteria":"Manufacturer","value":"CMS, Inc."},
"children":[{"data":{"criteria":"Model","value":"XiO"},
"children":[{"data":{"criteria":"Software Ver.","value":"4.51.00"},
"children":[]},{"data":{"criteria":"Software Ver.","value":"4.51.02"},"children":[]}]}]},
{"data":{"criteria":"Manufacturer","value":"CPS"},
"children":[{"data":{"criteria":"Model","value":"1024"}
8<------------------------------------------------------------------------------->8
Modality Values and Counts API
The Modality Values and Counts API will return the modality values plus the subject count for the modality it takes the following parameters optionally
  • Collection
  • BodyPartExamined
Example Modality Values and Counts Query
curl -H "Authorization:Bearer c428d42c-9eed-4f5d-8007-416d46be9b52" -k "https://services.cancerimagingarchive.net/nbia-api/services/getModalityValuesAndCounts?Collection=LIDC"

The API returns the modalities and their counts
[
{"criteria":"CT","count":"397"}
]
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
curl -H "Authorization:Bearer 1be042c4-2506-4ecc-9c5e-9556506896aa" -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.
"Subject ID","Study UID","Study Description","Study Date","Series ID","Series Description","Number of images","File Size (Bytes)","Collection Name","Modality","Manufacturer"
"LIDC-IDRI-1009708434","9999.80530326108514806420601956698897575003","CT CHEST O CONTR","1999-12-21 00:00:00.0","9999.172212451609088872857235914630319746611","","268","141000690","LIDC-IDRI","CT","GE MEDICAL SYSTEMS"
"LIDC-IDRI-1001617569","9999.217840977308171348409694654150334249839","","1999-12-21 00:00:00.0","9999.293545899757968087866143572947417050996","","46","24199232","LIDC-IDRI","CT","SIEMENS"
Series Metadata Returning Spreadsheet API
The Series Metadata Returning Spreadsheet API allows returns the metadata needed by the Client for a set of series as CSV in the form of a spreadsheet. 
The API takes one argument:
  • list- Comma separated list of series to return
Example Series Metadata Returning Spreadsheet Query
curl -H "Authorization:Bearer 1be042c4-2506-4ecc-9c5e-9556506896aa" -k "https://services.cancerimagingarchive.net/nbia-api/getSeriesMetadata2" -d "list=9999.293545899757968087866143572947417050996,9999.172212451609088872857235914630319746611"
The API returns "ok" if successful and the error if one occurs.
"Subject ID","Study UID","Study Description","Study Date","Series ID","Series Description","Number of images","File Size (Bytes)","Collection Name","Modality","Manufacturer"
"LIDC-IDRI-1009708434","9999.80530326108514806420601956698897575003","CT CHEST O CONTR","1999-12-21 00:00:00.0","9999.172212451609088872857235914630319746611","","268","141000690","LIDC-IDRI","CT","GE MEDICAL SYSTEMS"
"LIDC-IDRI-1001617569","9999.217840977308171348409694654150334249839","","1999-12-21 00:00:00.0","9999.293545899757968087866143572947417050996","","46","24199232","LIDC-IDRI","CT","SIEMENS"
Shared List Data API
The Shared List Data API retrieves the data associated with a Shared List
The API takes one argument:
  • nameValue - The name of the Shared List
Example Shared List Data Query 
curl -H "Authorization:Bearer 6143882e-fd9d-4269-9d67-f4293afe417f" -k "https://services.cancerimagingarchive.net/nbia-api/services/getSharedList" -d "nameValue=scottslist"
The API will send back the Shared List data.
{"name":"scottslist",
"comment":"",
"hyperlink":"//",
"date":1502078400000,
"id":7798784,
"userName":"sgustaf",
"seriesInstanceUIDs":["88.8.327219764444138790630242591550292040652","88.8.48940758713094405889891485363115655700"],
"seriesInstanceUidsList":null,
"usageCount":null,
"dateString":"2017-08-07"}
Simple Search API
The Simple Search API is used to run queries for the Simple search in NBIA, the Simple Search API uses a variety of criteria as seen in the Simple Search Screen. The available criteria types include and their components are:
  • CollectionCriteria
    • value
  • ImageModalityCriteria
    • value
  • AnatomicalSiteCriteria
    • value
  • ManufacturerCriteria
    • value
  • DateRangeCriteria
    • fromDate - Formatted "dd/mm/yyyy"
    • toDate - Formatted "dd/mm/yyyy"
  • PatientCriteria
    • value
  • MinNumberOfStudiesCriteria
    • value
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 Simple Search Query 
curl -H "Authorization:Bearer 946bddb4-d076-4fb1-8dff-81fb64d6f921" -k "https://services.cancerimagingarchive.net/nbia-api/services/getSimpleSearch" -d "criteriaType0=AnatomicalSiteCriteria&value0=LUNG&criteriaType1=CollectionCriteria&value1=Project"
The Simple Search API returns the same JSON as the Advanced Search API.
Submission API
The Submission API allows images to be imported into the NBIA database and text index without being submitted through CTP.  Note the API does not create thumbnails as it is assumed that they have already been created.
The API takes up to seven arguments:
  • project- The collection.
  • siteName- The site name.
  • siteID- The site ID.
  • batch- The batch if necessary.
  • thirdPartyAnalysis- yes if a third party analysis
  • descriptionURI- The uri of the description of third party analysis
  • uri- The location of the image files
Example Submission Query
curl -H "Authorization:Bearer 0d9ad4b6-153b-4777-a506-358e3411b3ae" -k "https://services.cancerimagingarchive.net/nbia-api/services/submitDICOM" -d "project=CBIS-DDSM&siteName=CBIS-DDSM&siteID=99&batch=8
&uri=C:/a/000002.dcm"
The API returns "ok" if successful and the error if one occurs.
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 
curl -H "Authorization:Bearer 946bddb4-d076-4fb1-8dff-81fb64d6f921" -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.
[{
"subjectId":"Project-3076386612",
 "project":"Project",
 "id":1277952,
 "totalNumberOfStudies":1,
 "totalNumberOfSeries":1,
 "hit":"<em>seriesDesc</em>: <strong>LUNG</strong>",
 "studyIdentifiers":[{
 "seriesIdentifiers":[1376256],
 "studyIdentifier":1310720
 }]
}]
User Administration APIs
This section describes the group of APIs used internally by NBIA's User Authorization Tool (UAT). The user administration information is considered a private resource and is protected by NBIA's OAauth 2 API server, which allows access only by authorized users. For details on accessing private resources using the NBIA REST service, see NBIA REST API Guide.
Assuming the user has been authenticated and has received the OAuth token for the HTTP headers of the API calls, that user can refer to the following table for the parameters for each query endpoint in the UAT APIs. The server returns either the status of the operation or the data requested in the format specified in the query parameter. However, the query parameter for format is optional. If it is not provided, the response returns data in JSON format.
Access to the user administration APIs requires a token and a different base URL, https://imaging.nci.nih.gov/nbia-api/services/v3.
Resource
QueryEndpoint
Query Parameters
All query parameters are optional unless stated otherwise.
Return
Description
v3/
assignDataSetToPG
projAndSite(R)
PGName(R)
The status of operation
Assign a combination of Project and Site to a Protection Group
v3/
assignGroupToPGWithRoles
groupName(R)
PGName(R)
roleNames(R)
The status of operation
Assign a group to a protection group with a role
v3/
assignPEsToPG
PENames(R)
PGName(R)
The status of operation
Assign a list of combination of Project and Site to a Protection Group
v3/
assignUserToPGWithRoles
loginName(R)
PGName(R)
roleNames(R)
The status of operation
Assign an user to a protection group with a role
v3/
createProtecionGroup
PGName(R)
description
The status of operation
Create a new Protection Group
v3/
createUser
loginName(R)
email(R)
active(R)
The status of operation
Create a new user
v3/
deassignDataSetFromPG
projAndSite(R)
PGName(R)
The status of operation
De-assign a combination of Project and Site from a Protection Group
v3/
deassignPEsFromPG
PENames(R)
PGName(R)
The status of operation
De-assign a list of combination of Project and Site from a Protection Group
v3/
deassignUserFromPGWithRoles
loginName(R)
PGName(R)
roleNames(R)
The status of operation
De-assign an user from a protection group with a role
v3/
deleteGroup
GroupName(R)
The status of operation
Delete a Group
v3/
deleteProtecionGroup
PGName(R)
The status of operation
Delete a Protection Group
v3/
getAllGroupsWithPGs
format
CSV/HTML/XML/JSON
Get all groups with associated protection groups
v3/
getAllPGsWithPEs
format
CSV/HTML/XML/JSON
Get all protection groups with associated protection elements
v3/
getAllPGsWithRolesForUser
loginName(R)
format
CSV/HTML/XML/JSON
Get protection group and roles associated with given user
v3/
getAllUsersWithRolesForPG
format
CSV/HTML/XML/JSON
Get all users with associated protection group and roles
v3/
getAvailablePEsForPG
PGName (R)
format
CSV/HTML/XML/JSON
Get the list of protection element names associated with a given protection group
v3/
getAvailablePGsForGroup
groupName (R)
format
CSV/HTML/XML/JSON
Get the list of protection element associated with the given group name
v3/
getAvailablePGsForUser
loginName (R)
format
CSV/HTML/XML/JSON
Get the list of protection group associated with the given user
v3/
getGroupList
format
CSV/HTML/XML/JSON
Get all group names
v3/
getIncludedPEsForPG
PGName (R)
format
CSV/HTML/XML/JSON
Get the list of protection element in the given protection group
v3/
getProjSiteList
format
CSV/HTML/XML/JSON
Get the list of <Project Name>//<Site Name>
v3/
getProtectionEleNameList
format
CSV/HTML/XML/JSON
Get all protection elements
v3/
getProtectionGrpList
format
CSV/HTML/XML/JSON
Get all protection group objects
v3/
getProtectionGrpNameList
format
CSV/HTML/XML/JSON
Get all protection group names
v3/
getRoleList
format
CSV/HTML/XML/JSON
Get all role names
v3/
getUserList
format
CSV/HTML/XML/JSON
Get all user objects
v3/
getUserNameList
format
CSV/HTML/XML/JSON
Get all user login names
v3/
modifyProtecionGroup
PGName(R)
Description(R)
The status of operation
Modify the description of a given Protection Group
v3/
modifyRolesOfGroupForPG
groupName(R)
PGName(R)
roleNames(R)
The status of operation
Modify a group’s roles with a given Protection Group
v3/
modifyRolesOfUserForPG
loginName(R)
PGName(R)
roleNames(R)
The status of operation
Modify a user’s roles win a given Protection Group
v3/
modifyUser
loginName(R)
email(R)
active(R)
The status of operation
Modify the given user’s email and/or active status
v3/
removeGroupFromPG
groupName(R)
PGName(R)
The status of operation
Remove a group from a protection Group
v3/
removeUserFromPG
loginName(R)
PGName(R)
The status of operation
Remove a user from a Protection Group