Docs menu
Healthgrades API endpoint
Healthgrades physician search API
Returns one page of Healthgrades provider search results for a specialty, condition, procedure, or provider name near a location, with each provider's NPI, specialty, office, aggregate patient rating, accepted insurers, and profile URL, plus the filters available for the search. Closed-set filters accept the listed values; insurance, insurance_plan, language, clinical_focus, affiliated_hospital, and specialty accept values returned in the filters for the same query/where. List filters take comma-separated values. Requests use US egress because Healthgrades restricts content by region. Patient review text is not returned.
GETapiKey3 credits/requestHealthgradeshealthgrades.physicianSearchResponseDoc
Healthgrades/healthgrades/physicians/searchEndpoint facts
- Method
- GET
- API path
- /healthgrades/physicians/search
- Auth
- apiKey
- Credits
- 3 credits/request
- Charged on
- Successful 2xx responses only
- Platform
- Healthgrades
- Response schema
- #/definitions/healthgrades.physicianSearchResponseDoc
How this endpoint behaves
Query parameters:
query(required): specialty, condition, procedure, or provider name; maximum 120 characters.where(optional): city and state (for exampleBoston, MA) or ZIP code; maximum 120 characters.page(optional): result page,1-500; 20 results per page. Default1.sort(optional):bestmatch(default),distance, orratings.gender(optional):ForM.distance(optional): search radius in miles:1,5,10,25,50,100, ornational. Healthgrades widens the radius automatically when a filtered search would be empty.age(optional, comma-separated):*-40,41-50,51-60,61-70,71-*.availability(optional, comma-separated):today,tomorrow,nextTwoWeeks,online,acceptsNewPatients,telehealth.rating(optional):5(5 stars) or4,3,2,1(that many stars and higher).insurance(optional, comma-separated): insurer codes from theinsurancefilter of/api/v1/healthgrades/physicians/filters.insurance_plan(optional, comma-separated): plan IDs from an insurer'splans; requiresinsurance.language(optional, comma-separated): language codes from thelanguagefilter.clinical_focus(optional, comma-separated): codes from theclinical_focusfilter.affiliated_hospital(optional, comma-separated): codes from theaffiliated_hospitalfilter.specialty(optional, comma-separated): practicing-specialty codes from thespecialtyfilter (for exampleps1027, Cosmetic Dentistry); several codes match any of them.affirming_care(optional):trueto return only providers marked LGBTQ+ affirming.
Invalid closed-set values return 400. Insurer, language, clinical-focus, hospital, and specialty values depend on the query and location, so read them from the filters endpoint (or this response's filters) for the same query/where.
Each result includes the provider name, NPI, Healthgrades ID, profile URL, specialty, gender, age, years of experience, aggregate patient rating (score and count), new-patient and telehealth flags, distance, office address and phone, accepted insurers, and affiliated hospital codes. Patient review text is not returned. filters lists the filter groups for this search; each group's param names the query parameter that accepts its values. Requests use US egress because Healthgrades restricts content by region.
Live monitoring
- Monitored request
- GET /healthgrades/physicians/search?query=Cardiology&where=Boston%2C+MA
- Checks passed, 7 days to 14 Oct 2026
- 100%
- Median response time
- 4.54 s
Sampled response
- Request, 14 Oct 2026
- GET /healthgrades/physicians/search?query=Cardiology&where=Boston%2C+MA
- Items in physicians
- 20
- Fields filled in every checked item
- 17
- Fields empty in some or all items
- 2
| Field | Filled in, of 20 checked | Values in the sample |
|---|---|---|
| name | 20 | |
| id | 20 | |
| npi | 20 | 1,003,852,526 to 1,962,454,298, median 1,427,029,263 |
| profile_url | 20 | healthgrades.com |
| specialty | 20 | |
| specialist_descriptions | 20 | median 2 entries |
| gender | 20 | |
| age | 20 | 43 to 79, median 56 |
| years_experience | 17 | 10 to 40, median 25 |
| rating | 20 | |
| accepts_new_patients | 20 | true in 6 of 20 |
| telehealth_available | 20 | true in 14 of 20 |
| telehealth_only | 20 | true in 0 of 20 |
| distance_miles | 20 | 0.2 to 0.8, median 0.5 |
| about | 20 | median 134 characters |
| office | 20 | |
| insurers | 20 | median 12 entries |
| affiliated_hospital_ids | 20 | |
| image_url | 4 | photos.healthgrades.com |
Request parameters
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| query | string | Yes | Specialty, condition, procedure, or provider name | Cardiology | |
| where | string | No | City and state, or ZIP code | Boston, MA | |
| page | integer | No | Result page (1-500, 20 results per page) | ||
| sort | string | No | Result order Allowed values: bestmatch, distance, ratings. | ||
| gender | string | No | Provider gender Allowed values: F, M. | ||
| distance | string | No | Search radius in miles Allowed values: 1, 5, 10, 25, 50, 100, national. | ||
| age | string | No | Comma-separated provider age bands Allowed values: *-40, 41-50, 51-60, 61-70, 71-*. | ||
| availability | string | No | Comma-separated availability filters Allowed values: today, tomorrow, nextTwoWeeks, online, acceptsNewPatients, telehealth. | ||
| rating | string | No | Minimum patient-satisfaction stars (5 means exactly 5) Allowed values: 1, 2, 3, 4, 5. | ||
| insurance | string | No | Comma-separated insurer codes from the insurance filter | HPY00006F7 | |
| insurance_plan | string | No | Comma-separated plan IDs from an insurer's plans (requires insurance) | HPT0000407 | |
| language | string | No | Comma-separated language codes from the language filter | spanish | |
| clinical_focus | string | No | Comma-separated clinical focus codes from the clinical_focus filter | ||
| affiliated_hospital | string | No | Comma-separated hospital codes from the affiliated_hospital filter | ||
| specialty | string | No | Comma-separated practicing-specialty codes from the specialty filter | ps1027 | |
| affirming_care | boolean | No | Only providers marked LGBTQ+ affirming | ||
| x-api-key (header) | string | Yes | API key required |
cURL example
curl -X GET "https://api.crawlora.net/api/v1/healthgrades/physicians/search?query=Cardiology&page=1&sort=bestmatch&gender=F&distance=1&age=*-40&availability=today&rating=1&language=en&affirming_care=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
Example JSON response
{
"code": 0,
"message": "success",
"data": {
"query": "Cardiology",
"where": "Boston, MA",
"page": 1,
"page_size": 20,
"total_results": 350,
"total_pages": 18,
"sort": "bestmatch",
"sorts": [
{
"key": "bestmatch",
"label": "Most Relevant"
},
{
"key": "distance",
"label": "Closest"
},
{
"key": "ratings",
"label": "Highest Rated"
}
],
"physicians": [
{
"name": "Dr. Lana Tsao, MD",
"id": "2QGW4",
"npi": "1467555466",
"profile_url": "https://www.healthgrades.com/physician/dr-lana-tsao-2qgw4",
"specialty": "Cardiology",
"gender": "F",
"age": 62,
"years_experience": 35,
"rating": {
"score": 4.2,
"count": 10
},
"accepts_new_patients": false,
"telehealth_available": false,
"telehealth_only": false,
"distance_miles": 0.5,
"office": {
"name": "Massachusetts General Hospital",
"street": "55 Fruit St",
"city": "Boston",
"state": "MA",
"postal_code": "02114",
"phone": "(617) 643-6148"
},
"insurers": [
"Aetna",
"Cigna"
]
}
],
"filters": [
{
"param": "gender",
"label": "Gender",
"values": [
{
"value": "F",
"label": "Female",
"count": 120
},
{
"value": "M",
"label": "Male",
"count": 230
}
]
}
]
}
}Request schema
No body schema
Response schema
#/definitions/healthgrades.physicianSearchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| data | healthgrades.PhysicianSearchResponse | No | ||||
| data.filters | array | No | PhysicianFilterGroup record, 10 fields: label, param, values. Described under Healthgrades facility search API. | |||
| data.page | integer | No | ||||
| data.page_size | integer | No | ||||
| data.physicians | array | No | ||||
| data.physicians[].about | string | No | ||||
| data.physicians[].accepts_new_patients | boolean | No | ||||
| data.physicians[].affiliated_hospital_ids | array | No | ||||
| data.physicians[].age | integer | No | ||||
| data.physicians[].distance_miles | number | No | ||||
| data.physicians[].gender | string | No | ||||
| data.physicians[].id | string | No | ||||
| data.physicians[].image_url | string | No | ||||
| data.physicians[].insurers | array | No | ||||
| data.physicians[].name | string | No | ||||
| data.physicians[].npi | string | No | ||||
| data.physicians[].office | healthgrades.PhysicianOffice | No | ||||
| data.physicians[].office.city | string | No | ||||
| data.physicians[].office.latitude | number | No | ||||
| data.physicians[].office.longitude | number | No | ||||
| data.physicians[].office.name | string | No | ||||
| data.physicians[].office.phone | string | No | ||||
| data.physicians[].office.postal_code | string | No | ||||
| data.physicians[].office.state | string | No | ||||
| data.physicians[].office.street | string | No | ||||
| data.physicians[].profile_url | string | No | ||||
| data.physicians[].rating | healthgrades.PhysicianRating | No | ||||
| data.physicians[].rating.count | integer | No | ||||
| data.physicians[].rating.score | number | No | ||||
| data.physicians[].specialist_descriptions | array | No | ||||
| data.physicians[].specialty | string | No | ||||
| data.physicians[].telehealth_available | boolean | No | ||||
| data.physicians[].telehealth_only | boolean | No | ||||
| data.physicians[].years_experience | integer | No | ||||
| data.query | string | No | ||||
| data.sort | string | No | ||||
| data.sorts | array | No | ||||
| data.sorts[].key | string | No | ||||
| data.sorts[].label | string | No | ||||
| data.total_pages | integer | No | ||||
| data.total_results | integer | No | ||||
| data.where | string | No |
Failure responses
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Code examples
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/healthgrades/physicians/search?query=Cardiology&page=1&sort=bestmatch&gender=F&distance=1&age=*-40&availability=today&rating=1&language=en&affirming_care=true" \
-H "x-api-key: $CRAWLORA_API_KEY"Shared guides
Related
More Healthgrades endpoint docsHealthgrades Scraper APIHealthgrades search autocomplete API documentationHealthgrades facility search filters API documentationHealthgrades facility search API documentationHealthgrades facility profile API documentationHealthgrades Health A-Z article API documentationHealthgrades Health A-Z articles API documentation