Purpose of this Guide
The National Biomedical Imaging Archive (NBIA) REST APIs are provided to access the search and download functions used in the TCIA radiology portal.
The NBIA Search REST APIs, described on this page, allow you to perform basic queries on and download data for image analysis from public collections.
The NBIA Search with Authentication REST APIs, described in the NBIA Search with Authentication REST API Guide, allow you to use the same APIs described on this page to query and download data from restricted collections.
The NBIA Advanced REST APIs, described in the NBIA Advanced REST API Guide, provide advanced features geared towards developers seeking to integrate searching and downloading TCIA data into their own web and desktop applications.
Run APIs Live on the Cloud
You can find examples for using the NBIA APIs with Python in these Jupyter Notebooks. They are set up so that you can run them in Google Colab without the need to configure your own development environment.
NBIA Search REST API URL and Format
A call includes a base URL followed by the API and query parameters, in that order. The base URL to access public data is https://services.cancerimagingarchive.net/nbia-api/services/v1.
Base URL for NLST Data
To access National Lung Screening Trial (NLST) data, use the following base URL instead: https://nlst.cancerimagingarchive.net/nbia-api/services/
For example, in the following URL:
https://services.cancerimagingarchive.net/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://services.cancerimagingarchive.net/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. JSON is the default return format if no format parameter is specified
- The order in which the query parameters are provided does not matter.
- NBIA Search REST APIs can only access public data. If you want to use these APIs to access restricted collections, see NBIA Search with Authentication REST API Guide.
Use the APIs in the following table to download images from TCIA. Query Name Return Values Output Format Query Parameters getImage An object that represents a set of images in a ZIP file based on SeriesInstanceUID. The naming scheme for the NewFileNames parameter changes from sequential numbers to ZIP SeriesInstanceUID (R) NewFileNames (O) - Accepted values are Yes and No. getImageWithMD5Hash All images in the series and MD5 hash values getSingleImage A 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) Use the APIs in the following table to explore the metadata of objects in the TCIA database. Queries return a file in one of these data formats: CSV, HTML, XML, and JSON. JSON is the default return format if no format parameter is specified. Query Name Return Values Query Parameters getBodyPartValues Set of all body part names filtered by query keys Collection (O) Modality (O) getCollectionValues Set of all collection names None getContentsByName Return the contents of your cart. To get the name of the cart contents, you must add data to your cart in the TCIA Radiology Portal, and then select Share My Cart. An example of the URL that appears is https://nbia.cancerimagingarchive.net/nbia-search/?saved-cart=nbia-54241629300063058. The cart name is what follows the equal sign, so in this example, the cart name is nbia-54241629300063058. getManufacturerValues Set of all manufacturer names filtered by query keys Collection (O) BodyPartExamined (O) Modality (O) getModalityValues Set of all modality values (CT, MR, ...) filtered by query keys Collection (O) BodyPartExamined (O) NewPatientsInCollection Set of patients, in a specified collection, since a specified date Collection (R) Date (R) NewStudiesInPatientCollection Set of new studies for given patient and collection since a specified date API example and return values for NewStudiesInPatientCollection Collection (R) Date (R) PatientID (R) getPatient Set of patient objects filtered by query keys Collection (O) getPatientByCollectionAndModality Returns a list of PatientIDs, given a specific Collection Name and Modality API example and return values for getPatientByCollectionAndModality Collection (R) Modality (R) getPatientStudy Set of patient/study objects filtered by query keys Collection (R) PatientID (O) StudyInstanceUID (O) getSeries Set of series objects filtered by query keys Collection (O) PatientID (O) StudyInstanceUID (O) Modality (O) SeriesInstanceUID (O) BodyPartExamined (O) ManufacturerModelName (O) Manufacturer (O) SeriesInstanceUID (O) getSeriesMetaData All of the metadata for a given SeriesInstanceUID getSeriesSize Set of total byte size and object count filtered by query key getSOPInstanceUIDs A list of SOPInstanceUIDs for a given series using the SeriesInstanceUID SeriesInstanceUID (R) Set of series updated since a specified dateImage Download APIs
Usage acquisition number - instance number (in correct order).Used for bulk transfer of all images in a series. ZIP SeriesInstanceUID (R) Used for bulk transfer of images with the ability to check MD5Hash. Used to retrieve a single image. Image Metadata APIs
name (R) SeriesInstanceUID (R) SeriesInstanceUID (R) getUpdatedSeries fromDate (R)
Return Values
This section lists and explains the return values of the APIs included in both tables above.
If the value for an attribute is not populated in the specified collection, it will not appear in the returned values.
- getBodyPartValues
- getCollectionValues
- getContentsByName
- getImage
- getImageWithMD5Hash
- getManufacturerValues
- getModalityValues
- NewPatientsInCollection
- NewStudiesInPatientCollection
- getPatient
- getPatientByCollectionAndModality
- getPatientStudy
- getSeries
- getSeriesMetaData
- getSeriesSize
- getSingleImage
- getSOPInstanceUIDs
- getUpdatedSeries
getBodyPartValues
https://services.cancerimagingarchive.net/nbia-api/services/v1/getBodyPartValues
| Attribute | DICOM Tag | Description |
|---|---|---|
| BodyPartExamined | 0018, 0015 | Standard DICOM definition |
"[
{ },
{
BodyPartExamined: ""ABD PEL""
},
{
BodyPartExamined: ""ABD PELV""
},
{
BodyPartExamined: ""ABDOMEN""
},
{
BodyPartExamined: ""ABDOMENPELVIS""
},"
getCollectionValues
https://services.cancerimagingarchive.net/nbia-api/services/v1/getCollectionValues
| Attribute | DICOM Tag | Description |
|---|---|---|
| Collection | N/A | A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data. |
[
{
Collection: "4D-Lung"
},
{
Collection: "AAPM-RT-MAC"
},
{
Collection: "ACRIN-FLT-Breast"
},
{
Collection: "ACRIN-FMISO-Brain"
},
{
Collection: "ACRIN-NSCLC-FDG-PET"
},
getContentsByName
https://services.cancerimagingarchive.net/nbia-api/services/v1/getContentsByName?name=TCIA_TCGA-PRAD_08-09-2016-v3
| Attribute | DICOM Tag | Description |
|---|---|---|
SeriesInstanceUID | 0020, 000E | Has been de-identified as part of submission process |
StudyInstanceUID | 0020, 000D | Has been de-identified as part of submission process. |
Modality | 0008, 0060 | Standard DICOM definition |
ProtocolName | 0018, 1030 | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
SeriesDate | 0008, 0021 | Standard DICOM definition |
SeriesDescription | 0008, 103E | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
BodyPartExamined | 0018, 0015 | Standard DICOM definition |
SeriesNumber | 0020, 0011 | Standard DICOM definition |
AnnotationsFlag | N/A | Indicates if there are annotations for a collection |
Collection | N/A | A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data. |
PatientID | 0010, 0020 | Has been de-identified as part of submission process. |
Manufacturer | 0008, 0070 | Standard DICOM definition |
ManufacturerModelName | 0008, 1090 | Standard DICOM definition |
SoftwareVersions | 0018, 1020 | Standard DICOM definition |
ImageCount | N/A | Number of images in the specified series |
getImage
The license file, which includes the data usage agreement, is included in the returned ZIP file.
https://services.cancerimagingarchive.net/nbia-api/services/v1/getImage?SeriesInstanceUID=1.3.6.1.4.1.9328.50.1.216116555221814778114703363464001196508
| Attribute | DICOM Tag | Description |
|---|---|---|
| N/A | N/A | Set of images in a ZIP file |
getImageWithMD5Hash
https://services.cancerimagingarchive.net/nbia-api/services/v1/getImageWithMD5Hash?SeriesInstanceUID=1.3.6.1.4.1.14519.5.2.1.6919.4624.313514201353787659031503464798
Attribute | DICOM Tag | Description |
|---|---|---|
| N/A | N/A | Set of images in a ZIP file |
getManufacturerValues
https://services.cancerimagingarchive.net/nbia-api/services/v1/getManufacturerValues
Attribute | DICOM Tag | Description |
|---|---|---|
Manufacturer | 0008, 0070 | Standard DICOM definition |
getModalityValues
https://services.cancerimagingarchive.net/nbia-api/services/v1/getModalityValues
| Attribute | DICOM Tag | Description |
|---|---|---|
| Modality | 0008, 0060 | Standard DICOM definition |
NewPatientsInCollection
https://services.cancerimagingarchive.net/nbia-api/services/v1/NewPatientsInCollection?Collection=CBIS-DDSM&Date=2010/08/16
| Attribute | DICOM Tag | Description |
|---|---|---|
| PatientID | 0010, 0020 | Has been de-identified as part of submission process. |
| PatientName | 0010, 0010 | Has been de-identified as part of submission process. |
| PatientBirthDate | 0010,0030 | Has been de-identified as part of submission process. |
| PatientSex | 0010,0040 | Standard DICOM definition |
| EthnicGroup | 0010,2160 | Standard DICOM definition |
| Collection | N/A | A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data. |
| Phantom | 0010, 0200 | Indicates whether or not the subject is a quality control phantom. |
| SpeciesCode | 0010,2202 | The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient. |
| SpeciesDescription | 0010,2201 | The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient. |
NewStudiesInPatientCollection
https://services.cancerimagingarchive.net/nbia-api/services/v1/NewStudiesInPatientCollection?Collection=CBIS-DDSM&Date=2010/08/16
| Attribute | DICOM Tag | Description |
|---|---|---|
StudyInstanceUID | 0020, 000D | Has been de-identified as part of submission process. |
StudyDate | 0008, 0020 | Has been de-identified as part of submission process. Longitudinal information is preserved. |
StudyDescription | 0008, 1030 | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
AdmittingDiagnosesDescription | 0008, 1080 | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
StudyID | 0020, 0010 | Has been de-identified as part of submission process. |
PatientAge | 0010, 1010 | Standard DICOM definition |
PatientID | 0010, 0020 | Has been de-identified as part of submission process. |
PatientName | 0010, 0010 | Has been de-identified as part of submission process. |
PatientBirthDate | 0010, 0030 | Has been de-identified as part of submission process. |
PatientSex | 0010, 0040 | Standard DICOM definition |
EthnicGroup | 0010, 2160 | Standard DICOM definition |
Collection | N/A | A 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 | N/A | Computed number of series |
LongitudinalTemporalEventType | 0012, 0053 | The type of event to which Longitudinal Temporal Offset from Event (0012,0052) is relative. |
LongitudinalTemportalOffsetFromEvent | 0012, 0052 | An offset in days from a particular event of significance. May be fractional. In the context of a clinical trial, this is often the days since enrollment, or the baseline imaging Study. |
getPatient
https://services.cancerimagingarchive.net/nbia-api/services/v1/getPatient
| Attribute | DICOM Tag | Description |
|---|---|---|
| PatientId | 0010, 0020 | Has been de-identified as part of submission process. |
| PatientName | 0010, 0010 | Has been de-identified as part of submission process. |
| PatientBirthDate | 0010, 0030 | Has been de-identified as part of submission process. |
| PatientSex | 0010, 0040 | Standard DICOM definition |
| EthnicGroup | 0010, 2160 | Standard DICOM definition |
| Collection | N/A | A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data. |
| Phantom | 0010, 0200 | Indicates whether or not the subject is a quality control phantom. |
| SpeciesCode | 0010,2202 | The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient. |
| SpeciesDescription | 0010,2201 | The taxonomic rank value (e.g., genus, subgenus, species or subspecies) of the Patient. |
getPatientByCollectionAndModality
https://services.cancerimagingarchive.net/nbia-api/services/v1/getPatientByCollectionAndModality?Collection=VICTRE&Modality=MG
| Attribute | DICOM Tag | Description |
|---|---|---|
| PatientId | 0010, 0020 | A list of patient IDs for a specified collection and modality |
getPatientStudy
https://services.cancerimagingarchive.net/nbia-api/services/v1/getPatientStudy?Collection=VICTRE&Modality=MG
| Attribute | DICOM Tag | Description |
|---|---|---|
| StudyInstanceUID | 0020, 000D | Has been de-identified as part of submission process. |
| StudyDate | 0008, 0020 | Has been de-identified as part of submission process. Longitudinal information is preserved. |
| StudyDescription | 0008, 1030 | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
| AdmittingDiagnosesDescription | 0008, 1080 | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
| StudyID | 0020, 0010 | Has been de-identified as part of submission process. |
| PatientAge | 0010, 1010 | Standard DICOM definition |
| PatientID | 0010, 0020 | Has been de-identified as part of submission process. |
| PatientName | 0010, 0010 | Has been de-identified as part of submission process. |
| PatientBirthDate | 0010, 0030 | Has been de-identified (emptied) as part of submission process. |
| PatientSex | 0010, 0040 | Standard DICOM definition |
| EthnicGroup | 0010, 2160 | Standard DICOM definition |
| Collection | N/A | A 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 | N/A | Computed number of series |
LongitudinalTemporalEventType | 0012, 0053 | The type of event to which Longitudinal Temporal Offset from Event (0012,0052) is relative. |
| LongitudinalTemporalOffsetFromEvent | 0012, 0052 | An offset in days from a particular event of significance. May be fractional. In the context of a clinical trial, this is often the days since enrollment, or the baseline imaging Study. |
getSeries
https://services.cancerimagingarchive.net/nbia-api/services/v1/getSeries?Collection=VICTRE&Modality=MG
| Attribute | DICOM Tag | Description |
|---|---|---|
| SeriesInstanceUID | 0020, 000E | Has been de-identified as part of submission process |
| StudyInstanceUID | 0020, 000D | Has been de-identified as part of submission process |
| Modality | 0008, 0060 | Standard DICOM definition |
| ProtocolName | 0018, 1030 | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
| SeriesDate | 0008, 0021 | Standard DICOM definition |
| SeriesDescription | 0008, 103E | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
| BodyPartExamined | 0018, 0015 | Entered on a per collection basis using relevant SNOMED terms |
| SeriesNumber | 0020, 0011 | Standard DICOM definition |
| AnnotationsFlag | N/A | Indicates if there are annotations for a collection |
| Collection | N/A | A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data. |
| PatientID | 0010, 0020 | Has been de-identified as part of submission process |
| Manufacturer | 0008, 0070 | Standard DICOM definition |
| ManufacturerModelName | 0008, 1090 | Standard DICOM definition |
| SoftwareVersions | 0018, 1020 | Standard DICOM definition |
| ImageCount | N/A | Computed number of images in this series |
| TimeStamp | N/A | Date the series was released |
| LicenseName | N/A | License that applies to this series |
| LicenseURI | N/A | URL of license source |
| CollectionURI | N/A | URI of collection |
| FileSize | N/A | File size |
getSeriesMetaData
https://services.cancerimagingarchive.net/nbia-api/services/v1/getSeriesMetaData?SeriesInstanceUID=1.3.6.1.4.1.14519.5.2.1.6834.5010.322628904903035357840500590726
| Attribute | DICOM Tag | Description |
|---|---|---|
Series UID | 0020, 000E | Standard DICOM definition |
Collection | N/A | A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data. |
3rd Party Analysis | N/A | Data from third-party analysis results |
Data Description URI | N/A | Location of the data description |
Subject ID | N/A | Unique identifier for the subject |
Study UID | 0020, 000D | Standard DICOM definition |
Study Description | 0008, 1030 | Institution-generated description or classification of the Study (component) performed |
Study Date | 0008, 0020 | Has been de-identified as part of submission process. Longitudinal information is preserved. |
Series Description | 0020, 0011 | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
Manufacturer | 0008, 0070 | Standard DICOM definition |
Modality | 0008, 0060 | Standard DICOM definition |
SOP Class UID | N/A | Unique identifier of the SOP Class |
Number of Images | N/A | Number of images in this series |
File Size | N/A | File size in bytes |
File Location | N/A | Location of the file in the file system |
Series Number | 0020,0011 | Standard DICOM definition |
License Name | N/A | License that applies to this series |
License URL | N/A | URL of license source |
Annotation Size | N/A | Size of annotation files in bytes |
getSeriesSize
https://services.cancerimagingarchive.net/nbia-api/services/v1/getSeriesSize?SeriesInstanceUID=1.3.6.1.4.1.14519.5.2.1.6834.5010.322628904903035357840500590726
| Attribute | DICOM Tag | Description |
|---|---|---|
TotalSizeInBytes | N/A | Byte size of the specified series |
ObjectCount | N/A | Number of objects in the specified series |
getSingleImage
https://services.cancerimagingarchive.net/nbia-api/services/v1/getSingleImage?SeriesInstanceUID=143.284188174537413748743284550513035752067&SOPInstanceUID=143.53599064898089361503082484556513429004
| Attribute | DICOM Tag | Description |
|---|---|---|
| N/A | N/A | Single image in DICOM format |
getSOPInstanceUIDs
https://services.cancerimagingarchive.net/nbia-api/services/v1/getSOPInstanceUIDs?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992
| Attribute | DICOM Tag | Description |
|---|---|---|
| SOPInstanceUID | 0008, 0018 | Uniquely identifies the SOP Instance |
getUpdatedSeries
https://services.cancerimagingarchive.net/nbia-api/services/v1/getUpdatedSeries?fromDate=28/03/2023
| Attribute | DICOM Tag | Description |
|---|---|---|
SeriesInstanceUID | 0020, 000E | Has been de-identified as part of submission process |
StudyInstanceUID | 0020, 000D | Has been de-identified as part of submission process |
Modality | 0008, 0060 | Standard DICOM definition |
ProtocolName | 0018, 1030 | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
SeriesDate | 0008, 0021 | Standard DICOM definition |
SeriesDescription | 0008, 103E | Standard DICOM definition. Has been inspected and cleaned of any PHI. |
BodyPartExamined | 0018, 0015 | Entered on a per collection basis using relevant SNOMED terms |
SeriesNumber | 0020, 0011 | Standard DICOM definition |
AnnotationsFlag | N/A | Indicates if there are annotations for a collection |
Collection | N/A | A label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data. |
PatientID | 0010, 0020 | Has been de-identified as part of submission process. |
Manufacturer | 0008, 0070 | Standard DICOM definition |
ManufacturerModelName | 0008, 1090 | Standard DICOM definition |
SoftwareVersions | 0018, 1020 | Standard DICOM definition |
ImageCount | N/A | Number of images in the specified series |