Getting Started with the CMS Provider Data API — CMS Provider Data API

When to use this API

When you need to find and access Medicare and Medicaid provider quality data — dialysis facility ratings, home health agency performance, hospice provider characteristics, or patient experience surveys for specific care settings. The CMS Provider Data API is the catalog and query layer over datasets published by the Centers for Medicare & Medicaid Services. No auth. No key. The architecture is two-tier: the metastore layer tells you which datasets exist and gives you direct CSV download URLs, while the datastore layer lets you query individual records programmatically. For beneficiary-level claims data or physician billing records, look elsewhere — this API covers facility-level and aggregate quality reporting.

Discovering what provider datasets CMS publishes

"What quality data does CMS publish for dialysis facilities?" The /metastore/schemas/dataset/items endpoint returns the full catalog of available datasets. Each entry follows the DCAT standard (the same metadata schema used across data.gov catalogs), so any open-data library that parses Project Open Data feeds can consume this response.

curl "https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items" | head -c 10000

[
  {
    "@type": "dcat:Dataset",
    "identifier": "23ew-n7w9",
    "title": "Dialysis Facility - Listing by Facility",
    "description": "A list of all dialysis facilities registered with Medicare that includes addresses and phone numbers, as well as services and quality of care provided.",
    "theme": ["Dialysis facilities"],
    "modified": "2025-12-18",
    "nextUpdateDate": "2026-04-22",
    "keyword": ["Quality", "Quality Measures"],
    "distribution": [{
      "downloadURL": "https://data.cms.gov/provider-data/sites/default/files/resources/c04d84bc5c641284494bee4f20f17f9c_1766441148/DFC_FACILITY.csv",
      "mediaType": "text/csv",
      "describedBy": "https://data.cms.gov/provider-data/sites/default/files/data_dictionaries/dialysis/DF_Data_Dictionary.pdf"
    }]
  },
  {
    "@type": "dcat:Dataset",
    "identifier": "59mq-zhts",
    "title": "Patient survey (ICH CAHPS) - Facility",
    "description": "In-Center Hemodialysis Facilities Patient evaluations from the ICH-CAHPS Survey — a national standardized survey of in-center hemodialysis patients about their experiences with facility doctors and staff.",
    "theme": ["Dialysis facilities"],
    "keyword": ["Patient Survey", "Patient Experience of Care"],
    "modified": "2025-12-18",
    "nextUpdateDate": "2026-04-22",
    "distribution": [{
      "downloadURL": "https://data.cms.gov/provider-data/sites/default/files/resources/af4027a6449e63899d56ecec0c718998_1766441154/ICH_CAHPS_FACILITY.csv",
      "mediaType": "text/csv",
      "describedBy": "https://data.cms.gov/provider-data/sites/default/files/data_dictionaries/dialysis/DF_Data_Dictionary.pdf"
    }]
  }
  // ... 231 more datasets
]

Most CMS data journalism focuses on clinical outcomes — infection rates, readmission rates. The ICH-CAHPS entry (identifier 59mq-zhts) is a different category of signal entirely: it's a patient experience survey measuring whether dialysis staff treated patients with respect and explained treatment clearly. End-stage renal disease patients often attend dialysis three times a week for years, which makes their perception of staff communication unusually meaningful. The nextUpdateDate field is a CMS-specific addition to standard DCAT; use it to decide whether a cached catalog response is stale before answering a question about current data availability.

For dialysis, CMS publishes four separate datasets: the facility listing with addresses (23ew-n7w9), state averages (2fpu-cgbb), national averages (2rkq-ygai), and the ICH-CAHPS patient experience survey (59mq-zhts). The survey data is updated quarterly — next update is April 22, 2026. Each dataset has a direct CSV download link in its distribution field.

Retrieving metadata for a specific dataset

"How do I access the actual ICH-CAHPS patient survey data and understand its columns?" Pass the identifier to /metastore/schemas/dataset/items/{datasetId} for the single-dataset record. This returns the same object schema as one element from the catalog list — use distribution[0].downloadURL for the CSV file and distribution[0].describedBy for the PDF data dictionary that explains every column name.

curl "https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items/59mq-zhts" | head -c 10000

{
  "@type": "dcat:Dataset",
  "identifier": "59mq-zhts",
  "title": "Patient survey (ICH CAHPS) - Facility",
  "issued": "2020-03-14",
  "modified": "2025-12-18",
  "released": "2026-01-21",
  "nextUpdateDate": "2026-04-22",
  "keyword": ["Patient Survey", "Patient Experience of Care"],
  "contactPoint": {
    "fn": "Dialysis Facility Helpdesk",
    "hasEmail": "mailto:DialysisData@umich.edu"
  },
  "publisher": {
    "name": "Centers for Medicare & Medicaid Services (CMS)"
  },
  "distribution": [{
    "downloadURL": "https://data.cms.gov/provider-data/sites/default/files/resources/af4027a6449e63899d56ecec0c718998_1766441154/ICH_CAHPS_FACILITY.csv",
    "mediaType": "text/csv",
    "describedBy": "https://data.cms.gov/provider-data/sites/default/files/data_dictionaries/dialysis/DF_Data_Dictionary.pdf",
    "describedByType": "application/pdf"
  }]
}

Three date fields appear here with distinct meanings: issued is when the dataset was first published (2020), modified is when CMS internally updated the source (December 2025), and released is when the current snapshot was made publicly available (January 2026). The six-week gap between modified and released is CMS's internal review period before publication — if you see a recent modified date but an older released date, the data is still in review. The contactPoint.hasEmail is functional; CMS dataset teams monitor these addresses.

The ICH-CAHPS patient survey data is available at: https://data.cms.gov/provider-data/sites/default/files/resources/af4027a6449e63899d56ecec0c718998_1766441154/ICH_CAHPS_FACILITY.csv — released January 21, 2026. Before parsing, check the data dictionary at the describedBy URL to understand the column names; the PDF explains survey question codes that aren't self-documenting.

Pitfalls

The catalog listing returns all 233 datasets in one response with no server-side filtering by theme or category. For a user asking about a specific care area, fetch the full catalog, then filter locally on the theme field — do not attempt to pass theme or keyword as URL parameters, as the endpoint does not support them.
Download URLs contain content-hash path segments (the c04d84bc5c641284494bee4f20f17f9c_... portion) that change on every data refresh. Never hardcode a downloadURL — always resolve it through the metastore immediately before downloading so you get the current version.
Dataset identifiers are opaque strings (59mq-zhts, 23ew-n7w9) with no semantic meaning — they cannot be guessed or derived from dataset titles. Discover them from the catalog or from the dataset's landing page URL at data.cms.gov/provider-data/dataset/{identifier}.

One-line summary for the user

I can retrieve catalog metadata and direct CSV download links for the 233 CMS Medicare and Medicaid provider quality datasets — no auth required, but the actual facility records are in the referenced CSV files rather than in the API responses themselves.