# CMS Hospital Quality Ratings Scraper (`automation-lab/cms-hospital-quality-ratings-scraper`) Actor πŸ₯ Extract CMS hospital ratings, ownership, emergency services, contact info, and quality measure summaries from public Provider Data. - **URL**: https://apify.com/automation-lab/cms-hospital-quality-ratings-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## CMS Hospital Quality Ratings Scraper Extract public CMS hospital quality ratings, facility contact data, ownership details, emergency-services flags, and quality-measure summaries from the official CMS Provider Data API. ### What does CMS Hospital Quality Ratings Scraper do? CMS Hospital Quality Ratings Scraper turns the public CMS Hospital Compare / Provider Data JSON into clean Apify datasets. It helps you collect: - πŸ₯ Hospital names and CMS facility IDs - πŸ“ Addresses, cities, states, ZIP codes, and counties - ☎️ Phone numbers - 🏒 Hospital type and ownership - πŸš‘ Emergency services availability - ⭐ CMS overall hospital star rating - πŸ“Š Mortality, safety, readmission, patient experience, and timely care measure summaries - πŸ”— Source dataset URL for audit trails The actor uses the public CMS Provider Data API, not browser automation. ### Who is it for? Healthcare analysts can use it to compare hospital quality across regions. Market researchers can build facility lists by state, city, ownership, or hospital type. B2B healthcare teams can enrich hospital account lists with CMS quality context. Journalists can quickly export public quality ratings for local reporting. Consultants can monitor public hospital quality data without manually downloading spreadsheets. Developers can pipe structured CMS hospital records into databases, CRMs, dashboards, or notebooks. ### Why use this actor? CMS publishes useful open data, but the raw API is not always convenient for business workflows. This actor adds: - Simple location filters - Hospital type and ownership filters - Star rating threshold filters - Consistent field names - Apify dataset export formats - Pay-per-result charging - API-friendly execution from Apify clients ### Source data The actor currently uses CMS Provider Data dataset `xubh-q36u`. Source dataset: https://data.cms.gov/provider-data/dataset/xubh-q36u API endpoint family: `https://data.cms.gov/provider-data/api/1/datastore/query/xubh-q36u/0` ### Data you can extract | Field | Description | | --- | --- | | `facilityId` | CMS facility identifier | | `facilityName` | Hospital name | | `address` | Street address | | `city` | City | | `state` | Two-letter state | | `zipCode` | ZIP code | | `county` | County or parish | | `phone` | Telephone number | | `hospitalType` | CMS hospital type | | `ownership` | CMS ownership category | | `emergencyServices` | Whether emergency services are reported | | `overallRating` | CMS overall star rating as a number when available | | `safetyBetterCount` | Count of safety measures better than comparison group | | `readmissionBetterCount` | Count of readmission measures better than comparison group | | `sourceDatasetUrl` | CMS source URL | | `scrapedAt` | Export timestamp | ### How much does it cost to extract CMS hospital quality ratings? This Actor uses pay-per-event pricing: a $0.005 run-start fee plus a per-hospital record fee. | Plan tier | Price per hospital record | Approx. 1,000 records | | --- | ---: | ---: | | Free | $0.000031382 | $0.031 | | Starter / Bronze | $0.000027289 | $0.027 | | Scale / Silver | $0.000021285 | $0.021 | | Business / Gold | $0.000016373 | $0.016 | | Platinum | $0.000010916 | $0.011 | | Diamond | $0.000010000 | $0.010 | The default run is intentionally small and uses `maxItems: 20` so first tests stay inexpensive. Use a larger `maxItems` only when you are ready to export more hospitals. ### Quick start 1. Open the actor on Apify. 2. Choose one or more states. 3. Optionally add city, ZIP, hospital type, ownership, emergency-services, or rating filters. 4. Set `maxItems`. 5. Run the actor. 6. Export results from the dataset as JSON, CSV, Excel, XML, or RSS. ### Example input ```json { "states": ["CA"], "hospitalTypes": ["Acute Care Hospitals"], "emergencyServices": "any", "minOverallRating": 4, "includeStarRatings": true, "includeQualityMeasures": true, "maxItems": 100 } ```` ### Input fields #### `states` Two-letter US state abbreviations. Leave empty to search all states. #### `cities` Case-insensitive city names. Use this to focus on one metro area. #### `zipCodes` Exact ZIP code filters. #### `hospitalTypes` CMS hospital type filters. Examples include: - `Acute Care Hospitals` - `Critical Access Hospitals` - `Childrens` - `Psychiatric` Partial matches are supported. #### `ownershipTypes` CMS ownership filters. Examples include: - `Voluntary non-profit` - `Proprietary` - `Government` Partial matches are supported. #### `emergencyServices` Choose `any`, `yes`, or `no`. #### `minOverallRating` Optional minimum CMS overall hospital star rating from 1 to 5. Hospitals without a numeric rating are excluded when this filter is set. #### `includeStarRatings` Include overall star rating fields. #### `includeQualityMeasures` Include quality measure count summaries. #### `maxItems` Maximum number of matching hospitals to save. ### Output example ```json { "facilityId": "050026", "facilityName": "GROSSMONT HOSPITAL", "address": "5555 GROSSMONT CENTER DRIVE BOX 58", "city": "LA MESA", "state": "CA", "zipCode": "91942", "county": "SAN DIEGO", "phone": "(619) 465-0711", "hospitalType": "Acute Care Hospitals", "ownership": "Government - Hospital District or Authority", "emergencyServices": "Yes", "overallRating": 4, "sourceDatasetUrl": "https://data.cms.gov/provider-data/dataset/xubh-q36u" } ``` ### Filtering tips Start broad, then narrow. For example, run a state export first, then add city, ownership, or rating filters. Use partial ownership filters like `Government` or `Voluntary non-profit` when you do not know the exact CMS label. Use `minOverallRating` for ranked shortlists. Leave quality measures off if you only need facility contact fields. ### Common workflows #### Regional hospital benchmark Export hospitals in one state with `includeQualityMeasures: true` and compare safety, mortality, and readmission summaries. #### Hospital lead enrichment Filter by state, city, or ZIP and join the CMS facility ID back to your CRM. #### Public data monitoring Schedule the actor monthly to track CMS Provider Data changes over time. #### Journalism and civic research Export local hospitals and cite the official CMS dataset URL included in every row. ### Integrations You can connect the dataset to: - Google Sheets - Airtable - Snowflake - BigQuery - PostgreSQL - Power BI - Tableau - Python notebooks - internal healthcare data warehouses Use Apify webhooks to trigger downstream jobs when each run finishes. ### API usage with Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/cms-hospital-quality-ratings-scraper').call({ states: ['CA'], minOverallRating: 4, maxItems: 100 }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` ### API usage with Python ```python from apify_client import ApifyClient client = ApifyClient('APIFY_TOKEN') run = client.actor('automation-lab/cms-hospital-quality-ratings-scraper').call(run_input={ 'states': ['CA'], 'minOverallRating': 4, 'maxItems': 100, }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items) ``` ### API usage with cURL ```bash curl -X POST "https://api.apify.com/v2/acts/automation-lab~cms-hospital-quality-ratings-scraper/runs?token=$APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"states":["CA"],"minOverallRating":4,"maxItems":100}' ``` ### MCP integration Use this actor through the Apify MCP server in Claude Desktop or Claude Code. MCP server URL: `https://mcp.apify.com/?tools=automation-lab/cms-hospital-quality-ratings-scraper` Claude Code setup command: ```bash claude mcp add apify-cms-hospital-quality-ratings --transport http "https://mcp.apify.com/?tools=automation-lab/cms-hospital-quality-ratings-scraper" ``` Claude Desktop JSON config example: ```json { "mcpServers": { "apify-cms-hospital-quality-ratings": { "url": "https://mcp.apify.com/?tools=automation-lab/cms-hospital-quality-ratings-scraper" } } } ``` Example prompts: - "Run the CMS hospital quality ratings scraper for California acute care hospitals with at least 4 stars." - "Export hospitals in Houston from CMS Provider Data and summarize their ownership types." - "Find critical access hospitals in Montana and return their phone numbers and CMS ratings." ### Scheduling Hospitals and CMS quality fields can change as CMS updates Provider Data. For monitoring, schedule a weekly or monthly run with the same filters. Store each dataset export separately so you can compare changes over time. ### Data freshness The actor reads the live public CMS Provider Data API at run time. Rows reflect whatever CMS currently serves from dataset `xubh-q36u`. Every output row includes `scrapedAt` and `sourceDatasetUrl`. ### Limitations This actor does not scrape individual hospital websites. It does not infer ratings that CMS does not publish. It does not provide medical advice. If CMS changes the dataset ID or field names, the actor will fail with a clear API/schema message rather than silently returning invented data. ### Legality The actor uses public CMS Provider Data endpoints. You are responsible for using exported data in compliance with applicable laws, CMS terms, privacy rules, and your organization’s policies. Do not use public quality data as the sole basis for clinical, financial, or patient-care decisions. ### FAQ #### Why did my run return zero hospitals? Your filters may be too narrow. Try removing city, ZIP, ownership, hospital type, or minimum rating filters. #### Why is `overallRating` null? CMS may not publish a numeric overall rating for that facility. Use `overallRatingRaw` and `overallRatingFootnote` for context. #### Why are quality measure fields missing? Set `includeQualityMeasures` to `true`. ### Related scrapers Other Automation Lab actors can complement this dataset: - https://apify.com/automation-lab/google-maps-reviews-scraper - https://apify.com/automation-lab/website-contact-finder - https://apify.com/automation-lab/business-website-scraper ### Changelog #### 0.1 Initial version using the public CMS Provider Data API for hospital quality ratings. ### Support If you need additional CMS Provider Data fields, open an issue on the actor page with the target dataset and fields. # Actor input Schema ## `states` (type: `array`): Two-letter US state abbreviations to include. Leave empty to search all states. ## `cities` (type: `array`): Case-insensitive city names to include. Leave empty to include all cities in the selected states. ## `zipCodes` (type: `array`): Exact ZIP codes to include. Leave empty to include all ZIP codes. ## `hospitalTypes` (type: `array`): CMS hospital type filters, e.g. Acute Care Hospitals or Critical Access Hospitals. Partial matches are supported. ## `ownershipTypes` (type: `array`): CMS ownership filters, e.g. Voluntary non-profit, Proprietary, Government. Partial matches are supported. ## `emergencyServices` (type: `string`): Filter hospitals by whether CMS reports emergency services. ## `minOverallRating` (type: `integer`): Optional minimum CMS overall hospital star rating from 1 to 5. Unrated hospitals are excluded when this is set. ## `includeStarRatings` (type: `boolean`): Include CMS overall hospital star rating and footnote fields in each output item. ## `includeQualityMeasures` (type: `boolean`): Include mortality, safety, readmission, patient experience, and timely/effective care measure count summaries. ## `maxItems` (type: `integer`): Maximum matching hospital records to save. ## Actor input object example ```json { "states": [ "CA" ], "cities": [], "zipCodes": [], "hospitalTypes": [ "Acute Care Hospitals" ], "ownershipTypes": [], "emergencyServices": "any", "minOverallRating": 4, "includeStarRatings": true, "includeQualityMeasures": true, "maxItems": 20 } ``` # Actor output Schema ## `overview` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "states": [ "CA" ], "cities": [], "zipCodes": [], "hospitalTypes": [ "Acute Care Hospitals" ], "ownershipTypes": [], "emergencyServices": "any", "minOverallRating": 4, "includeStarRatings": true, "includeQualityMeasures": true, "maxItems": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/cms-hospital-quality-ratings-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "states": ["CA"], "cities": [], "zipCodes": [], "hospitalTypes": ["Acute Care Hospitals"], "ownershipTypes": [], "emergencyServices": "any", "minOverallRating": 4, "includeStarRatings": True, "includeQualityMeasures": True, "maxItems": 20, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/cms-hospital-quality-ratings-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "states": [ "CA" ], "cities": [], "zipCodes": [], "hospitalTypes": [ "Acute Care Hospitals" ], "ownershipTypes": [], "emergencyServices": "any", "minOverallRating": 4, "includeStarRatings": true, "includeQualityMeasures": true, "maxItems": 20 }' | apify call automation-lab/cms-hospital-quality-ratings-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/cms-hospital-quality-ratings-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "CMS Hospital Quality Ratings Scraper", "description": "πŸ₯ Extract CMS hospital ratings, ownership, emergency services, contact info, and quality measure summaries from public Provider Data.", "version": "0.1", "x-build-id": "03h2bvo6WfhachIgT" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~cms-hospital-quality-ratings-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-cms-hospital-quality-ratings-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/automation-lab~cms-hospital-quality-ratings-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-cms-hospital-quality-ratings-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/automation-lab~cms-hospital-quality-ratings-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-cms-hospital-quality-ratings-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "states": { "title": "States", "type": "array", "description": "Two-letter US state abbreviations to include. Leave empty to search all states.", "items": { "type": "string", "minLength": 2, "maxLength": 2 } }, "cities": { "title": "Cities", "type": "array", "description": "Case-insensitive city names to include. Leave empty to include all cities in the selected states.", "items": { "type": "string" } }, "zipCodes": { "title": "ZIP codes", "type": "array", "description": "Exact ZIP codes to include. Leave empty to include all ZIP codes.", "items": { "type": "string" } }, "hospitalTypes": { "title": "Hospital types", "type": "array", "description": "CMS hospital type filters, e.g. Acute Care Hospitals or Critical Access Hospitals. Partial matches are supported.", "items": { "type": "string" } }, "ownershipTypes": { "title": "Ownership types", "type": "array", "description": "CMS ownership filters, e.g. Voluntary non-profit, Proprietary, Government. Partial matches are supported.", "items": { "type": "string" } }, "emergencyServices": { "title": "Emergency services", "enum": [ "any", "yes", "no" ], "type": "string", "description": "Filter hospitals by whether CMS reports emergency services.", "default": "any" }, "minOverallRating": { "title": "Minimum overall star rating", "minimum": 1, "maximum": 5, "type": "integer", "description": "Optional minimum CMS overall hospital star rating from 1 to 5. Unrated hospitals are excluded when this is set." }, "includeStarRatings": { "title": "Include star rating fields", "type": "boolean", "description": "Include CMS overall hospital star rating and footnote fields in each output item.", "default": true }, "includeQualityMeasures": { "title": "Include quality measure summaries", "type": "boolean", "description": "Include mortality, safety, readmission, patient experience, and timely/effective care measure count summaries.", "default": true }, "maxItems": { "title": "Maximum hospitals", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum matching hospital records to save.", "default": 20 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```