Summary
...
This
...
page describes
...
The API is a RESTful interface, accessed through web URLs. There is no software that an application developer needs to download in order to use the API. The application developer can build their own access routines using just the API documentation provided. The interface employs a set of predefined query functions (see REST API Directory) that access TCIA databases.
the representational state transfer application programming interface (REST API) implementations that can be used to access TCIA data and resources. The APIs complement the existing web interfaces and enable developers to build direct access to TCIA data into their applications using only the API documentation provided. The application developer must ensure that they and the users of their applications comply with the TCIA Data Usage Policy. If you are interested in using the
...
APIs and have any questions, please contact
...
What's new
The following characteristics apply to all TCIA APIs:
Version 3
- Two new APIs have been added (/getSingleImage, /getSOPInstanceUIDs)
- Three new APIs have been added (/NewPatientsInCollection, /NewStudiesInPatientsCollection, /PatientsByModality
- The getSeries API has been modified to include new query parameters
- Bug Fixes
Version 2 (Documentation for Version 2. can be found here)
- You can access the metadata of an API by appending /metadata to the end of a QueryEndpoint, without any QueryParameters (See below). The metadata is in JSON format and conforms to this schema
- Most APIs can return results as CSV/JSON/XML/HTML. You can specify the return format by including the query parameter format
Getting Started with the TCIA API
Getting access to the API:
- Every request must contain an API-KEY. The key can be included in the url by adding an extra query parameter api_key
or it can be included in the HTTP headers.
You can obtain one API-KEY and use that for your application; you do not need a separate API-KEY for each user of your software.
NOTE: Due to a configuration issue in our load balancer, API-Keys are only accepted if they are included in the URL as an extra query parameter. This is temporary and will be resolved soon (over the holidays). - To obtain an API-Key:
- If you don't have a TCIA account, please create one by visiting https://public.cancerimagingarchive.net/ncia/login.jsf
- If you already have a TCIA account, please send a request to help@cancerimagingarchive.net
The following characteristics apply to all TCIA APIs:
- You access a resource by sending an HTTP request to the TCIA API server. The server replies with a response that either contains the data you requested, or a status indicator.
- You can access the metadata of an API by appending /metadata to the end of the query. See examples. The metadata is in JSON format and conforms to this schema
- Most APIs can return results as CSV/JSON/XML/HTML. You can specify the return format by including the query parameter format
- An API request takes the following structure:
<BaseURL><Resource><QueryEndpoint>?<QueryParameters><Format>
For example, the API shown below is a request to get all studies in the TCGA-GBM collection for patient GBM-0123 as CSV
https://services.cancerimagingarchive.net/services/v3/TCIA/query/getPatientStudy?Collection=TCGA-GBM&PatientID=GBM-0123&format=csv
This can be broken down as follows:
BaseURL | https://services.cancerimagingarchive.net/services/v3 | The BaseURL includes the version number of this API (v3 in this example) |
---|---|---|
Resource | /TCIA | |
QueryEndpoint | /query/getPatientStudy | |
Query Parameters | Collection=TCGA-GBM & PatientID=GBM-0123 | |
Format | format=csv | Some APIs support CSV/HTML/XML/JSON, while others only support a single return type. Therefore this is required only in instances where multiple return types are supported. |
- Coding examples and a SDK (in Python & Java) can be found on here
- Interface documentation can be found on Mashape. The table below contains the most up-to-date documentation of the API.
- The interface is registered on ProgrammableWeb
API Reference
The full API consists of a base URL followed by the api and the query parameters in that order.
Resource | QueryEndpoint | Query Parameters All query parameters areoptional unless stated otherwise | Format | Description |
---|---|---|---|---|
/TCIA |
| |||
/query/getCollectionValues | None | CSV/HTML/XML/JSON | Set of all collection names | |
/query/getModalityValues | Collection / BodyPartExamined | CSV/HTML/XML/JSON | Set of all modality values (CT, MR, ...) filtered by query keys | |
/query/getBodyPartValues | Collection / Modality | CSV/HTML/XML/JSON | Set of all body part names filtered by query keys | |
/query/getManufacturerValues | Collection / Modality / BodyPartExamined | CSV/HTML/XML/JSON | Set of all manufacturer names filtered by query keys | |
/query/getPatient | Collection | CSV/HTML/XML/JSON | Set of patient objects filtered by query keys | |
/query/PatientsByModality | Collection (R) Modality (R) | CSV/HTML/XML/JSON | Returns a list of PatientIDs, given a specific Collection Name and Modality | |
/query/getPatientStudy | Collection / PatientID / StudyInstanceUID | CSV/HTML/XML/JSON | Set of patient/study objects filtered by query keys | |
/query/getSeries | Collection / StudyInstanceUID / | CSV/HTML/XML/JSON | Set of series objects filtered by query keys | |
/query/getSeriesSize | SeriesInstanceUID (R) | CSV/HTML/XML/JSON | Set of total byte size and object count filtered by query key | |
/query/getImage | SeriesInstanceUID (R) | ZIP | Set of images in a zip file | |
/query/NewPatientsInCollection | Date (R) | CSV/HTML/XML/JSON | Returns a set of Patients that have been added to a specified collection since a specified date. | |
/query/NewStudiesInPatientCollection | Date (R) Collection (R) PatientID | CSV/HTML/XML/JSON | Returns a set of Studies that have been added to a specified collection, and optionally to a patient since a specified date Date is specified as (YYYY-MM-DD)Use the getCollectionValues to get the list of available collections | |
/query/getSOPInstanceUIDs | SeriesInstanceUID (R) | CSV/HTML/XML/JSON | Return a list of SOPInstanceUID for a given series using the SeriesInstanceUID | |
/query/getSingleImage | SeriesInstanceUID (R) SOPInstanceUID (R) | Raw DICOM Object | Returns a SINGLE DICOM Object that is identified by its SeriesInstanceUID and SOPInstanceUID. This API will always be used following the /getSOPInstanceUIDs | |
/SharedList | ||||
/query/ContentsByName | name (R) | JSON | Given the name of a shared list return its contents. |
API Metadata
The API now supports the ability to programmatically access the metadata about your API. This information is provided as a JSON document and includes:
Name of API
Free text description
List of Query Parameters
Supported Return Types
A description of the returned attributes: Name, DICOM Tag and Description
Example:
Let us say we wanted metadata for the getPatientStudy query from our earlier example. The query would look as follows:
https://services.cancerimagingarchive.net/services/v3/TCIA/query/getPatientStudy/metadata
Or in other words, the query would have the following structure:
<BaseURL><Resource><QueryEndpoint>/metadata
(Warning) Don’t forget to include the api-key in either HTTP headers or the URL of the API.
Return Values
Click here to see more details on the return values.
Testing the API
There are two RESTful servers provided by TCIA. A test system is loaded with a small set of known data to allow you to test your applications. The production system is configured to use the full TCIA database. The query format is the same for both systems. The base URLs are:
Type | URL |
---|---|
Production | https://services.cancerimagingarchive.net/services/v3/TCIA/query |
Test | https://services-test.cancerimagingarchive.net/services/v3/TCIA/query |
Click Here to see the test data that has been loaded on these test servers have the following test data
Warning |
---|
The Test system does not share API-Keys with the production system. You must request access to the test system. |
the TCIA Help Desk except where otherwise noted.
- NBIA REST APIs: Provided as part of the NBIA software, these APIs provide access to the search and download functions used in the TCIA radiology portal, and allow access to both public and limited access DICOM collections.
- The NBIA Search REST APIs allow you to perform basic queries and download data for image analysis on public collections.
- The NBIA Search with Authentication REST APIs allow you to perform basic queries on and download data for image analysis from public and restricted collections.
- The NBIA Advanced REST APIs also allow access to public and restricted collections, but are geared towards developers seeking to integrate searching and downloading TCIA data into their own web and desktop applications.
- DataCite REST API: Each Collection TCIA publishes is issued a Digital Object Identifier (DOI) through DataCite. This API can be used to programmatically access Collection metadata such as their DOIs, titles and abstracts. Please note that this API was not developed by TCIA. See https://support.datacite.org/ for any technical questions. The TCIA Helpdesk may be able to assist if your inquiry is related to the content of the data itself.
- TCIA REST API: [DEPRECATED 6-22-2022] - The TCIA REST API originally developed using Project Bindaas with Emory University, has been deprecated in favor of the NBIA REST APIs. While the NBIA REST APIs have the same functionality as the Bindaas based TCIA REST APIs, there are some differences that should be noted and tested during conversion from the TCIA REST API to the NBIA REST API. Please see the Migration Guide for details. The existing Bindaas based TCIA REST APIs will remain active but will receive no updates or maintenance going forward. They also do not contain an up-to-date view of our available datasets, so newer collections will not appear if you use them.
TCIA_Utils
The tcia_utils package contains functions to simplify common tasks one might perform when interacting with The Cancer Imaging Archive (TCIA) via Python. Issues with this package should be submitted at https://github.com/kirbyju/tcia_utils/issues. Example notebooks demonstrating tcia_utils functionality can be found at https://github.com/kirbyju/TCIA_Notebooks.
Installation can be achieved with this Pip command:
Code Block |
---|
pip install tcia_utils |
To import functions related to NBIA for accessing our DICOM radiology data:
Code Block |
---|
from tcia_utils import nbia |
To import functions related to pathDB for accessing our digitized pathology data:
Code Block |
---|
from tcia_utils import pathdb |
To import functions related to Datacite for querying Collection metadata such as their DOIs, titles and abstracts:
Code Block |
---|
from tcia_utils import datacite |
TCIA Data Usage Policy
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|