DICOMweb Guide for IDC

Reviewed 2026-09-30 against IDC endpoint/policy documentation and Google Healthcare conformance. Public QIDO and metadata reads were probed; authenticated Google-store access and pixel/frame retrieval were not executed.

When to Use DICOMweb

Use DICOMweb when you need:

• Integration with PACS systems or DICOMweb-compatible tools
• Streaming metadata without downloading full files
• Building custom viewers or web applications
• Using existing DICOMweb client libraries (OHIF, dicomweb-client, etc.)

For most use cases, idc-index is simpler and recommended. Use DICOMweb when you specifically need the DICOMweb protocol.

Endpoints

Public Proxy (No Authentication)

https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb

• 100% data coverage - Contains all IDC data from all storage buckets
• Points to the latest IDC version automatically
• Updates immediately on new IDC releases
• Per-IP and global daily egress quotas; use when bucket downloads cannot meet the task
• No authentication required
• Read-only access
• Note: "viewer-only-no-downloads" in URL is legacy naming with no functional meaning

Google Healthcare API (Requires Authentication)

https://healthcare.googleapis.com/v1/projects/nci-idc-data/locations/us-central1/datasets/idc/dicomStores/idc-store-v{VERSION}/dicomWeb

The pattern is historical, not proof that a store exists for the latest IDC release. IDC currently documents idc-store-v23, while Google [documents idc-store and an access-request form](https://docs.cloud.google.com/healthcare-api/docs/resources/public-datasets/idc). Confirm the provisioned store URL and access with those pages/the IDC health monitor; do not synthesize idc-store-v24 solely from this client output:

from idc_index import IDCClient
client = IDCClient()
print(client.get_idc_version())  # e.g., "v24" for current version

• Replicates idc-open-data; excludes the other two buckets, so check your selected series
• IDC targets synchronization within 1-2 weeks of a release; this is not guaranteed
• Requires authentication and provides higher quotas
• Better performance (no proxy routing)
• Each release gets a new versioned store

See Content Coverage Differences and Authentication sections below.

Content Coverage Differences

Important: The two DICOMweb endpoints have different data coverage. The IDC public proxy contains MORE data than the authenticated Google Healthcare endpoint.

Coverage Summary

What's Missing from Google Healthcare?

The Google Healthcare DICOM store **only replicates data from the idc-open-data S3 bucket**. It does not include data from two additional buckets:

• idc-open-data-cr
• idc-open-data-two

The often-quoted 95.89% coverage is an IDC v21 series-count snapshot. Recalculate the share for the selected release; it is not a current guarantee or a fraction by file size.

See cloud_storage_guide.md for details on bucket organization, file structure, and direct access methods.

Update Timing

• IDC Public Proxy: Updates immediately when new IDC versions are released
• Google Healthcare: Independently maintained; synchronization within 1-2 weeks is a goal.

Verify the actual store release and query representative selected UIDs before a large job.

Warning from IDC documentation: "Google-hosted DICOM store may not contain the latest version of IDC data!" - Check during the weeks following a new release.

Choosing the Right Endpoint

Use IDC Public Proxy when:

• You need complete data coverage (100%)
• You need the absolute latest data immediately after a new version release
• You don't want to set up GCP authentication
• Your usage fits within per-IP quotas (can request increases via support@canceridc.dev)
• You're accessing slide microscopy images frame-by-frame

Use Google Healthcare API when:

• Your selected series exist in the particular Google store
• You need higher quotas for heavy usage
• You want better performance (direct access, no proxy routing)

Checking Your Data Availability

Before choosing an endpoint, verify whether your data might be in the missing buckets:

from idc_index import IDCClient

client = IDCClient()

# Check which buckets contain your collection's data
results = client.sql_query("""
    SELECT aws_bucket, COUNT(*) as series_count
    FROM index
    WHERE collection_id = 'your_collection_id'
    GROUP BY aws_bucket
""")

print(results)

# Look for bucket values 'idc-open-data-cr' or 'idc-open-data-two'
# If present, that data won't be available in Google Healthcare endpoint

Implementation Details

IDC DICOMweb is provided through Google Cloud Healthcare API DICOM stores. The implementation follows DICOM PS3.18 Web Services with specific characteristics documented in the Google Healthcare DICOM conformance statement.

Supported Operations

Not supported: URI Service, Worklist Service, Non-Patient Instance Service, Capabilities Transactions

Searchable DICOM Tags (QIDO-RS)

The implementation supports a limited set of searchable tags:

Important: Only exact matching is supported, except for:

• StudyDate: supports range queries
• PatientName: supports fuzzy matching

Query Limitations

• Maximum results: 5,000 for studies/series searches; 50,000 for instances
• Maximum offset: 1,000,000
• Sequence tags (VR SQ) larger than approximately 1 MiB are omitted without a BulkDataURI; other bulk data can have a BulkDataURI. Retrieve the full instance for omitted sequences.
• QIDO defaults to 100 studies/series or 1,000 instances. Use limit and offset for pages, including a final empty-page check; there is no reliable warning header marking exhaustion. WADO series metadata does not use these QIDO pagination parameters.

Code Examples

All examples use the public proxy endpoint. For authenticated access to Google Healthcare, see the authentication section.

Finding UIDs with idc-index

Use idc-index to discover data, then use DICOMweb for metadata access:

from idc_index import IDCClient

client = IDCClient()

# Find studies of interest
results = client.sql_query("""
    SELECT StudyInstanceUID, SeriesInstanceUID, PatientID, Modality
    FROM index
    WHERE collection_id = 'tcga_luad' AND Modality = 'CT'
    LIMIT 5
""")

# Use these UIDs with DICOMweb
study_uid = results.iloc[0]['StudyInstanceUID']
series_uid = results.iloc[0]['SeriesInstanceUID']
print(f"Study: {study_uid}")
print(f"Series: {series_uid}")

QIDO-RS: Search by UID

import requests

base_url = "https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb"

# Search for a specific study
study_uid = "1.3.6.1.4.1.14519.5.2.1.6450.9002.307623500513044641407722230440"
response = requests.get(
    f"{base_url}/studies",
    params={"StudyInstanceUID": study_uid},
    headers={"Accept": "application/dicom+json"},
    timeout=60,
)
response.raise_for_status()

if response.status_code == 200:
    studies = response.json()
    print(f"Found {len(studies)} study")

QIDO-RS: List Series in a Study

import requests

base_url = "https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb"
study_uid = "1.3.6.1.4.1.14519.5.2.1.6450.9002.307623500513044641407722230440"

response = requests.get(
    f"{base_url}/studies/{study_uid}/series",
    headers={"Accept": "application/dicom+json"},
    timeout=60,
)
response.raise_for_status()

if response.status_code == 200:
    series_list = response.json()
    for series in series_list:
        # DICOM tags are returned as hex codes
        series_uid = series.get("0020000E", {}).get("Value", [None])[0]
        modality = series.get("00080060", {}).get("Value", [None])[0]
        description = series.get("0008103E", {}).get("Value", [""])[0]
        print(f"{modality}: {description}")

QIDO-RS: List Instances in a Series

import requests

base_url = "https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb"
study_uid = "1.3.6.1.4.1.14519.5.2.1.6450.9002.307623500513044641407722230440"
series_uid = "1.3.6.1.4.1.14519.5.2.1.6450.9002.217441095430480124587725641302"

response = requests.get(
    f"{base_url}/studies/{study_uid}/series/{series_uid}/instances",
    params={"limit": 10},
    headers={"Accept": "application/dicom+json"},
    timeout=60,
)
response.raise_for_status()

if response.status_code == 200:
    instances = response.json()
    print(f"Found {len(instances)} instances")
    for inst in instances[:3]:
        sop_uid = inst.get("00080018", {}).get("Value", [None])[0]
        print(f"  SOPInstanceUID: {sop_uid}")

WADO-RS: Retrieve Series Metadata

import requests

base_url = "https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb"
study_uid = "1.3.6.1.4.1.14519.5.2.1.6450.9002.307623500513044641407722230440"
series_uid = "1.3.6.1.4.1.14519.5.2.1.6450.9002.217441095430480124587725641302"

response = requests.get(
    f"{base_url}/studies/{study_uid}/series/{series_uid}/metadata",
    headers={"Accept": "application/dicom+json"},
    timeout=60,
)
response.raise_for_status()

if response.status_code == 200:
    instances = response.json()
    print(f"Retrieved metadata for {len(instances)} instances")

    # Extract image dimensions from first instance
    if instances:
        inst = instances[0]
        rows = inst.get("00280010", {}).get("Value", [None])[0]
        cols = inst.get("00280011", {}).get("Value", [None])[0]
        print(f"Image dimensions: {rows} x {cols}")

Combined Workflow: idc-index Discovery + DICOMweb Metadata

from idc_index import IDCClient
import requests

# Use idc-index for efficient discovery
idc = IDCClient()
results = idc.sql_query("""
    SELECT StudyInstanceUID, SeriesInstanceUID, Modality, SeriesDescription
    FROM index
    WHERE collection_id = 'nlst' AND Modality = 'CT'
    LIMIT 1
""")

study_uid = results.iloc[0]['StudyInstanceUID']
series_uid = results.iloc[0]['SeriesInstanceUID']
print(f"Found: {results.iloc[0]['SeriesDescription']}")

# Use DICOMweb to stream metadata without downloading files
base_url = "https://proxy.imaging.datacommons.cancer.gov/current/viewer-only-no-downloads-see-tinyurl-dot-com-slash-3j3d9jyp/dicomWeb"

response = requests.get(
    f"{base_url}/studies/{study_uid}/series/{series_uid}/metadata",
    headers={"Accept": "application/dicom+json"},
    timeout=60,
)
response.raise_for_status()

if response.status_code == 200:
    metadata = response.json()
    print(f"Retrieved metadata for {len(metadata)} instances without downloading files")

Common DICOM Tags Reference

DICOMweb returns tags as hexadecimal codes. Common tags:

Authentication for Google Healthcare API

To use the Google Healthcare endpoint with higher quotas:

import os
from google.auth import default
from google.auth.transport.requests import AuthorizedSession

# Get ADC; AuthorizedSession refreshes expiring tokens automatically.
credentials, project = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
session = AuthorizedSession(credentials)

# Set IDC_DICOMWEB_URL to the verified provisioned Google store URL (ending /dicomWeb).
base_url = os.environ["IDC_DICOMWEB_URL"].rstrip("/")

response = session.get(
    f"{base_url}/studies",
    params={"limit": 5},
    headers={
        "Accept": "application/dicom+json"
    },
    timeout=60,
)
response.raise_for_status()

Prerequisites:

1. Google Cloud SDK installed (gcloud)
2. Authenticated: gcloud auth application-default login
3. google-auth and requests installed; account authorized for the selected Google store
4. IDC_DICOMWEB_URL set to the verified endpoint. Google documents an access-request form; follow it if ADC alone is insufficient. No authenticated access was verified in this refresh.

Troubleshooting

Issue: 400 Bad Request on search queries

• Cause: Using unsupported search parameters. The implementation only supports specific DICOM tags for filtering.
• Solution: Use UID-based queries (StudyInstanceUID, SeriesInstanceUID). For filtering by Modality or other attributes, use idc-index to discover UIDs first, then query DICOMweb with specific UIDs.

Issue: 403 Forbidden on Google Healthcare endpoint

• Cause: Missing authentication or insufficient permissions
• Solution: Run gcloud auth application-default login and ensure your account has access

Issue: 429 Too Many Requests

• Cause: Rate limit exceeded
• Solution: Honor Retry-After, back off, and use public buckets for complete files. A daily proxy egress cap is not fixed by repeated retries; do not rotate IPs to bypass it.

Issue: 204 No Content for valid UIDs

• Cause: UID may be from an older IDC version not in current data, or data is in buckets not replicated by Google Healthcare
• Solution:
• Verify UID exists using idc-index query first
• Check if data is in idc-open-data-cr or idc-open-data-two buckets (not available in Google Healthcare endpoint)
• Switch to IDC public proxy for 100% coverage
• Verify store release/access; synchronization timing is not guaranteed

Issue: Large metadata responses slow to parse

• Cause: Series with many instances returns large JSON
• Solution: Use limit/offset on QIDO instance searches, or retrieve metadata for a specific instance by appending /instances/{SOPInstanceUID}/metadata; do not assume limit paginates WADO series metadata

Issue: Response missing expected attributes

• Cause: DICOM sequences larger than ~1 MB are excluded from metadata responses
• Solution: Retrieve the full DICOM instance using WADO-RS instance retrieval if you need all attributes

Resources

IDC Documentation:

• IDC DICOM Stores - Data coverage and bucket details
• IDC DICOMweb Access - Endpoint usage and differences
• IDC Proxy Policy - Quota policies and usage restrictions
• IDC User Guide - Complete documentation

DICOMweb Standards and Tools:

• Google Healthcare DICOM Conformance Statement
• DICOMweb Standard
• dicomweb-client Python library

Related Guides:

• cloud_storage_guide.md - Direct bucket access, file organization, CRDC UUIDs, and versioning
• bigquery_guide.md - Advanced metadata queries with full DICOM attributes