Provider

Differences

Note 1: Datastore vs. Metastore
  • Datastore
    • Data from the data files (CSVs)
  • Metastore
    • Metadata from the data.json file
    • title, last_updated, release_date, keywords, etc.

Think of the Metastore as the library index that helps you find the right book (dataset), and the Datastore as the book itself.

Distribution vs. Dataset

  • Distribution
    • Unique identifier of the Datastore
    • Changes with every data refresh
    • Specific to a particular CSV data import
  • Dataset
    • Unique identifier of the Dataset
    • Does not change between data refreshes
    • Comes from the data.json file
    • Appears as part of the URL in the PDC site

If you have been using the datastore/sql or datastore/query/{distributionId} endpoints, consider switching to the datastore/query/{datasetID}/{index} endpoint instead.

The datasetID does not change between refreshes, and, currently, all Provider Data Catalog datasets only have a single resource, so the index will always be 0.

For example, search the Long Term Care Hospital dataset with:

"https://data.cms.gov/provider-data/api/1/datastore/query/5zdx-ny2x/0"

Distribution IDs change with every dataset update, so it is better to use APIs with the Dataset ID and the index of the distribution. If you still need the current distribution ID, you can access it through the metadata API, under distribution -> identifier:

"https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items/[datasetID]?show-reference-ids"

Endpoints

Metastore

  1. Full collection of available metastore schemas
    • GET (No Parameters)
"https://data.cms.gov/provider-data/api/1/metastore/schemas" |> 
  request() |> 
  req_perform() |> 
  resp_body_string() |> 
  jsonify::pretty_json()
  1. A specific schema definition, see https://json-schema.org/
    • GET provider-data/api/1/metastore/schemas/{schema_id} 
"https://data.cms.gov/provider-data/api/1/metastore/schemas/data-dictionary" |> 
  request() |> 
  req_perform() |> 
  resp_body_string() |> 
  jsonify::pretty_json()
  1. Get all items for a specific schema (e.g., “dataset”)
    • GET provider-data/api/1/metastore/schemas/{schema_id}/items 
"https://data.cms.gov/provider-data/api/1/metastore/schemas/data-dictionary" |> 
  request() |> 
  req_perform() |> 
  resp_body_string() |> 
  jsonify::pretty_json()

Metastore: dataset

  1. Get a single dataset.
    • GET provider-data/api/1/metastore/schemas/dataset/items/{identifier} 
"https://data.cms.gov/provider-data/api/1/metastore/schemas/dataset/items/clinical_depression?show-reference-ids=true" |> 
  request() |> 
  req_perform() |> 
  resp_body_string() |> 
  jsonify::pretty_json()
{
    "accessLevel": "public",
    "landingPage": "https://data.cms.gov/provider-data/dataset/clinical_depression",
    "bureauCode": [
        "009:38"
    ],
    "issued": "2021-01-20",
    "@type": "dcat:Dataset",
    "modified": "2024-12-03",
    "released": "2025-01-15",
    "keyword": [
        {
            "identifier": "28fcf043-93be-5044-a7b3-5e05b415e54d",
            "data": "Linking Quality to Payment"
        }
    ],
    "contactPoint": {
        "@type": "vcard:Contact",
        "fn": "ESRD QIP Helpdesk",
        "hasEmail": "mailto:ESRDQIP@cms.hhs.gov"
    },
    "publisher": {
        "identifier": "4c1de1c4-f083-5877-8968-7ddc04756c49",
        "data": {
            "@type": "org:Organization",
            "name": "Centers for Medicare & Medicaid Services (CMS)"
        }
    },
    "identifier": "clinical_depression",
    "description": "This dataset includes facility details, measure score, and the state and national average measure scores for the clinical depression screening and follow up reporting measure included in the PY 2025 ESRD QIP.",
    "title": "ESRD QIP - Clinical Depression Screening and Follow-up - Payment Year 2025",
    "programCode": [
        "009:000"
    ],
    "distribution": [
        {
            "identifier": "0899b062-a295-5479-8304-5e1cffb7e4fd",
            "data": {
                "@type": "dcat:Distribution",
                "downloadURL": "https://data.cms.gov/provider-data/sites/default/files/resources/2c0e67025b8a6b48ee2cda52f1b26498_1734653103/CLINICAL_DEPRESSION.csv",
                "mediaType": "text/csv",
                "%Ref:downloadURL": [
                    {
                        "identifier": "2c0e67025b8a6b48ee2cda52f1b26498__1734653103__source",
                        "data": {
                            "filePath": "s3://211125755750-pdc-prod-df-data/CLINICAL_DEPRESSION.csv",
                            "identifier": "2c0e67025b8a6b48ee2cda52f1b26498",
                            "mimeType": "text/csv",
                            "perspective": "source",
                            "version": "1734653103",
                            "checksum": null
                        }
                    },
                    {
                        "identifier": "2c0e67025b8a6b48ee2cda52f1b26498__1734653103__local_url",
                        "data": {
                            "filePath": "https://h-o.st/provider-data/sites/default/files/resources/2c0e67025b8a6b48ee2cda52f1b26498_1734653103/CLINICAL_DEPRESSION.csv",
                            "identifier": "2c0e67025b8a6b48ee2cda52f1b26498",
                            "mimeType": "text/csv",
                            "perspective": "local_url",
                            "version": "1734653103",
                            "checksum": null
                        }
                    }
                ]
            }
        }
    ],
    "theme": [
        {
            "identifier": "ea23754a-16dc-558c-9183-5189dd4588f5",
            "data": "Dialysis facilities"
        }
    ],
    "%modified": "2024-12-19T19:05:03-0500"
}

Datastore: import

  1. Datastore statistics: Returns the numbers of rows and columns, and a list of columns headers from the datastore
    • GET provider-data/api/1/datastore/imports/{identifier} 
ds_import <- "https://data.cms.gov/provider-data/api/1/datastore/imports/e7fce918-0873-519f-80ae-818e386299d1" |> 
  request() |> 
  req_perform() |> 
  resp_body_json(simplifyVector = TRUE)

ds_import$numOfColumns
[1] 13
ds_import$numOfRows
[1] 1229

Datastore: query

  1. Query one or more datastore resources
    • POST No Parameters
ds_post <- request(
  "https://data.cms.gov/provider-data/api/1/datastore/query/f93da3a3-400b-5efe-960d-c1d72b1d4f65") |> 
  req_method("POST") |> 
  req_headers(Accept = "application/json", 
              `Content-Type` = "application/json") |> 
  req_body_json(
    list(
      limit = 1,
      state = "GA")) |> 
  req_perform() |> 
  resp_body_json(simplifyVector = TRUE)

ds_post$count
ds_post$results |> purse()
  1. Simple GET equivalent of a POST query. Note that parameters containing arrays or objects are not yet supported by SwaggerUI. For conditions, sorts, and other complex parameters, write your query in JSON and then convert to a nested query string. See this web tool for an example.
request("https://data.cms.gov/provider-data/api/1/datastore/query/f93da3a3-400b-5efe-960d-c1d72b1d4f65") |>
  req_url_query(
    limit                     = 1,
    offset                    = 10,
    count                     = "true",
    results                   = "true",
    schema                    = "true",
    keys                      = "true",
    format                    = "json",
    rowIds                    = "false",
    `conditions[0][property]` = "record_number",
    `conditions[0][value]`    = 1,
    `conditions[0][operator]` = ">") |> 
  req_perform() |> 
  resp_body_string() |> 
  jsonify::pretty_json()

Datastore: SQL Query

Search

Schemas