CMS Medicare

CMS Provider Data API

Hospital quality ratings, nursing home data, and Medicare coverage. No authentication required.

Data Model

• Dataset — A published dataset (e.g. Hospital General Information, Nursing Home Compare).
• Distribution — Download format for a dataset (CSV, JSON, API endpoint).
• Theme — Category grouping (Hospitals, Nursing Homes, Physicians, Home Health).

Key Datasets

• Hospital General Information — Star ratings, ownership, emergency services, location.
• HCAHPS — Patient satisfaction survey results by hospital.
• Timely and Effective Care — Quality measures (heart attack, pneumonia, surgical care).
• Complications and Deaths — Readmission and mortality rates.
• Nursing Home Compare — Quality ratings, staffing, health inspections for nursing homes.
• Physician Compare — Individual physician data, specialties, group practices.

Catalog Search

• Catalog search (no dataset_id) runs DKAN full-text search across each dataset's title, description, and CMS-curated keyword tags. Multi-word natural-language phrases work in a single call.
• Pass the full intent ("hospital readmissions mortality", "device infections", "nursing home staffing", "patient satisfaction HCAHPS") in ONE call. Do not fan out the same intent into multiple single-word calls — that wastes upstream quota and can saturate CMS at peak load.
• If a phrase returns zero results, drop the least-specific word and retry serially. Do not retry in parallel.
• Use theme to scope by CMS category — Hospitals, Nursing homes including rehab services, Doctors and clinicians, Home health services, Hospice care, Dialysis facilities, Inpatient rehabilitation facilities, Long-term care hospitals, Supplier directory, Physician office visit costs.
• Use page / page_size (max 100) for paging; total_matching is the full result count.

Dataset Detail and Data

• Dataset detail with a dataset_id (e.g. xubh-q36u) returns the full dataset record including its distribution array.
• Pull a distribution.identifier (UUID-shaped) out of that array and use it to query the underlying rows via the datastore endpoint.

Filtering Data Rows

• Datastore queries run DKAN datastore queries. They support structured filters, sort_by/sort_order, limit, and offset. It does NOT support full-text keyword search.
• Filter by exact match: filters={"state": "MA", "measure_id": "PSI_13"}.
• Filter with operators: filters={"score": {"operator": ">=", "value": 5}}, filters={"measure_name": {"operator": "like", "value": "%sepsis%"}}, filters={"state": {"operator": "in", "value": ["MA","NH","CT"]}}.
• Sort: sort_by="score", sort_order="desc".
• Hospital quality rows typically have columns: facility_id, facility_name, address, citytown, state, zip_code, measure_id, measure_name, score, denominator, lower_estimate, higher_estimate, start_date, end_date. Inspect one row with limit=1 if unsure.
• Score columns are stored as strings. "Not Available" appears for masked rows; filter it out before ranking with {"score": {"operator": "<>", "value": "Not Available"}}.
• Common measure IDs: PSI_13 (postoperative sepsis), PSI_90 (composite safety), MORT_30_AMI (heart-attack mortality), MORT_30_HF (heart-failure mortality), READM_30_HOSP_WIDE (hospital-wide readmission), COMP_HIP_KNEE (hip/knee complications).
• DO NOT paginate through tens of thousands of rows to find a state or a measure — that's a sign you should be using filters instead.

Key Datasets (common starting points)

• Hospital General Information — Star ratings, ownership, ER services.
• HCAHPS Hospital — Patient satisfaction survey results.
• Timely and Effective Care - Hospital — Process quality measures.
• Complications and Deaths - Hospital — Readmission, mortality, PSI.
• Healthcare Associated Infections - Hospital — CDC/NHSN infection data.
• Hospital Readmissions Reduction Program — HRRP payment adjustments.
• Nursing Home Compare — Quality ratings, staffing, inspections.
• Physician Compare — Individual clinician data and group practices.

Gotchas

• Catalog metadata lives in DKAN; actual data downloads use distribution URLs.
• Star ratings range from 1-5 (5 = best); some hospitals are "Not Available".
• HCAHPS scores are percentages (top-box, middle-box, bottom-box responses).
• Provider data is updated quarterly; check modified dates.
• Blue Button API (beneficiary claims data) requires separate OAuth registration.