The Cancer Imaging Archive (TCIA) Public Access

Space shortcuts

Child pages
  • NBIA Advanced REST API Guide

Versions Compared

Old Version 2

changes.mady.by.user Carolyn Klinger

Saved on

compared with

New Version 3

changes.mady.by.user Carolyn Klinger

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Content Zone
maxLevel2
locationtop

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

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

Sample Results

The API returns the body parts and their counts.

Code Block
titleSample 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 or Series for DOI API

The Collection or Series for DOI API returns the collection and/or series with the Digital Object Identifier (DOI). 

Example Collection or Series for DOI Query

Code Block
titleSample Call
curl -H "Authorization:Bearer eec67b9c-44fc-4fd8-809d-dea1b228c8b9" -k "https://imaging-qacm.nci.nih.gov/nbia-api/services/getCollectionOrSeriesForDOI" -d "DOI=https://doifor-CBIS-DDSM&CollectionOrSeries=collection"

 The API returns the collections with their counts.

Code Block
titleSample Return Value
[\{"collection":"CBIS-DDSM","seriesInstanceUID":null,"thirdPartyAnanlysis":null}]

Collection Values and Counts API

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

Example getCollectionValuesAndCounts Query

Code Block
titleSample Call
curl -H "Authorization:Bearer 8159f96d-d2fc-4af9-aa83-9a29876ef758" -k “https://services.cancerimagingarchive.net/nbia-api/services/getCollectionValuesAndCounts" -d "criteriaType0=CollectionCriteria&value0=CBIS-DDSM"

 The API returns the collections with their counts.

Code Block
titleSample Return Value
[
{"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 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

Code Block
titleSample Call
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"

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 

Code Block
titleSample Call
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 sends back triples of all DICOM element, name, data in the file.

Code Block
titleSample Return Value
[
{"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"}
...................................

DICOM Tags By Image ID API

The DICOM Tag By Image ID API returns the DICOM tags and values associated with the image.

  • imageID

The values used in this API can be derived by using the results of the imagePkId in the Drill Down to Images API.

Example DICOM Tags By Image ID Query

Code Block
titleSample Call
C:\curl>curl -H "Authorization:Bearer d9d01317-34c3-40ac-92dc-9a1287a159e4" -k "https://services.cancerimagingarchive.net/nbia-api/services/getDicomTagsByImageID?imageID=4587520"

The API returns the tags and values.

Code Block
titleSample Return Value
[{"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.128"},
{"element":"(0002,0003)","name":"Media Storage SOP Instance UID","data":"88.8.263250895051952442807371950278727814872"},
{"element":"(0002,0010)...

Drill Down API

The 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 Extended Simple Search with Modality and Body Part Paged Query.

Example Drill Down Query 

Code Block
titleSample Call
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.

Code Block
titleSample Return Value
[ {"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 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 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 

Code Block
titleSample Call
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 retrieve multiple studies.

Code Block
titleSample Return Value
[ {"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," that repeats for each series for which you want to retrieve images.

Example Drill Down to Images Query 

Code Block
titleSample Call
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.

Code Block
titleSample Return Value
[ {  "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:

Code Block
titleInformation Needed for a WADO Call
  "sopInstanceUid" : "88.8.73811183841243046367164226375699603900",
  "seriesInstanceUid" : "88.8.326983478845196402838719404831299211067",
  "studyInstanceUid" : "88.8.40100432719994870453539459050137164864",

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

  • 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

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

Code Block
titleSample Call
curl -H "Authorization:Bearer d2310d88-cefe-491f-82a2-df66d6c087c4" -k "http://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.

Code Block
titleSample Return Value
{
   "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

Code Block
titleSample Call
curl -H "Authorization:Bearer 72dfaea7-b704-4b31-ad90-02606faa4572" -k "http://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.

Licenses API

The Licenses API retrieves all available license information.

The API takes no arguments.

Example Licenses Query

Code Block
titleSample Call
curl -H "Authorization:Bearer ff849ffb-7b18-4c7e-83bd-6db2f7dbee9c" -k "https://services.cancerimagingarchive.net/nbia-api/services/getLicenses"

If the API is successful, it returns the licenseslicense long name, short name, license URL, license text, and commercial use designation.

Code Block
titleSample Return Value
[
{
"longName":"Creative Commons Attribution 3.0 Unported License",
"id":1,
"shortName":"CC BY 3.0",
"licenseURL":"http://creativecommons.org/licenses/by/3.0/",
"licenseText":"https://creativecommons.org/licenses/by/3.0/",
"commercialUse":"YES",
"license":{
"id":1,
"longName":"Creative Commons Attribution 3.0 Unported License",
"shortName":"CC BY 3.0",
"url":"http://creativecommons.org/licenses/by/3.0/",
"commercialUse":"YES",
"licenseText":"https://creativecommons.org/licenses/by/3.0/"
}
},....

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 

Code Block
titleSample Call
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 NBIA Data Retriever.

Code Block
titleSample Return Value
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 the modality values plus the manufacturer count for the modality. It optionally takes the following parameters.

  • Collection
  • Modality
  • Body Part Examined

Example Manufacturer Values and Counts Query

Code Block
titleSample Call
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.

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

Manufacturer Tree API

The Manufacturer Tree API returns the manufacturer and software in a tree structure.

Example Manufacturer Values and Counts Query

Code Block
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.

Code Block
{"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

MD5 Hash for Image API

This API takes the SOPInstanceIUD and returns an MD5 hash.

The API takes one argument:

  • sopInstanceUid - UID of the image

Example MD5 Hash for Image Query

Code Block
titleSample Call
curl -H "Authorization:Bearer 295382ae-e94c-473c-a98e-db10ce6ad774" -k "http://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 will return the modality values plus the subject count for the modality it optionally takes the following parameters.

  • Collection
  • BodyPartExamined

Example Modality Values and Counts Query

Code Block
titleSample Call
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.

Code Block
titleSample Return Value
[
{"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

Code Block
titleSample Call
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.

Code Block
titleSample Return Value
"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"

Simple Search Criteria Values API

The Simple Search Criteria Values API returns the possible criteria values to the client.

  • This API takes the same parameters as simple search.

Example Simple Search Criteria Values Query

Code Block
titleSample Call
curl -H "Authorization:Bearer 544bc1c7-6ea5-421c-9d10-b88ed7e52bfb" -k "https://services.cancerimagingarchive.net/nbia-api/services/getSimpleSearchCriteriaValues" -d "criteriaType0=CollectionCriteria&value0=TCGA-UCEC"

The API returns the possible criteria values.

Code Block
titleSample Return Value
[
{
"criteria":"Collections",
"values":[
{ "criteria":"CBIS-DDSM", "count":"80" }
,
{ "criteria":"BREAST-DIAGNOSIS", "count":"8" }
,

{ "criteria":"Head-Neck Cetuximab", "count":"3" }
]
},
{
"criteria":"Image Modality",
"values":[
{ "criteria":"PT", "count":"3" }
,
{ "criteria":"CT", "count":"3" }
,
{ "criteria":"MR", "count":"8" }
,

{ "criteria":"MG", "count":"82" }
]
}
]

Species Tax API

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

Example Species Tax Query

Code Block
titleSample Call
C:\curl>curl -H "Authorization:Bearer 0a6c0a95-1919-4430-888d-5375fca7566f" -k "https://services.cancerimagingarchive.net/nbia-api/services/getSpeciesTax"

The API returns the current species taxonomy.

Code Block
titleSample Return Value
[\{"speciesCode":"L-877FC","speciesDescription":"Rattus norvegicus (common rat)"},\{"speciesCode":"L-85003","speciesDescription":"Human (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 simple search.

Example Species Values And Counts Query

Code Block
titleSample Call
C:\curl>curl -H "Authorization:Bearer 9227f2ee-5936-4fe9-8268-131e50833527" -k "https://services.cancerimagingarchive.net/nbia-api/services/getSimpleSearchCriteriaValues" -d "criteriaType0=CollectionCriteria&value0=CBIS-DDSM"

The API returns the values and counts for species.

Code Block
titleSample Return Value
[{"criteria":"Collections","values":[

{"criteria":"CBIS-DDSM","count":"80"}
]},

{"criteria":"Species","values":[\{"criteria":"Human","count":"80"}
]},

{"criteria":"Image Modality","values":[\{"criteria":"MG","count":"80"}
]},

{"criteria":"Anatomical Site","values":[\{"criteria":"BREAST","count":"80"}
]},

{"criteria":"Manufacturer","values":[\{"criteria":"","count":"80"}
]}]

Study Drill Down API

The 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

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

The Study Drill Down API returns JSON with the information to populate the drill down to study screen. You can retrieve multiple studies.

Code Block
titleSample Return Value
[ {"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  } ]} ]

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 

Code Block
titleSample Call
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 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.

Code Block
titleSample Return Value
[ {"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

Code Block
titleSample Call
curl -H "Authorization:Bearer f314f9bb-6752-4c5d-9f56-d2d450b7260c" -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 

Code Block
titleSample Call
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.

Code Block
titleSample Return Value
[{
"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

Code Block
titleSample Call
curl -H "Authorization:Bearer 86d45ad0-2e48-4f10-bbbe-593d7176fe30" -k "http://services.cancerimagingarchive.net/nbia-api/services/v2/getUpdatedSeries?fromDate=01/01/2020"

The API returns the updated series.

Code Block
titleSample Return Value
[
   {
      "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
   }


...