# Healthgrades Scraper - Doctors, Ratings & Reviews (`haketa/healthgrades-scraper`) Actor Healthgrades scraper & API: find US doctors by specialty & location and export name, NPI, specialty, patient rating & review count, phone, practice address, hospital affiliations and accepting-new-patients. Healthcare provider data and medical lead generation โ€” fast, no login. - **URL**: https://apify.com/haketa/healthgrades-scraper.md - **Developed by:** [Haketa](https://apify.com/haketa) (community) - **Categories:** Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $1.50 / 1,000 results 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 ## Healthgrades Scraper ๐Ÿฉบ โ€” Doctors, Ratings & Reviews by Specialty + Location Extract **US healthcare provider data from Healthgrades** as clean, structured JSON โ€” search **doctors by specialty and location** and get **name, NPI, specialty, patient star rating & review count, practice addresses, hospital affiliations, accepting-new-patients status, telehealth** and more. Fast and reliable: API-first (the data is read straight from Healthgrades' own structured feed, no fragile HTML scraping), with automatic pagination and US residential proxy handling. > ๐Ÿ’ก **Why this actor?** It returns the **ratings, reviews and rich practice data** that the free NPI/NPPES registry simply doesn't have โ€” patient star ratings, review counts, Healthgrades Choice badges, hospital affiliations and specialty detail โ€” perfect for healthcare lead-gen, referral networks and market research. --- ### ๐Ÿ“‹ Table of contents - [What does it do?](#what-does-it-do) - [Use cases](#use-cases) - [How to use it](#how-to-use-it-step-by-step) - [Input parameters](#input-parameters) - [Input examples](#input-examples) - [Output โ€” data fields](#output--data-fields) - [Sample output record](#sample-output-record) - [How it compares to the NPI registry](#how-it-compares-to-the-npi-registry) - [Tips & best practices](#tips--best-practices) - [Frequently asked questions](#frequently-asked-questions) - [Changelog](#changelog) --- ### What does it do? Give it a **specialty** (or condition / doctor name) and one or more **locations**, and it returns every matching provider with: - ๐Ÿ‘ฉโ€โš•๏ธ **Identity:** name, NPI, specialty, gender, years since graduation, photo, profile URL. - โญ **Reputation:** patient star rating, review count, Healthgrades Choice / patient-favorite / recommended flags, patient-highlighted strengths. - ๐Ÿ“ **Practice:** every office location with street, city, state, ZIP and coordinates. - ๐Ÿฅ **Affiliations & access:** affiliated hospitals, accepts-new-patients, telehealth availability. Export to **JSON, CSV, Excel, XML or HTML**, or pull from the **Apify API**. --- ### Use cases **๐Ÿ“‡ Healthcare lead generation & marketing** - Build targeted provider lists by specialty + city with ratings and practice addresses. - Power referral networks, medical staffing and outreach. **๐Ÿ“Š Market & competitive research** - Map provider density, ratings and hospital affiliations across markets. - Benchmark reputation by specialty and location. **๐Ÿฅ Health systems & recruiters** - Find and qualify providers; track accepting-new-patients and telehealth. **๐Ÿค– Data & AI teams** - Build provider datasets enriched with patient-reputation signals. --- ### How to use it (step by step) No coding required. 1. Click **Try for free / Start**. 2. Enter a **Specialty** (e.g. `Cardiologist`, `Dermatologist`, `Family Medicine`). 3. Add one or more **Locations** (e.g. `Miami, FL`, `New York, NY`). 4. Set **Max providers**. 5. Keep the proxy on its default โ€” **US Residential** (required). 6. Click **Save & Start**, then export the results. --- ### Input parameters | Field | Type | Description | |------|------|-------------| | `specialty` | string | Specialty / condition / name to search, e.g. `Cardiologist`. | | `locations` | array | Locations as `City, ST` (e.g. `Miami, FL`). The specialty is searched in each. | | `startUrls` | array | Advanced: paste Healthgrades search URLs directly. Overrides the builder. | | `maxItems` | integer | Max providers. `0` = no limit. Default `200`. | | `maxPagesPerSearch` | integer | Pagination cap per specialty+location (~20 providers/page). Default `20`. | | `proxyConfiguration` | object | **US Residential is required** (Healthgrades is US-only and blocks datacenter IPs). Default. | | `maxConcurrency` | integer | Max parallel requests. Default `3`. | --- ### Input examples **1) Cardiologists in Miami** ```json { "specialty": "Cardiologist", "locations": ["Miami, FL"], "maxItems": 200 } ```` **2) Dermatologists across several cities** ```json { "specialty": "Dermatologist", "locations": ["New York, NY", "Los Angeles, CA", "Chicago, IL"], "maxItems": 1000 } ``` **3) Advanced โ€” paste a search URL** ```json { "startUrls": [ { "url": "https://www.healthgrades.com/usearch?what=Pediatrician&where=Austin,+TX" } ] } ``` *** ### Output โ€” data fields One record per provider: | Field | Description | |------|-------------| | `name` | Provider name (with credentials) | | `npi` | National Provider Identifier | | `profileUrl` | Healthgrades profile URL | | `specialty` | Primary specialty | | `specialtyDescription` | Specialty description | | `gender` | Gender | | `yearsSinceGraduation` | Years since graduation | | `rating` | Patient star rating (0โ€“5) | | `reviewCount` | Number of patient surveys/reviews | | `ratingPercent` | Overall rating percentage | | `acceptsNewPatients` | Accepting new patients | | `telehealthAvailable` / `isTelehealthOnly` | Telehealth flags | | `isHealthgradesChoice` / `isPatientFavorite` / `isRecommendedProvider` | Badges | | `primaryOfficeName` | Main practice name | | `phone` / `phones` | Primary office phone number(s) | | `photoUrl` | Provider photo | | `city` / `state` / `zip` / `address` / `latitude` / `longitude` | Primary location (flattened) | | `addresses` | All practice locations (`address1`, `address2`, `city`, `state`, `zip`, `cityState`, `officeCode`, `latitude`, `longitude`) | | `affiliatedHospitalIds` | Affiliated hospital IDs | | `hasTopHospital` | Affiliated with a top hospital | | `payorCount` / `payors` | Accepted insurance (when available) | | `strengths` | Patient-highlighted strengths | | `aboutMe` / `carePhilosophy` | Bio / care philosophy | | `providerId` | Internal provider ID | | `searchSpecialty` / `searchLocation` | The search that produced this record | | `scrapedAt` | ISO timestamp | *** ### Sample output record ```json { "name": "Dr. Juan Cueto, MD", "npi": "1588614572", "profileUrl": "https://www.healthgrades.com/physician/dr-juan-cueto-x3bjy", "specialty": "Cardiology", "gender": "M", "rating": 4.8, "reviewCount": 15, "acceptsNewPatients": true, "telehealthAvailable": true, "isHealthgradesChoice": false, "city": "Miami", "state": "FL", "zip": "33133", "address": "3663 S Miami Ave", "addresses": [ { "address1": "3663 S Miami Ave", "city": "Miami", "state": "FL", "zip": "33133", "officeCode": "XR66RS" } ], "affiliatedHospitalIds": ["HGST5D138D46100167"], "photoUrl": "https://photos.healthgrades.com/img/prov/x/3/b/x3bjy_...jpg", "searchSpecialty": "Cardiologist", "searchLocation": "Miami, FL", "scrapedAt": "2026-06-05T12:00:00.000Z" } ``` *** ### How it compares to the NPI registry The free **NPI / NPPES registry** gives you the complete universe of providers with NPI, taxonomy and licensing โ€” but it has **no patient ratings, no reviews, no star scores, no Healthgrades Choice badges, no hospital affiliations, no photos/bios and no specialty reputation data.** This actor adds exactly that **consumer-facing reputation and rich practice layer**. Use the NPI registry for the full universe and verification, and this Healthgrades actor for **ratings, reviews and enrichment** โ€” together they make a complete healthcare lead-gen dataset. *** ### Tips & best practices - ๐ŸŒ **Use the default US Residential proxy** โ€” Healthgrades is US-only and blocks datacenter IPs; non-residential will return 0 results. - ๐Ÿงช **Start with one specialty + one city** and a small `maxItems` to confirm the output. - ๐Ÿงฑ **Add multiple locations** to cover a region or the whole country. - ๐Ÿ” **Schedule runs** to track ratings, new providers and accepting-new-patients changes over time. - ๐Ÿ’พ **Use the Apify API / integrations** to push results into Google Sheets, a CRM, or a webhook. *** ### Frequently asked questions **Do I need a US proxy?** Yes โ€” Healthgrades only serves US traffic and blocks datacenter IPs. The actor defaults to US Residential; keep it. **Does it include patient ratings and review counts?** Yes โ€” star rating, review count and rating percentage are core fields. **Does it return NPI?** Yes, when available on the listing. **Can I search a whole region?** Add multiple `City, ST` locations and the actor searches each. **What export formats are supported?** JSON, CSV, Excel, XML, HTML table, RSS โ€” plus the Apify API and integrations. *** ### Changelog **0.1.0** - Initial release: search providers by specialty + location with automatic pagination. - Rich provider records: NPI, specialty, patient rating & review count, all practice locations with coordinates, hospital affiliations, badges, telehealth and accepting-new-patients. - US residential proxy handling; API-first structured parsing. # Actor input Schema ## `specialty` (type: `string`): What to search for, e.g. 'Cardiologist', 'Dermatologist', 'Family Medicine', 'Diabetes'. Used with the Locations below. ## `locations` (type: `array`): One or more locations, e.g. 'Miami, FL', 'New York, NY', 'Austin, TX'. The actor searches the specialty in each location. ## `startUrls` (type: `array`): Paste Healthgrades search URLs directly (e.g. https://www.healthgrades.com/usearch?what=Cardiologist\&where=Miami,+FL). When provided, the specialty/locations fields are ignored. ## `maxItems` (type: `integer`): Maximum number of providers to scrape. Use 0 for no limit. ## `maxPagesPerSearch` (type: `integer`): Pagination cap per specialty+location search (~20 providers per page). ## `proxyConfiguration` (type: `object`): Healthgrades is US-only and blocks datacenter IPs โ€” US RESIDENTIAL proxies are REQUIRED. Keep this default. ## `maxConcurrency` (type: `integer`): Maximum parallel requests. ## Actor input object example ```json { "specialty": "Cardiologist", "locations": [ "Miami, FL" ], "maxItems": 200, "maxPagesPerSearch": 20, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" }, "maxConcurrency": 3 } ``` # Actor output Schema ## `providers` (type: `string`): All provider records collected during the run. ## `runUrl` (type: `string`): Open this run in the Apify Console. # 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 = { "specialty": "Cardiologist", "locations": [ "Miami, FL" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } }; // Run the Actor and wait for it to finish const run = await client.actor("haketa/healthgrades-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 = { "specialty": "Cardiologist", "locations": ["Miami, FL"], "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US", }, } # Run the Actor and wait for it to finish run = client.actor("haketa/healthgrades-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 '{ "specialty": "Cardiologist", "locations": [ "Miami, FL" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } }' | apify call haketa/healthgrades-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=haketa/healthgrades-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Healthgrades Scraper - Doctors, Ratings & Reviews", "description": "Healthgrades scraper & API: find US doctors by specialty & location and export name, NPI, specialty, patient rating & review count, phone, practice address, hospital affiliations and accepting-new-patients. Healthcare provider data and medical lead generation โ€” fast, no login.", "version": "0.1", "x-build-id": "S6O4nfMOcQjmEgnB0" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/haketa~healthgrades-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-haketa-healthgrades-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/haketa~healthgrades-scraper/runs": { "post": { "operationId": "runs-sync-haketa-healthgrades-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/haketa~healthgrades-scraper/run-sync": { "post": { "operationId": "run-sync-haketa-healthgrades-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": { "specialty": { "title": "Specialty / condition / name", "type": "string", "description": "What to search for, e.g. 'Cardiologist', 'Dermatologist', 'Family Medicine', 'Diabetes'. Used with the Locations below." }, "locations": { "title": "Locations (City, ST)", "type": "array", "description": "One or more locations, e.g. 'Miami, FL', 'New York, NY', 'Austin, TX'. The actor searches the specialty in each location.", "items": { "type": "string" } }, "startUrls": { "title": "Search URLs (advanced)", "type": "array", "description": "Paste Healthgrades search URLs directly (e.g. https://www.healthgrades.com/usearch?what=Cardiologist&where=Miami,+FL). When provided, the specialty/locations fields are ignored.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxItems": { "title": "Max providers", "minimum": 0, "type": "integer", "description": "Maximum number of providers to scrape. Use 0 for no limit.", "default": 200 }, "maxPagesPerSearch": { "title": "Max pages per search", "minimum": 1, "type": "integer", "description": "Pagination cap per specialty+location search (~20 providers per page).", "default": 20 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Healthgrades is US-only and blocks datacenter IPs โ€” US RESIDENTIAL proxies are REQUIRED. Keep this default.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Maximum parallel requests.", "default": 3 } } }, "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 } } } } } } } } } } ```