# CMS Home Health Compare Scraper (`automation-lab/cms-home-health-compare-scraper`) Actor Extract CMS home health agency contacts, ownership, services, quality ratings, and HHCAHPS patient survey scores for market research. - **URL**: https://apify.com/automation-lab/cms-home-health-compare-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Lead generation, Other - **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 Home Health Compare Scraper Extract Medicare-certified home health agency records from CMS Provider Data / Care Compare. Use this actor to collect agency names, CMS Certification Numbers, addresses, phones, ownership, services, quality star ratings, selected quality measures, and HHCAHPS patient survey scores. The actor is built for repeatable healthcare market mapping, lead generation, referral-network research, quality benchmarking, and competitor monitoring. ### What does CMS Home Health Compare Scraper do? CMS Home Health Compare Scraper downloads the public CMS Provider Data home health agency datasets and turns them into clean Apify dataset rows. It focuses on one entity: Medicare-certified home health agencies. Each output row combines provider listing data with optional HHCAHPS patient survey metrics. The scraper uses official CMS CSV downloads rather than a fragile browser workflow. That means runs are fast, stable, and suitable for recurring refreshes. ### Who is it for? ๐Ÿฅ Healthcare lead-generation teams use it to build agency prospect lists by state, city, ownership, and quality threshold. ๐Ÿ“Š Market intelligence teams use it to compare provider density, service coverage, and quality ratings across local markets. ๐Ÿค Referral-network teams use it to identify qualified home health partners for hospitals, discharge planners, and care coordinators. ๐Ÿงพ Compliance and quality teams use it to monitor CMS rating changes and public reporting updates. ๐Ÿ’ผ Healthcare investors and operators use it to map acquisition targets and competitor footprints. ### Why use this actor? CMS publishes valuable data, but raw provider files are large and not shaped for sales or BI workflows. This actor handles dataset discovery, CSV parsing, filtering, patient-survey joins, output normalization, and Apify dataset export. You can run it from the Apify Console, schedule it, call it from an API, or pipe the dataset into your CRM or warehouse. ### Data source The actor uses CMS Provider Data from `data.cms.gov/provider-data`. Primary dataset: Home Health Care Agencies. Patient survey dataset: Home Health Care - Patient Survey (HHCAHPS) provider data. Dataset metadata such as modified date and next update date is included in each output item. ### What data can you extract? | Field group | Example fields | | --- | --- | | Agency identity | `ccn`, `providerName` | | Contact | `address`, `city`, `state`, `zipCode`, `phone` | | Ownership | `ownership`, `certificationDate` | | Services | nursing care, physical therapy, occupational therapy, speech pathology, medical social, home health aide | | Quality | quality-of-patient-care star rating and selected measure percentages | | Patient survey | HHCAHPS summary stars, communication stars, recommendation percent, survey count | | Source metadata | source dataset, source URL, modified date, next update date, scrape time | ### Input options You can filter the source dataset before saving items. `state` limits results to a two-letter state abbreviation. `city` limits results to a CMS city/town value. `search` looks across provider name, address, and city. `ownership` matches ownership text such as `PROPRIETARY` or `NON-PROFIT`. `minQualityRating` keeps only agencies with a CMS quality star rating at or above the threshold. `minPatientSurveyRating` keeps only agencies with an HHCAHPS survey summary star rating at or above the threshold. `includePatientSurvey` controls whether the actor joins HHCAHPS survey data by CCN. `maxItems` controls the maximum number of matching agencies saved. ### Example input ```json { "state": "TX", "city": "HOUSTON", "minQualityRating": 4, "includePatientSurvey": true, "maxItems": 100 } ```` ### Example output ```json { "ccn": "747123", "providerName": "EXAMPLE HOME HEALTH", "state": "TX", "city": "HOUSTON", "address": "123 MAIN STREET", "zipCode": "77002", "phone": "7135550100", "ownership": "PROPRIETARY", "qualityOfPatientCareStarRating": 4, "patientSurveySummaryStarRating": 5, "services": { "nursingCare": true, "physicalTherapy": true }, "sourceDataset": "Home Health Care Agencies" } ``` ### How much does it cost to scrape CMS home health agencies? This actor uses pay-per-event pricing. There is a small start charge for each run. There is a per-agency charge for each dataset item saved. Default runs are inexpensive because the actor reads public CMS files without browser automation or proxies. Use `maxItems` to cap exploratory runs. ### How to scrape Texas home health agencies 1. Open the actor on Apify. 2. Enter `TX` in the state field. 3. Leave city empty for statewide results or add a city such as `HOUSTON`. 4. Keep `includePatientSurvey` enabled if you need HHCAHPS fields. 5. Set `maxItems` to your desired cap. 6. Start the run. 7. Export results as JSON, CSV, Excel, or API. ### How to find high-rated agencies Set `minQualityRating` to `4` or `4.5`. Optionally set `minPatientSurveyRating` to `4`. This is useful for partner discovery, referral-network screening, and quality benchmarking. ### How to monitor competitors Create one task per market or state. Schedule the task monthly or quarterly. Compare dataset exports over time by `ccn` and rating fields. Use the `datasetModified` and `datasetNextUpdate` fields to understand CMS freshness. ### Data freshness CMS periodically refreshes Provider Data files. The actor reads the current download URL from the CMS Provider Data catalog at run time. This avoids hard-coding one stale CSV file. When CMS changes the file resource URL, the actor follows the current catalog entry. ### Integrations Send results to Google Sheets for market maps. Send results to a CRM for lead routing. Load results into Snowflake, BigQuery, or PostgreSQL for analytics. Connect results to BI dashboards for provider density and quality scoring. Use webhooks to notify teams when a scheduled market refresh finishes. ### API usage Run with the Apify API from 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-home-health-compare-scraper').call({ state: 'TX', maxItems: 100 }); console.log(run.defaultDatasetId); ``` ### Python API usage ```python from apify_client import ApifyClient client = ApifyClient('MY-APIFY-TOKEN') run = client.actor('automation-lab/cms-home-health-compare-scraper').call(run_input={ 'state': 'CA', 'maxItems': 100, }) print(run['defaultDatasetId']) ``` ### cURL API usage ```bash curl -X POST 'https://api.apify.com/v2/acts/automation-lab~cms-home-health-compare-scraper/runs?token=MY-APIFY-TOKEN' \ -H 'Content-Type: application/json' \ -d '{"state":"NY","maxItems":100}' ``` ### MCP usage Use this actor from Claude Desktop or Claude Code through Apify MCP. MCP server URL: `https://mcp.apify.com/?tools=automation-lab/cms-home-health-compare-scraper` Add it in Claude Code: ```bash claude mcp add apify-cms-home-health "https://mcp.apify.com/?tools=automation-lab/cms-home-health-compare-scraper" ``` Claude Desktop JSON config: ```json { "mcpServers": { "apify-cms-home-health": { "url": "https://mcp.apify.com/?tools=automation-lab/cms-home-health-compare-scraper" } } } ``` Example prompts: - "Find high-rated home health agencies in Houston and summarize the largest ownership groups." - "Build a CSV of non-profit home health agencies in California with patient survey scores." - "Compare CMS quality ratings for home health agencies in Phoenix and Tucson." ### Tips for best results Use uppercase state abbreviations for readability. Use CMS city spellings when applying a city filter. Start with `maxItems` around 100 for testing. Increase `maxItems` for statewide or national exports. Leave rating filters empty when you need complete market coverage. Enable patient survey data when you need patient-experience scores. Disable patient survey data for the fastest identity-only exports. ### Limitations The actor only returns agencies present in CMS public Provider Data. Some measures may be unavailable for agencies with too few cases. CMS uses `-` or footnotes for suppressed fields; the actor returns unavailable numeric fields as `null`. The actor does not scrape private payer networks or non-Medicare agencies. ### Legality This actor extracts public government data from CMS Provider Data. You are responsible for using the data according to applicable laws, CMS terms, and your organization's compliance policies. Do not use contact data for unlawful spam or prohibited outreach. ### FAQ #### Does this scrape the CMS Care Compare website? It uses the underlying CMS Provider Data downloads that power public comparison workflows. This is more reliable than browser scraping. #### Why are some ratings null? CMS suppresses some measures when the sample size is too small or data is unavailable. The actor preserves that reality by returning `null` for unavailable numeric values. #### Can I scrape all states? Yes. Leave `state` empty and set a large enough `maxItems`. #### Can I filter by ownership? Yes. Use values such as `PROPRIETARY`, `NON-PROFIT`, or another substring from CMS ownership text. #### How do I avoid missing agencies? Do not set rating filters when your goal is full coverage. Some agencies have no reportable quality or survey star rating. ### Related scrapers Explore other healthcare and public-data actors from automation-lab: - https://apify.com/automation-lab/cms-nursing-home-compare-scraper - https://apify.com/automation-lab/cms-hospital-quality-ratings-scraper - https://apify.com/automation-lab/openfda-drug-adverse-event-scraper - https://apify.com/automation-lab/propublica-nonprofit-explorer-scraper ### Support If you need a new CMS dataset, a different healthcare vertical, or custom output fields, open an issue on the actor page. Include the market, fields, and example workflow you need. ### Changelog Initial private build for CMS Home Health Compare / Provider Data home health agency extraction. # Actor input Schema ## `state` (type: `string`): Two-letter state abbreviation, e.g. TX, CA, NY. Leave empty for all states. ## `city` (type: `string`): Optional city/town filter exactly as CMS lists it. ## `search` (type: `string`): Case-insensitive text search across provider name, address, and city. ## `ownership` (type: `string`): Filter by ownership text such as PROPRIETARY, NON-PROFIT, GOVERNMENT, or VOLUNTARY NON-PROFIT. ## `minQualityRating` (type: `number`): Only include agencies with this CMS quality-of-patient-care star rating or higher. ## `minPatientSurveyRating` (type: `number`): Only include agencies with this HHCAHPS survey summary star rating or higher. ## `includePatientSurvey` (type: `boolean`): Join HHCAHPS patient survey ratings and recommendation fields by CMS Certification Number. ## `maxItems` (type: `integer`): Maximum number of matching home health agencies to save. ## Actor input object example ```json { "state": "TX", "city": "HOUSTON", "includePatientSurvey": true, "maxItems": 20 } ``` # Actor output Schema ## `agencies` (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 = { "state": "TX", "city": "HOUSTON", "includePatientSurvey": true, "maxItems": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/cms-home-health-compare-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 = { "state": "TX", "city": "HOUSTON", "includePatientSurvey": True, "maxItems": 20, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/cms-home-health-compare-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 '{ "state": "TX", "city": "HOUSTON", "includePatientSurvey": true, "maxItems": 20 }' | apify call automation-lab/cms-home-health-compare-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/cms-home-health-compare-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "CMS Home Health Compare Scraper", "description": "Extract CMS home health agency contacts, ownership, services, quality ratings, and HHCAHPS patient survey scores for market research.", "version": "0.1", "x-build-id": "f6g67EivzS5XKyVJ7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~cms-home-health-compare-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-cms-home-health-compare-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-home-health-compare-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-cms-home-health-compare-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-home-health-compare-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-cms-home-health-compare-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": { "state": { "title": "State abbreviation", "type": "string", "description": "Two-letter state abbreviation, e.g. TX, CA, NY. Leave empty for all states." }, "city": { "title": "City", "type": "string", "description": "Optional city/town filter exactly as CMS lists it." }, "search": { "title": "Agency/name search", "type": "string", "description": "Case-insensitive text search across provider name, address, and city." }, "ownership": { "title": "Ownership contains", "type": "string", "description": "Filter by ownership text such as PROPRIETARY, NON-PROFIT, GOVERNMENT, or VOLUNTARY NON-PROFIT." }, "minQualityRating": { "title": "Minimum quality star rating", "minimum": 1, "maximum": 5, "type": "number", "description": "Only include agencies with this CMS quality-of-patient-care star rating or higher." }, "minPatientSurveyRating": { "title": "Minimum patient survey star rating", "minimum": 1, "maximum": 5, "type": "number", "description": "Only include agencies with this HHCAHPS survey summary star rating or higher." }, "includePatientSurvey": { "title": "Include patient survey fields", "type": "boolean", "description": "Join HHCAHPS patient survey ratings and recommendation fields by CMS Certification Number.", "default": true }, "maxItems": { "title": "Maximum agencies", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of matching home health agencies 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 } } } } } } } } } } ```