Endpoint Details
This page provides details on each of the IDC API endpoints.
get
Get links to the IDC API Swagger UI and IDC documentation
Responses
200
API Description and link to SwaggerUI interface.
500
Server error message
get
GET /about HTTP/1.1
Host:
Accept: */*
{
"message": "text",
"documentation": "text",
"code": 1
}get
Returns a list of IDC data versions and activation dates
Responses
200
A list of IDC data versions and metadata
500
Server error message
get
GET /versions HTTP/1.1
Host:
Accept: */*
{
"idc_data_versions": [
{
"idc_data_version": "text",
"date_active": "text",
"active": "text"
}
],
"code": 1
}get
Returns a list of collections, and associated metadata, in the current IDC data version.
Responses
200
A list of collections
500
Server error message
get
GET /collections HTTP/1.1
Host:
Accept: */*
{
"collections": [
{
"collection_id": "text",
"cancer_type": "text",
"date_updated": "text",
"description": "text",
"source_doi": "text",
"source_url": "text",
"image_types": "text",
"location": "text",
"species": "text",
"subject_count": 1,
"supporting_data": "text"
}
],
"code": 1
}get
Returns a list of the analysis results, and associated metadata, in the current IDC data version
Responses
200
A list of analysis results
500
Server error message
get
GET /analysis_results HTTP/1.1
Host:
Accept: */*
{
"analysisResults": [
{
"analysis_result_id": "text",
"analysisArtifacts": "text",
"cancer_type": "text",
"collections": "text",
"date_updated": "text",
"description": "text",
"doi": "text",
"location": "text",
"subjects": 1,
"title": "text"
}
],
"code": 1
}get
Returns a list of 'filters', organized by data source (BQ table), for the current IDC data version. An IDC cohort is defined by a 'filterset', a set of (filter,[values]) pairs, and the IDC version against which the filterset is applied. The returned data is grouped by source (the BQ table that contains the corresponding filter values). For each filter, its data type and units, when available, are reported.
Responses
200
A list of filters
500
Server error message
get
GET /filters HTTP/1.1
Host:
Accept: */*
{
"idc_data_version": "text",
"data_sources": [
{
"data_source": "text",
"filters": [
{
"name": "text",
"data_type": "CONTINUOUS_NUMERIC",
"units": "text"
}
]
}
],
"code": 1
}get
Return a list of the values accepted for a 'categorical filter'. A categorical filter is a filter having a data type of 'Categorical String' or 'Categorical Number'.
Path parameters
filterstringRequired
Categorical filter whose values are to be returned
Responses
200
A list of accepted values
500
Server error message
get
GET /filters/values/{filter} HTTP/1.1
Host:
Accept: */*
{
"values": [
"text"
]
}get
Return a list of queryable manifest fields.
Path parameters
versionstringRequired
IDC data version whose data is to be returned. If the version is 'current', the fields of the current IDC version are returned.
Responses
200
A list of fields
500
Server error message
get
GET /fields/{version} HTTP/1.1
Host:
Accept: */*
{
"idc_data_version": "text",
"data_sources": [
{
"data_source": "text",
"fields": [
"text"
]
}
],
"code": 1
}post
Returns a manifest of a 'previewed cohort' as defined by a specified filterset. The filterset is always applied to the current IDC version. The metadata to be returned in the manifest is configurable. A previewed cohort is not saved in the user's IDC account.
Body
countsstringOptionalDefault:
If True, return counts of DICOM objects
Falsegroup_sizestringOptionalDefault:
If True, return size in bytes of instances in group
FalsesqlstringOptionalDefault:
If True, return the BQ SQL for this query.
Falsepage_sizeintegerOptionalDefault:
Maximum number of rows to return
1000Responses
200
Preview cohort spec and manifest
202
Timeout waiting for BQ job to complete
500
Server error message
post
POST /cohorts/manifest/preview HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 345
{
"cohort_def": {
"name": "mycohort",
"description": "Example description",
"filters": {
"collection_id": [
"TCGA_luad",
"tcga_kirc"
],
"Modality": [
"CT",
"MR"
],
"Race": [
"WHITE"
],
"age_at_diagnosis_btw": [
65,
75
]
}
},
"fields": [
"Age_At_Diagnosis",
"aws_bucket",
"crdc_series_uuid",
"Modality",
"SliceThickness"
],
"counts": true,
"group_size": true,
"sql": true,
"page_size": 1000
}{
"cohort": {
"name": "text",
"description": "text",
"filterSet": {
"idc_data_version": "text",
"filters": {
"project_short_name": [
"text"
],
"sample_type": [
"text"
],
"age_at_diagnosis_btw": [
1
],
"age_at_diagnosis_ebtw": [
1
],
"age_at_diagnosis_btwe": [
1
],
"age_at_diagnosis_ebtwe": [
1
],
"age_at_diagnosis_gte": [
1
],
"age_at_diagnosis_lte": [
1
],
"age_at_diagnosis_gt": [
1
],
"age_at_diagnosis_lt": [
1
],
"age_at_diagnosis_eq": [
1
],
"bmi_btw": [
1
],
"bmi_ebtw": [
1
],
"bmi_btwe": [
1
],
"bmi_ebtwe": [
1
],
"bmi_gte": [
1
],
"bmi_lte": [
1
],
"bmi_gt": [
1
],
"bmi_lt": [
1
],
"bmi_eq": [
1
],
"country": [
"text"
],
"disease_code": [
"text"
],
"ethnicity": [
"text"
],
"gender": [
"text"
],
"histological_type": [
"text"
],
"pathologic_stage": [
"text"
],
"project_name": [
"text"
],
"race": [
"text"
],
"tumor_tissue_site": [
"text"
],
"vital_status": [
"text"
],
"analysis_results_id": [
"text"
],
"AnatomicRegionSequence": [
"text"
],
"Apparent_Diffusion_Coefficient_btw": [
1
],
"Apparent_Diffusion_Coefficient_ebtw": [
1
],
"Apparent_Diffusion_Coefficient_btwe": [
1
],
"Apparent_Diffusion_Coefficient_ebtwe": [
1
],
"Apparent_Diffusion_Coefficient_gte": [
1
],
"Apparent_Diffusion_Coefficient_lte": [
1
],
"Apparent_Diffusion_Coefficient_gt": [
1
],
"Apparent_Diffusion_Coefficient_lt": [
1
],
"Apparent_Diffusion_Coefficient_eq": [
1
],
"BodyPartExamined": [
"text"
],
"Calcification": [
"text"
],
"CancerType": [
"text"
],
"collection_id": [
"text"
],
"Diameter_btw": [
1
],
"Diameter_ebtw": [
1
],
"Diameter_btwe": [
1
],
"Diameter_ebtwe": [
1
],
"Diameter_gte": [
1
],
"Diameter_lte": [
1
],
"Diameter_gt": [
1
],
"Diameter_lt": [
1
],
"Diameter_eq": [
1
],
"illuminationType": [
"text"
],
"Internal_structure": [
"text"
],
"license_short_name": [
"text"
],
"Lobular_Pattern": [
"text"
],
"Malignancy": [
"text"
],
"Manufacturer": [
"text"
],
"ManufacturerModelName": [
"text"
],
"Margin": [
"text"
],
"max_TotalPixelMatrixColumns_btw": [
1
],
"max_TotalPixelMatrixColumns_ebtw": [
1
],
"max_TotalPixelMatrixColumns_btwe": [
1
],
"max_TotalPixelMatrixColumns_ebtwe": [
1
],
"max_TotalPixelMatrixColumns_gte": [
1
],
"max_TotalPixelMatrixColumns_lte": [
1
],
"max_TotalPixelMatrixColumns_gt": [
1
],
"max_TotalPixelMatrixColumns_lt": [
1
],
"max_TotalPixelMatrixColumns_eq": [
1
],
"max_TotalPixelMatrixRows_btw": [
1
],
"max_TotalPixelMatrixRows_ebtw": [
1
],
"max_TotalPixelMatrixRows_btwe": [
1
],
"max_TotalPixelMatrixRows_ebtwe": [
1
],
"max_TotalPixelMatrixRows_gte": [
1
],
"max_TotalPixelMatrixRows_lte": [
1
],
"max_TotalPixelMatrixRows_gt": [
1
],
"max_TotalPixelMatrixRows_lt": [
1
],
"max_TotalPixelMatrixRows_eq": [
1
],
"min_PixelSpacing_btw": [
1
],
"min_PixelSpacing_ebtw": [
1
],
"min_PixelSpacing_btwe": [
1
],
"min_PixelSpacing_ebtwe": [
1
],
"min_PixelSpacing_gte": [
1
],
"min_PixelSpacing_lte": [
1
],
"min_PixelSpacing_gt": [
1
],
"min_PixelSpacing_lt": [
1
],
"min_PixelSpacing_eq": [
1
],
"Modality": [
"text"
],
"ObjectiveLensPower": [
1
],
"PatientID": [
"text"
],
"primaryAnatomicStructure": [
"text"
],
"SamplesPerPixel": [
"text"
],
"SegmentAlgorithmName": [
"text"
],
"SegmentAlgorithmType": [
"text"
],
"SegmentedPropertyCategoryCodeSequence": [
"text"
],
"SegmentedPropertyTypeCodeSequence": [
"text"
],
"SeriesDescription": [
"text"
],
"SeriesInstanceUID": [
"text"
],
"SeriesNumber": [
"text"
],
"SliceThickness_btw": [
1
],
"SliceThickness_ebtw": [
1
],
"SliceThickness_btwe": [
1
],
"SliceThickness_ebtwe": [
1
],
"SliceThickness_gte": [
1
],
"SliceThickness_lte": [
1
],
"SliceThickness_gt": [
1
],
"SliceThickness_lt": [
1
],
"SliceThickness_eq": [
1
],
"SOPClassUID": [
"text"
],
"SOPInstanceUID": [
"text"
],
"Sphericity": [
"text"
],
"Sphericity_quant_btw": [
1
],
"Sphericity_quant_ebtw": [
1
],
"Sphericity_quant_btwe": [
1
],
"Sphericity_quant_ebtwe": [
1
],
"Sphericity_quant_gte": [
1
],
"Sphericity_quant_lte": [
1
],
"Sphericity_quant_gt": [
1
],
"Sphericity_quant_lt": [
1
],
"Sphericity_quant_eq": [
1
],
"Spiculation": [
"text"
],
"StudyDate": [
"text"
],
"StudyDescription": [
"text"
],
"StudyInstanceUID": [
"text"
],
"Subtlety_score": [
"text"
],
"Surface_area_of_mesh_btw": [
1
],
"Surface_area_of_mesh_ebtw": [
1
],
"Surface_area_of_mesh_btwe": [
1
],
"Surface_area_of_mesh_ebtwe": [
1
],
"Surface_area_of_mesh_gte": [
1
],
"Surface_area_of_mesh_lte": [
1
],
"Surface_area_of_mesh_gt": [
1
],
"Surface_area_of_mesh_lt": [
1
],
"Surface_area_of_mesh_eq": [
1
],
"tcia_species": [
"text"
],
"tcia_tumorLocation": [
"text"
],
"Texture": [
"text"
],
"Volume_btw": [
1
],
"Volume_ebtw": [
1
],
"Volume_btwe": [
1
],
"Volume_ebtwe": [
1
],
"Volume_gte": [
1
],
"Volume_lte": [
1
],
"Volume_gt": [
1
],
"Volume_lt": [
1
],
"Volume_eq": [
1
],
"Volume_of_Mesh_btw": [
1
],
"Volume_of_Mesh_ebtw": [
1
],
"Volume_of_Mesh_btwe": [
1
],
"Volume_of_Mesh_ebtwe": [
1
],
"Volume_of_Mesh_gte": [
1
],
"Volume_of_Mesh_lte": [
1
],
"Volume_of_Mesh_gt": [
1
],
"Volume_of_Mesh_lt": [
1
],
"Volume_of_Mesh_eq": [
1
]
}
},
"sql": "text"
},
"manifest": {
"manifest_data": [
{
"age_at_diagnosis": 1,
"analysis_results_id": "text",
"AnatomicRegionSequence": "text",
"Apparent_Diffusion_Coefficient": 1,
"aws_bucket": "text",
"aws_url": "text",
"bmi": 1,
"BodyPartExamined": "text",
"Calcification": "text",
"CancerType": "text",
"collection_id": "text",
"country": "text",
"crdc_instance_uuid": "text",
"crdc_series_uuid": "text",
"crdc_study_uuid": "text",
"Diameter": 1,
"disease_code": "text",
"ethnicity": "text",
"FrameOfReferenceUID": "text",
"gcs_bucket": "text",
"gcs_url": "text",
"gender": "text",
"histological_type": "text",
"illuminationType": "text",
"instance_size": 1,
"Internal_structure": "text",
"license_short_name": "text",
"Lobular_Pattern": "text",
"Malignancy": "text",
"Manufacturer": "text",
"ManufacturerModelName": "text",
"Margin": "text",
"max_TotalPixelMatrixColumns": 1,
"max_TotalPixelMatrixRows": 1,
"min_PixelSpacing": 1,
"Modality": "text",
"ObjectiveLensPower": 1,
"pathologic_stage": "text",
"PatientID": "text",
"primaryAnatomicStructure": "text",
"Program": "text",
"project_name": "text",
"project_short_name": "text",
"race": "text",
"sample_type": "text",
"SamplesPerPixel": 1,
"SegmentAlgorithmType": "text",
"SegmentedPropertyCategoryCodeSequence": "text",
"SegmentedPropertyTypeCodeSequence": "text",
"SegmentNumber": 1,
"SeriesDescription": "text",
"SeriesInstanceUID": "text",
"SeriesNumber": "text",
"SliceThickness": 1,
"SOPClassUID": "text",
"SOPInstanceUID": "text",
"source_DOI": "text",
"Sphericity": "text",
"Sphericity_quant": 1,
"Spiculation": "text",
"StudyDate": "text",
"StudyDescription": "text",
"StudyInstanceUID": "text",
"Subtlety_score": "text",
"Surface_area_of_mesh": 1,
"tcia_species": "text",
"tcia_tumorLocation": "text",
"Texture": "text",
"tumor_tissue_site": "text",
"vital_status": "text",
"Volume": 1,
"Volume_of_Mesh": 1,
"instance_count": 1,
"series_count": 1,
"study_count": 1,
"patient_count": 1,
"collection_count": 1,
"group_size": 1
}
],
"totalFound": 1,
"rowsReturned": 1
},
"next_page": "text",
"code": 1
}get
Returns the next page of a /cohorts/manifest/preview request, when additional data is available.
Query parameters
next_pagestringRequired
The next_page token returned by a previous access of the /cohorts/manifest/preview endpoint. The token identifies the next page to be retrieved
page_sizeintegerOptional
The maximum number of rows to be returned. If the manifest contains additional rows, another 'next_page' token is returned.
Responses
200
Preview manifest page
202
Timeout waiting for BQ job to complete
500
Server error message
get
GET /cohorts/manifest/preview/nextPage?next_page=text HTTP/1.1
Host:
Accept: */*
{
"manifest": {
"manifest_data": [
{
"age_at_diagnosis": 1,
"analysis_results_id": "text",
"AnatomicRegionSequence": "text",
"Apparent_Diffusion_Coefficient": 1,
"aws_bucket": "text",
"aws_url": "text",
"bmi": 1,
"BodyPartExamined": "text",
"Calcification": "text",
"CancerType": "text",
"collection_id": "text",
"country": "text",
"crdc_instance_uuid": "text",
"crdc_series_uuid": "text",
"crdc_study_uuid": "text",
"Diameter": 1,
"disease_code": "text",
"ethnicity": "text",
"FrameOfReferenceUID": "text",
"gcs_bucket": "text",
"gcs_url": "text",
"gender": "text",
"histological_type": "text",
"illuminationType": "text",
"instance_size": 1,
"Internal_structure": "text",
"license_short_name": "text",
"Lobular_Pattern": "text",
"Malignancy": "text",
"Manufacturer": "text",
"ManufacturerModelName": "text",
"Margin": "text",
"max_TotalPixelMatrixColumns": 1,
"max_TotalPixelMatrixRows": 1,
"min_PixelSpacing": 1,
"Modality": "text",
"ObjectiveLensPower": 1,
"pathologic_stage": "text",
"PatientID": "text",
"primaryAnatomicStructure": "text",
"Program": "text",
"project_name": "text",
"project_short_name": "text",
"race": "text",
"sample_type": "text",
"SamplesPerPixel": 1,
"SegmentAlgorithmType": "text",
"SegmentedPropertyCategoryCodeSequence": "text",
"SegmentedPropertyTypeCodeSequence": "text",
"SegmentNumber": 1,
"SeriesDescription": "text",
"SeriesInstanceUID": "text",
"SeriesNumber": "text",
"SliceThickness": 1,
"SOPClassUID": "text",
"SOPInstanceUID": "text",
"source_DOI": "text",
"Sphericity": "text",
"Sphericity_quant": 1,
"Spiculation": "text",
"StudyDate": "text",
"StudyDescription": "text",
"StudyInstanceUID": "text",
"Subtlety_score": "text",
"Surface_area_of_mesh": 1,
"tcia_species": "text",
"tcia_tumorLocation": "text",
"Texture": "text",
"tumor_tissue_site": "text",
"vital_status": "text",
"Volume": 1,
"Volume_of_Mesh": 1,
"instance_count": 1,
"series_count": 1,
"study_count": 1,
"patient_count": 1,
"collection_count": 1,
"group_size": 1
}
],
"totalFound": 1,
"rowsReturned": 1
},
"next_page": "text",
"code": 1
}Last updated
Was this helpful?