TCIA Collection Manager REST API Manual
The new TCIA Collection Manager REST API is accessible using HTTP methods GET, POST, and DELETE. You can also use any browser to request the data. The resulting response must be parsed using JSON.parse() or XMLHttpRequest() to output to raw JSON format.
The collection manager meta data fields return inline field data and relational field data. Some of the relational fields require further iterative requests to return the related data.
For example, when requesting a collection’s metadata, the expected response will include something that looks like this, below. You can see that most of the data is what we expected to see. However, ‘collection_downloads’ is not. The returned value “TCGA-SARC” points to relational data that contains all of the details of that download. For more information, see “Requesting related fields“.
[
{
"citations": "TCIA Collection Citation",
"collection_doi": "<a href='https://doi.org/10.7937/K9/TCIA.2016.CX6YLSUX' target='_blank'>https://doi.org/10.7937/K9/TCIA.2016.CX6YLSUX</a>",
"collection_downloads": "TCGA-SARC",
"collection_title": "The Cancer Genome Atlas Sarcoma Collection",
"collection_short_title": "TCGA-SARC",
"collection_abstract": "<p>The Cancer Genome Atlas Sarcoma (TCGA-SARC) data collection is part of a larger effort to build a resear...
}
]
Requesting collection manager metadata:
Data can be requested using a series of endpoints, URLs, and, optionally, specified fields ( referenced via field slugs).
To request all data, use this endpoint:
https://cancerimagingarchive.net/api/v1/collections/
To request a filtered array, append the endpoint with specified fields:
https://cancerimagingarchive.net/api/v1/collections/?&_fields=[a_field_slug],[another_field_slug]...†
The amount of data returned depends upon which fields are specified.
† Append as many fields as desired using the available field slugs in the table below.
Example request with actual field slugs:
https://cancerimagingarchive.net/api/v1/collections/?&_fields=id,slug,collection_doi,collection_short_title,collection_title,collection_abstract,collection_downloads,citations
To request by ‘id’:
https://cancerimagingarchive.net/api/v1/collections/?include=id,id,id...
Example:
https://cancerimagingarchive.net/api/v1/collections/?include=207,544
To add search criteria to a request:
https://cancerimagingarchive.net/api/v1/collections/?search=[text_and-or_numerals]
Example:
https://cancerimagingarchive.net/api/v1/collections/?search=sarc
Available Collection metadata fields:
Available Downloads metadata fields:
Available Licenses metadata fields:
Available Citations metadata fields/field slugs:
Available Download Requirements metadata fields/field slugs:
Requesting relational fields:
For this section, we will look at requesting related download(s) metadata (ie, file size, file type, number of subjects, file URL, etc.), but the same approach works for any relational data. To access other related data, use the documented REST API endpoints for the data you wish to request. (As of this writing, there are only two relational data types to access for collections: downloads and citations.)
Relational download(s) data are requested using the endpoints ending with the specified related download(s) field slug(s).
To request all related download fields, you must request each related download dataset and its related fields :
Start with the downloads endpoint and add the collection downloads field value(s), which will be the slug of the related data, as shown below. In the first example, we are going to request data from the TCGA-SARC collection. Its slug is ‘tcga-sarc’.
Example 1. Request single related download (to use in a script loop):
https://cancerimagingarchive.net/api/v1/downloads/?id=549
Example 2. Request multiple related downloads (returns an array). In this example, we are requesting data from a collection that returns three downloads by record IDs:
https://cancerimagingarchive.net/api/v1/downloads/?id=348,549,560
The above examples will load all available associated collection download(s) field data. To filter and refine your request, see the next section.
To add a filtered array of fields, append the above endpoint with specified fields:
The example below is requesting the download metadata for TCGA-SARC (tcga-sarc), and for one field only: Data Type (field slug: data_type).
https://cancerimagingarchive.net/api/v1/downloads/?id=id_num&_fields=data_type...†
The amount of data returned depends upon which fields (via field slugs) are specified.
† Append as many fields as desired using field slugs below.
Here is an example using real collection download metadata:
Filtered response:
[{“id”:549,”slug”:”tcga-sarc”,”status”:”publish”,”data_type”:[“Radiology Images”],”file_type”:[“DICOM”],”download_url”:”https:\/\/wiki.cancerimagingarchive.net\/download\/attachments\/19039714\/TCIA_TCGA-SARC_09-16-2015.tcia?version=1&modificationDate=1534787003333&api=v2″,”download_size”:”3″,”search_url”:”https:\/\/www.cancerimagingarchive.net\/nbia-search\/?CollectionCriteria=TCGA-SARC”,”cancer_type”:[“Sarcomas”],”cancer_location”:[“Chest-Abdomen-Pelvis”,”Leg”,”TSpine”],”species”:[“Human”],”subjects”:”5″,”modalities”:[“CT”,”MR”,”Pathology”],”supporting_data”:[“Clinical”,”Genomics”],”collection_status”:”Complete”}]
For comparison, here is the unfiltered response:
[{“id”:560,”date”:”2023-05-01T19:17:37″,”date_gmt”:”2023-05-01T19:17:37″,”guid”:{“rendered”:”https:\/\/cm.vastapps.dev\/?post_type=tcia_downloads&p=560″},”modified”:”2023-05-01T19:17:37″,”modified_gmt”:”2023-05-01T19:17:37″,”slug”:”orphan-test”,”status”:”publish”,”type”:”tcia_downloads”,”link”:”https:\/\/cm.vastapps.dev\/tcia-downloads\/orphan-test\/”,”title”:{“rendered”:”Orphan Test”},”content”:{“rendered”:”<p>This is an orphan test.<\/p>\n”,”protected”:false},”menu_order”:0,”template”:””,”api”:[],”requirements”:[],”data_type”:[“Pathology Images”],”file_type”:[“DICOM”],”download_url”:”https:\/\/testdownload.com\/”,”download_size”:”0″,”download_size_unit”:”kb”,”search_url”:”https:\/\/testsearch.com\/”,”cancer_type”:[“Cervical Cancer”],”cancer_location”:[“Bile duct”],”species”:[“Human”],”subjects”:”1″,”modalities”:[“Pathology”],”supporting_data”:[“Clinical”],”download_access”:”Public”,”collection_status”:”Complete”,”date_updated”:”2023-05-01″,”tcia_data_license”:[“CC 3.0″],”download_requirements”:”Requires NBIA Data Retriever”,”_links”:{“self”:[{“href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads\/560″}],”collection”:[{“href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads”}],”about”:[{“href”:”https:\/\/cm.vastapps.dev\/wp-json\/wp\/v2\/types\/tcia_downloads”}],”version-history”:[{“count”:1,”href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads\/560\/revisions”}],”predecessor-version”:[{“id”:561,”href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads\/560\/revisions\/561″}],”wp:attachment”:[{“href”:”https:\/\/cm.vastapps.dev\/wp-json\/wp\/v2\/media?parent=560″}],”wp:term”:[{“taxonomy”:”tcia_data_licenses”,”embeddable”:true,”href”:”https:\/\/cm.vastapps.dev\/wp-json\/licenses\/api?post=560″},{“taxonomy”:”tcia_download_requirement”,”embeddable”:true,”href”:”https:\/\/cm.vastapps.dev\/wp-json\/api\/requirements?post=560″}],”curies”:[{“name”:”wp”,”href”:”https:\/\/api.w.org\/{rel}”,”templated”:true}]}},{“id”:549,”date”:”2023-04-24T15:02:45″,”date_gmt”:”2023-04-24T15:02:45″,”guid”:{“rendered”:”https:\/\/cm.vastapps.dev\/?post_type=tcia_downloads&p=549″},”modified”:”2023-04-24T15:02:45″,”modified_gmt”:”2023-04-24T15:02:45″,”slug”:”tcga-sarc”,”status”:”publish”,”type”:”tcia_downloads”,”link”:”https:\/\/cm.vastapps.dev\/tcia-downloads\/tcga-sarc\/”,”title”:{“rendered”:”TCGA-SARC”},”content”:{“rendered”:””,”protected”:false},”menu_order”:0,”template”:””,”api”:[],”requirements”:[],”data_type”:[“Radiology Images”],”file_type”:[“DICOM”],”download_url”:”https:\/\/wiki.cancerimagingarchive.net\/download\/attachments\/19039714\/TCIA_TCGA-SARC_09-16-2015.tcia?version=1&modificationDate=1534787003333&api=v2″,”download_size”:”3″,”download_size_unit”:”gb”,”search_url”:”https:\/\/www.cancerimagingarchive.net\/nbia-search\/?CollectionCriteria=TCGA-SARC”,”cancer_type”:[“Sarcomas”],”cancer_location”:[“Chest-Abdomen-Pelvis”,”Leg”,”TSpine”],”species”:[“Human”],”subjects”:”5″,”modalities”:[“CT”,”MR”,”Pathology”],”supporting_data”:[“Clinical”,”Genomics”],”download_access”:”Public”,”collection_status”:”Complete”,”date_updated”:”2029-05-20″,”tcia_data_license”:[“CC 3.0″],”download_requirements”:”Requires NBIA Data Retriever”,”_links”:{“self”:[{“href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads\/549″}],”collection”:[{“href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads”}],”about”:[{“href”:”https:\/\/cm.vastapps.dev\/wp-json\/wp\/v2\/types\/tcia_downloads”}],”version-history”:[{“count”:1,”href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads\/549\/revisions”}],”predecessor-version”:[{“id”:550,”href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads\/549\/revisions\/550″}],”wp:attachment”:[{“href”:”https:\/\/cm.vastapps.dev\/wp-json\/wp\/v2\/media?parent=549″}],”wp:term”:[{“taxonomy”:”tcia_data_licenses”,”embeddable”:true,”href”:”https:\/\/cm.vastapps.dev\/wp-json\/licenses\/api?post=549″},{“taxonomy”:”tcia_download_requirement”,”embeddable”:true,”href”:”https:\/\/cm.vastapps.dev\/wp-json\/api\/requirements?post=549″}],”curies”:[{“name”:”wp”,”href”:”https:\/\/api.w.org\/{rel}”,”templated”:true}]}},{“id”:348,”date”:”2023-02-27T15:45:30″,”date_gmt”:”2023-02-27T15:45:30″,”guid”:{“rendered”:”https:\/\/cm.vastapps.dev\/?post_type=tcia_downloads&p=348″},”modified”:”2023-03-02T07:25:23″,”modified_gmt”:”2023-03-02T07:25:23″,”slug”:”tcga-brca-download”,”status”:”publish”,”type”:”tcia_downloads”,”link”:”https:\/\/cm.vastapps.dev\/tcia-downloads\/tcga-brca-download\/”,”title”:{“rendered”:”TCGA-BRCA Download”},”content”:{“rendered”:”<h3 id=\”TheCancerGenomeAtlasBreastInvasiveCarcinomaCollection(TCGABRCA)-AdditionalResourcesforthisDataset\”>Additional Resources for this Dataset<\/h3>\n<p>The NCI Cancer Research Data Commons (CRDC) provides access to additional data and a cloud-based data science infrastructure that connects data sets with analytics tools to allow users to share, integrate, analyze, and visualize cancer research data.<\/p>\n<ul>\n<li class=\”auto-cursor-target\”><a class=\”external-link\” href=\”https:\/\/portal.imaging.datacommons.cancer.gov\/explore\/filters\/?collection_id=tcga_brca\” rel=\”nofollow\”>Imaging Data Commons (IDC)<\/a>\u00a0(Imaging Data)<\/li>\n<li class=\”xmsonormal\”><a class=\”external-link\” href=\”https:\/\/portal.gdc.cancer.gov\/legacy-archive\/search\/f?filters=%7B%22op%22:%22and%22,%22content%22:%5B%7B%22op%22:%22in%22,%22content%22:%7B%22field%22:%22files.data_format%22,%22value%22:%5B%22SVS%22%5D%7D%7D,%7B%22op%22:%22in%22,%22content%22:%7B%22field%22:%22cases.project.program.name%22,%22value%22:%5B%22TCGA%22%5D%7D%7D,%7B%22op%22:%22in%22,%22content%22:%7B%22field%22:%22cases.project.project_id%22,%22value%22:%5B%22TCGA-BRCA%22%5D%7D%7D%5D%7D\” rel=\”nofollow\”>Genomic Data Commons Legacy Archive<\/a>\u00a0(Tissue Slide Images)<\/li>\n<li class=\”xmsonormal\”><a class=\”external-link\” href=\”https:\/\/portal.gdc.cancer.gov\/projects\/TCGA-BRCA\” rel=\”nofollow\”>Genomic Data Commons (GDC)<\/a>\u00a0(Genomic & Clinical Data)<\/li>\n<\/ul>\n<h3 id=\”TheCancerGenomeAtlasBreastInvasiveCarcinomaCollection(TCGABRCA)-ThirdPartyAnalysesofthisDataset\”>Third Party Analyses of this Dataset<\/h3>\n<p>TCIA encourages the community to\u00a0<a class=\”external-link\” href=\”http:\/\/www.cancerimagingarchive.net\/analysis-results\/\” rel=\”nofollow\”>publish your analyses of our datasets<\/a>. Below is a list of such third party analyses published using this Collection:<\/p>\n<ul>\n<li><a href=\”https:\/\/wiki.cancerimagingarchive.net\/pages\/viewpage.action?pageId=19039112\”>TCGA Breast Phenotype Research Group Data sets (TCGA-Breast-Radiogenomics)<\/a><\/li>\n<li><a href=\”https:\/\/wiki.cancerimagingarchive.net\/pages\/viewpage.action?pageId=33948919\”>Tumor-Infiltrating Lymphocytes Maps from TCGA H&E Whole Slide Pathology Images<\/a><\/li>\n<li><a href=\”https:\/\/wiki.cancerimagingarchive.net\/pages\/viewpage.action?pageId=52763018\”>SDTM datasets of clinical data and measurements for selected cancer collections to TCIA (DI-Cubed-Reports)<\/a><\/li>\n<li><a href=\”https:\/\/wiki.cancerimagingarchive.net\/pages\/viewpage.action?pageId=50135479\”>DICOM SR of clinical data and measurement for breast cancer collections to TCIA (DICOM-SR-Breast-Clinical)<\/a><\/li>\n<\/ul>\n<h3 id=\”TheCancerGenomeAtlasSarcomaCollection(TCGASARC)-GDCDataPortal-ClinicalandGenomicData\”>GDC Data Portal – Clinical and Genomic Data<\/h3>\n<p class=\”wiki-content\”>The\u00a0<a class=\”external-link\” href=\”https:\/\/portal.gdc.cancer.gov\/exploration?filters=%7B%22op%22%3A%22and%22%2C%22content%22%3A%5B%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22cases.project.program.name%22%2C%22value%22%3A%5B%22TCGA%22%5D%7D%7D%2C%7B%22op%22%3A%22in%22%2C%22content%22%3A%7B%22field%22%3A%22cases.project.project_id%22%2C%22value%22%3A%5B%22TCGA-SARC%22%5D%7D%7D%5D%7D\” rel=\”nofollow\”>GDC Data Portal<\/a>\u00a0has extensive clinical and genomic data, which can be matched to the patient identifiers on the images here in TCIA. Below is a snapshot of clinical data extracted on 1\/5\/2016.<\/p>\n<ul>\n<li class=\”wiki-content\”><a href=\”https:\/\/wiki.cancerimagingarchive.net\/download\/attachments\/19039714\/TCGA-SARC%20Clinical%20Data%201516.zip?version=1&modificationDate=1452106444955&api=v2\” data-linked-resource-id=\”22643035\” data-linked-resource-version=\”1\” data-linked-resource-default-alias=\”TCGA-SARC Clinical Data 1516.zip\” data-nice-type=\”Zip Archive\” data-linked-resource-content-type=\”application\/zip\” data-linked-resource-container-id=\”19039714\” data-linked-resource-container-version=\”40\”>TCGA-SARC Clinical Data.zip<\/a><\/li>\n<\/ul>\n<p class=\”wiki-content\”>Explanations of the clinical data can be found on the Biospecimen Core Resource Clinical Data Forms linked below:<\/p>\n<div class=\”wiki-content\”>\n<ul>\n<li><a class=\”external-link\” href=\”https:\/\/www.nationwidechildrens.org\/-\/media\/nch\/research\/documents\/tcga\/sarcoma-case-quality-control-form.ashx\” rel=\”nofollow\”>Sarcoma Case Quality Control Form<\/a><\/li>\n<li><a class=\”external-link\” href=\”https:\/\/www.nationwidechildrens.org\/-\/media\/nch\/research\/documents\/tcga\/sarcoma-enrollment-form.ashx\” rel=\”nofollow\”>Sarcoma Enrollment Form<\/a><\/li>\n<li><a class=\”external-link\” href=\”https:\/\/www.nationwidechildrens.org\/-\/media\/nch\/research\/documents\/tcga\/sarcoma-followup-form.ashx\” rel=\”nofollow\”>Sarcoma Follow-Up Form<\/a><\/li>\n<\/ul>\n<\/div>\n<h3 id=\”TheCancerGenomeAtlasSarcomaCollection(TCGASARC)-ANoteaboutTCIAandTCGASubjectIdentifiersandDates\”>A Note about TCIA and TCGA Subject Identifiers and Dates<\/h3>\n<p><strong>Subject Identifiers:<\/strong>\u00a0a subject with radiology images stored in TCIA is identified with a Patient ID that is identical to the Patient ID of the same subject with demographic, clinical, pathological, and\/or genomic data stored in TCGA. For each TCGA case, the baseline TCGA imaging studies found on TCIA are pre-surgical.<\/p>\n<p><strong>Dates:<\/strong>\u00a0TCIA and TCGA handle dates differently, and there are no immediate plans to reconcile:<\/p>\n<ul>\n<li><u>TCIA Dates:<\/u>\u00a0dates (be they birth dates, imaging study dates, etc.) in the Digital Imaging and Communications in Medicine (DICOM) headers of TCIA radiology images have been offset by a random number of days. The offset is a number of days between 3 and 10 years prior to the real date that is consistent for each TCIA image-submitting site and collection, but that varies among sites and among collections from the same site. Thus, the number of days between a subject\u2019s longitudinal imaging studies are accurately preserved when more than one study has been archived while still meeting HIPAA requirements.<\/li>\n<li><u>TCGA Dates:<\/u>\u00a0the patient demographic and clinical event dates are all the number of days from the index date, which is the actual date of pathologic diagnosis. So all the dates in the data are relative negative or positive integers, except for the \u201cdays_to_pathologic_diagnosis\u201d value, which is 0 \u2013 the index date. The years of birth and diagnosis are maintained in the distributed clinical data file. The NCI retains a copy of the data with complete dates, but those data are not made available.With regard to other TCGA dates, if a date comes from a HIPAA \u201ccovered entity\u2019s\u201d medical record, it is turned into the relative day count from the index date. Dates like the date TCGA received the specimen or when the TCGA case report form was filled out are not such covered dates, and they will appear as\u00a0real dates (month, day, and year).<\/li>\n<\/ul>\n”,”protected”:false},”menu_order”:0,”template”:””,”api”:[],”requirements”:[],”data_type”:[“Radiology Images”],”file_type”:[“DICOM”],”download_url”:”https:\/\/wiki.cancerimagingarchive.net\/download\/attachments\/3539225\/TCIA_TCGA-BRCA_09-16-2015.tcia?version=1&modificationDate=1534787408445&api=v2″,”download_size”:”88″,”download_size_unit”:”gb”,”search_url”:”https:\/\/www.cancerimagingarchive.net\/nbia-search\/?CollectionCriteria=TCGA-BRCA”,”cancer_type”:[“Breast Cancer”],”cancer_location”:[“Breast”],”species”:[“Human”],”subjects”:”139″,”modalities”:[“MR”,”MG”,”Pathology”],”supporting_data”:[“Clinical”,”Genomics”,”Image Analyses”],”download_access”:”Public”,”collection_status”:”Complete”,”date_updated”:”2020-05-29″,”tcia_data_license”:[“CC 3.0″],”download_requirements”:”Requires NBIA Data Retriever”,”_links”:{“self”:[{“href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads\/348″}],”collection”:[{“href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads”}],”about”:[{“href”:”https:\/\/cm.vastapps.dev\/wp-json\/wp\/v2\/types\/tcia_downloads”}],”version-history”:[{“count”:3,”href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads\/348\/revisions”}],”predecessor-version”:[{“id”:511,”href”:”https:\/\/cm.vastapps.dev\/api\/v1\/downloads\/348\/revisions\/511″}],”wp:attachment”:[{“href”:”https:\/\/cm.vastapps.dev\/wp-json\/wp\/v2\/media?parent=348″}],”wp:term”:[{“taxonomy”:”tcia_data_licenses”,”embeddable”:true,”href”:”https:\/\/cm.vastapps.dev\/wp-json\/licenses\/api?post=348″},{“taxonomy”:”tcia_download_requirement”,”embeddable”:true,”href”:”https:\/\/cm.vastapps.dev\/wp-json\/api\/requirements?post=348″}],”curies”:[{“name”:”wp”,”href”:”https:\/\/api.w.org\/{rel}”,”templated”:true}]}}]