Navigate to data.cms.gov/provider-data/topics/hospitals to identify the specific dataset you need — for example, Timely and Effective Care, HCAHPS patient survey results, or complications and deaths measures.
Each dataset has a unique identifier in the Provider Data Catalog; use the Socrata Open Data API (SODA) protocol that the catalog exposes to query the dataset programmatically with filters, pagination, and field selection.
Construct a SODA query using the dataset endpoint URL appended with query parameters such as $where for filtering by provider ID or state, $limit and $offset for pagination, and $select for column projection.
Issue an HTTP GET to the endpoint, optionally providing an app token in the X-App-Token header to increase rate limits for high-volume queries.
Parse the JSON response array, where each element represents one hospital-measure row with fields for facility ID, facility name, measure ID, score, denominator, and footnote codes.
Refresh the data on a quarterly schedule aligned with CMS update cycles, using the metadata endpoint to check the last data update date before re-downloading.
Known gotchas
Not all quality measures are updated each quarter; some are updated annually, and querying immediately after a scheduled refresh date may still return the prior period's data if the upload has not completed.
Footnote codes in the score field (such as codes indicating suppression due to small sample size) must be handled explicitly — treating them as numeric scores will corrupt aggregate calculations.
The Provider Data Catalog datasets for hospital quality are separate from the Inpatient Prospective Payment System (IPPS) claims data; they contain publicly reported measure rates, not individual-level claims.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp