...
In July and August 2023, the following APIs were added to this guide.
- Collection Descriptions
- Collection Site
- Manifest for Collection
- Manifest for Text Search
- Manifest from Patient Study Series
- MD5 Hierarchy
- Min Max Timepoints
- Restrictions for Text Search
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 radiology portal.
...
| Table of Content Zone | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Body Part Values and Counts APIThe Body Part Values and Counts API returns the modality values and body part count for the modality. It optionally takes the following parameters.
Example Body Part Values and Counts Query
Sample Results The API returns the body parts and their counts.
Collection DescriptionsThis API takes a collection name and returns the collection's description. The API takes one parameter:
Example GetCollectionDescriptions Query
If successful, the API returns the collection description.
Collectionor Series for DOIValues and Counts APIThe Collection or Series for DOI Values and Counts API returns the collections and the subject count for the collection and/or series with the Digital Object Identifier (DOI). Example Collectionor Series for DOIValues And Counts Query
The API returns the collections with their counts.
Collection SiteThe API returns all collections/sites in TCIA in JSON format. The API does not take any parameters. Example GetCollectionSite Query
Collection Values and Counts APIThe Collection Values and Counts API returns the collections and the subject count for the collection. Example Collection Values And Counts
Create Saved Cart APIThe Create Saved Cart API allows the creation of a saved cart. The API takes four arguments:
Example Create Saved Cart Query
The API returns the collections with their counts.
DICOM Metadata by Series UID APIThe DICOM Metadata by Series UID API provides the functionality in the portal where the DICOM data is retrieved from a series. The API takes one argument:
The SeriesUID is available from the Drill Down API call. Example Metadata Query
The API sends back triples of all DICOM element, name, data in the file.
Create Saved Cart APIThe Create Saved Cart API allows the creation of a saved cart. The API takes four arguments:
DICOM Tags By Image ID APIThe DICOM Tag By Image ID API returns the DICOM tags and values associated with the image.
The values used in this API can be derived by using the results of the imagePkId in the Drill Down to Images API. Example DICOM Tags By Image ID Query
DICOM Metadata by Series UID APIThe DICOM Metadata by Series UID API provides the functionality in the portal where the DICOM data is retrieved from a series. The API takes one argument:
The SeriesUID is available from the Drill Down API call. Example Metadata Query
The API sends back triples of all DICOM element, name, data in the file.
The API returns the tags and values.
DICOM Tags By Image ID APIThe DICOM Tag By Image ID API returns the DICOM tags and values associated with the image.
The values used in this API can be derived by using the results of the imagePkId in the Drill Down to Images API. Example DICOM Tags By Image ID Query
Drill Down APIThe Drill Down API provides the functionality in the search client where the user drills down the studies and series associated with a given patient. The API takes a list of series to query, using the parameter "list," that repeats for each series you want to retrieve. During the workflow these values come from the series identifiers in the Extended Simple Search with Modality and Body Part Paged Query. Example Drill Down Query
The Drill Down API returns the tags and valuesJSON with the information to populate the drill down to study screen. There can be multiple studies.
Drill Down APIThe Drill Down API provides the functionality in the search client where the user drills down the studies and series associated with a given patient. The API takes a list of series to query, using the parameter "list," that repeats for each series you want to retrieve. During the workflow these values come from the series identifiers in the Extended Simple Search with Modality and Body Part Paged Query. Example Drill Down Query
The Drill Down API returns JSON with the information to populate the drill down to study screen. There can be multiple studies.
Drill Down Using Series UIDs APIThe Drill Down Using Series UIDs API provides the functionality in the portal where the user drills down the studies and series associated with a set of IDs. In this case, the API takes Series Instance UIDs so the users can access this information outside of the Search Client workflow using any Series Instance UIDs that they are interested in. The API simply takes a list of Series UIDs to query, using the parameter "list," that repeats for each Series UID you want to retrieve. Example Drill Down Using Series UIDs Query
The Drill Down Using Series UIDs API returns JSON with the information to populate the drill down to study screen. You can retrieve multiple studies.
Drill Down to Images APIThe Drill Down to Images API allows the developer to drill down to the images in a series and have the information available to create a WADO call that can retrieve the images themselves. This API is used to create the Thumbnails screen in the portal. The API takes a list of series to query, using the parameter "list," that repeats for each series for which you want to retrieve images. Example Drill Down to Images Query
The API returns the information needed to populate the Thumbnails screen.
The information needed to create a WADO call is the following snippet from this code:
Extended Simple Search with Modality and Body Part Paged APIThe Extended Simple Search with Modality and Body Part Paged API is used to run queries for the Simple Search GUI in the NBIA client. This API uses a variety of criteria as seen in the NBIA client, as well as the pages of data the client requests. The available criteria types and their components follow. Since the simple search can take an unlimited number of criteria each of the criteria items is appended with a number signifying its order in the query, starting with 0.
Example Extended Simple Search with Modality and Body Part Paged Query
The API returns the results of the search.
Image with MD5 Hash APIThis API takes a series UID and returns a zip file with the images and a CSV file containing the MD5 hashes. The API takes two arguments:
Example Image with MD5 Hash Query
The API returns the images and a CSV file in the zip file that records the file name and a hash. Licenses APIThe Licenses API retrieves all available license information. The API takes no arguments. Example Licenses Query
If the API is successful, it returns the license long name, short name, license URL, license text, and commercial use designation., and commercial use designation.
Manifest for Simple Search APIThe Manifest Text for Simple Search API allows the creation of a manifest file that can be used to execute the NBIA Data Retriever. The API takes the same arguments as the Simple Search GUI. Example Manifest for Simple Search Query
The API returns text that can be used as a manifest file for the NBIA Data Retriever.
Manifest Text API
Manifest for Simple Search APIThe Manifest Text for Simple Search 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: the same arguments as the Simple Search GUI. Example ManifestQueryfor Simple Search Query
The API returns text that can be used as a manifest file for the NBIA Data Retriever.
Manifestfor CollectionThis API takes the collection name and optional parameters and generates a manifest file. The manifest file name includes the collection name and the date and time the file is generated. If the visibility status is not given, the manifest will include only visible series of the specified collection. Multiple visibility statuses can be given but each visibility status needs to be separated by "," which means all series with visibility in the given parametersText APIThe Manifest Text API allows the creation of a manifest file that can be used to execute the NBIA Data Retriever. The API takes the following parameters:
two arguments:
Example Manifest Query
The API returns text that can be used as a manifest file for the NBIA Data Retriever.
Manifest for Text SearchThis API takes a text value and generates a manifest file of series. This is an API version of the text search in the NBIA Radiology Portal GUI. See Performing a Text Search for more information. This API takes the following parameter:
Example getManifestForTextSearch Query
Manifest from Patient Study SeriesThis API takes a a parameter and generates a manifest file of patient IDs that match those parameters. This API takes the following parameters:
Example getManifestFromPatientStudySeries Query
If successful, the API returns the following.
MD5 HierarchyThis API takes the following parameters:
Example getMD5Hierarchy Query
Manufacturer Values and Counts APIThe Manufacturer Values and Counts API returns the modality values plus the manufacturer count for the modality. It optionally takes the following parameters.
Example getManufacturerValuesAndCounts Query
The API returns the manufacturer and their counts.
Manufacturer Tree APIThe Manufacturer Tree API returns the manufacturer and software in a tree structure. Example getManufacturerTree Query
The API returns the data in a tree structure.
MD5 Hash for Image APIThis API takes the SOPInstanceIUD and returns an MD5 hash. The API takes one argument:
Example MD5 Hash for Image Query
The API returns the MD5 hash. Min Max TimepointsExample getMinMaxTimepoints Query
Code Block | | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
.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
| Code Block | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
[
{"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
| Code Block | ||
|---|---|---|
| ||
curl -H "Authorization:Bearer 1fb4f3b5-f30e-4ccf-bea9-8b51183a70cd" -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.
Restrictions for Text Search
| Code Block | ||
|---|---|---|
| ||
curl -H "Authorization:Bearer 083c39d8-1316-4ec6-8bc9-7ae0163e2d0b" -X POST "https://services.cancerimagingarchive.net/nbia-api/services/getRestrictionsForTextSearch" -d "textValue=CT" |
| title | Sample Response |
|---|
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 | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
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
| Code Block | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
[\{"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 the Simple Search GUI.
Example Species Values And Counts Query
| Code Block | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
[{"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 | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
[ {"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 | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
[ {"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 | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
[{
"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 | ||
|---|---|---|
| ||
curl -H "Authorization:Bearer 86d45ad0-2e48-4f10-bbbe-593d7176fe30" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getUpdatedSeries?fromDate=01/01/2020" |
The API returns the updated series.
| Code Block | ||
|---|---|---|
| ||
[
{
"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
} |
...