Healthgrades APIhealthgrades.com ↗
Search Healthgrades for doctors by name, specialty, or condition. Retrieve NPI, ratings, education, office locations, and biography for any provider.
What is the Healthgrades API?
The Healthgrades API provides 2 endpoints to search and retrieve U.S. healthcare provider data. Use search_doctors to find practitioners by keyword and location, returning up to 20 results per page with name, specialty, star rating, address, and profile URL. Use get_doctor_details to pull a full profile including NPI, education history, office locations with phone and fax, languages spoken, biography, and gender.
curl -X GET 'https://api.parse.bot/scraper/8a7eb330-37d1-4848-88c4-c922b01dfbe9/search_doctors?keyword=Smith&location=New+York%2C+NY' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace healthgrades-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Healthgrades doctor search and detail lookup."""
from parse_apis.healthgrades_com_api import Healthgrades, DoctorNotFound
client = Healthgrades()
# Search for cardiologists in Chicago, cap total results fetched.
for doc in client.doctors.search(keyword="cardiologist", location="Chicago, IL", limit=5):
print(doc.name, doc.specialty, doc.rating)
# Drill down: take the first matching doctor and fetch full details.
summary = client.doctors.search(keyword="Smith", location="New York, NY", limit=1).first()
if summary is not None:
try:
detail = client.doctors.get(provider_url=summary.profile_url)
except DoctorNotFound:
print("Provider profile no longer available")
else:
print(detail.name, detail.specialty)
print("Accepts new patients:", detail.accepts_new_patients)
# Show office locations from the detailed profile.
if detail.offices:
for office in detail.offices:
print(f" {office.name}: {office.street}, {office.city}, {office.state}")
# Show education history.
if detail.education:
for edu in detail.education:
print(f" {edu.type}: {edu.name} ({edu.completion_year})")
print("exercised: doctors.search / doctors.get")
Search for doctors and healthcare professionals by keyword (name, condition, or specialty) and location (city/state or zip). Returns paginated results with up to 20 providers per page, including name, specialty, rating, address, and profile URL. Use 'page' to paginate through results; the response includes total_count and total_pages for navigation.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (1-based). |
| keywordrequired | string | Search term: doctor name, condition, or specialty (e.g. 'Smith', 'Family Medicine', 'cardiologist'). |
| locationrequired | string | Location to search near: city and state (e.g. 'New York, NY') or zip code. |
{
"type": "object",
"fields": {
"page": "current page number",
"results": "array of provider objects with name, specialty, rating, address, profile_url, and other fields",
"total_count": "total number of matching providers",
"total_pages": "total number of pages available"
},
"sample": {
"data": {
"page": 1,
"results": [
{
"npi": "CRITICAL_PII_REDACTED",
"name": "Dr. John Doe, DMD",
"gender": "M",
"rating": 5,
"address": {
"line1": "123 Main St",
"line2": "Springfield, IL 62704"
},
"specialty": "Dentistry",
"profile_url": "https://www.healthgrades.com/dentist/dr-john-doe-2lhkq",
"provider_id": "2LHKQ",
"specialties": [
"Dentist"
],
"ratings_count": 2,
"distance_miles": 0.1,
"accepts_new_patients": false,
"telehealth_available": false
}
],
"total_count": 405,
"total_pages": 21
},
"status": "success"
}
}About the Healthgrades API
Doctor Search
The search_doctors endpoint accepts a keyword (doctor name, medical condition, or specialty such as "cardiologist" or "Family Medicine") and a location (city/state pair like "Chicago, IL" or a zip code). Results are paginated at up to 20 providers per page; the response includes total_count and total_pages so you can walk through the full result set using the page parameter. Each result object surfaces the provider's name, primary specialty, overall star rating, address, and a profile_url path used as input to the detail endpoint.
Provider Detail Profiles
The get_doctor_details endpoint takes a provider_url path from search results (e.g. /physician/dr-noel-smith-xk82g) and returns a structured profile. Fields include the National Provider Identifier (npi), full credentialed name, gender, star rating out of 5, primary specialty, and biography text. The offices array delivers each practice location with address, phone, and fax. The education array lists each record by type (e.g. medical school, residency), institution name, and completion year. A languages array covers spoken languages beyond English.
Data Coverage and Limitations
Coverage reflects the provider data publicly available on Healthgrades for U.S. practitioners. Patient review counts and individual review text are not returned by the current endpoints — only the aggregate star rating is exposed. Search results are geography-dependent; a location input is required on every search_doctors call, so nationwide bulk enumeration requires iterating across many locations.
The Healthgrades API is a managed, monitored endpoint for healthgrades.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when healthgrades.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official healthgrades.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a physician finder that lets users filter by specialty and zip code using
search_doctors - Populate provider directories with NPI, credentials, and office contact details from
get_doctor_details - Verify a doctor's education history and training type (residency, fellowship) before a referral workflow
- Surface office phone and fax numbers programmatically for appointment scheduling integrations
- Aggregate Healthgrades star ratings across a network of providers for quality benchmarking
- Identify providers who speak specific languages using the
languagesfield for patient matching - Enrich an existing provider database by cross-referencing NPI numbers from profile detail responses
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Healthgrades have an official developer API?+
What does the `get_doctor_details` endpoint return beyond what search results include?+
get_doctor_details adds the provider's NPI, biography text, full education history (institution, type, and completion year), all office locations with phone and fax numbers, spoken languages, and gender. The aggregate star rating is available in both endpoints.Does the search endpoint support nationwide queries without specifying a location?+
location is a required parameter on every search_doctors call. To cover a broad geographic area you need to iterate across multiple cities, states, or zip codes. There is no single-call nationwide search mode in the current API.Are individual patient reviews or review counts returned by either endpoint?+
Can I retrieve a list of available specialties or conditions to use as search keywords?+
search_doctors. You can fork this API on Parse and revise it to add a specialties-listing endpoint if you need a structured vocabulary.