Skip to main content
GET
Find best-fit practitioners nearby
Returns nearby practitioners, ranked by how good a fit they are for a given referral target. Each result pairs a practitioner with one of their practice locations:
  • Practitioner: name, NPI number, and referralScopeMatch, our estimate of whether their billing history fits the referral target
  • Location: address and coordinates, staleAffiliationRisk, our estimate of whether they are still seeing patients there, and bookability, our estimate of whether an appointment can be booked there
  • Distance: straight-line (not driving) miles from the coordinates you searched
  • Score: from 0 to 100, how good a fit this practitioner, at this location, is for the referral you searched; higher is better

Ranking

score combines fit (referralScopeMatch), distance, and whether an appointment can be booked at the location (bookability). Ties are broken consistently, so repeating a search returns the same order. Results are not filtered by fit: poor fits are still returned, ranked below better ones. Filter on practitioner.referralScopeMatch if you only want likely matches. Scores are on a fixed scale, so they can be compared across searches that report the same servedModels. When servedModels has no practitionerLocationRisk, scores are computed without a bookability adjustment and locations omit both staleAffiliationRisk and bookability. Locations without a bookability label, such as those of practitioners the model does not cover, receive no adjustment.

Pagination

When more results are available, the response includes nextCursor. To get the next page, repeat the request with cursor set to that value. Stop when nextCursor is absent. A cursor is only valid for the search that produced it: changing any other parameter returns a 400.
A non-match (unlikely_match or very_unlikely_match) means a routine referral target does not fit the provider’s observed billing. It does not mean the service is outside their scope of practice or that they are unqualified; it reflects what they routinely bill, not what they are licensed or trained to do.
Geocoding data is provided in part by OpenStreetMap. © OpenStreetMap contributors, available under the Open Database License (ODbL). Additional data is derived from the U.S. Census Bureau TIGER/Line® Shapefiles (public domain), from other public sources, and from commercial sources, such as Geocodio.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your API token.

Query Parameters

referralTargetId
string<uuid>
required

The referral target to rank practitioners against, from GET /specializations/{id}/targets. Target ids change between model versions, so look them up rather than storing them.

latitude
number<double>
required

Latitude of the point to search around, in WGS84 decimal degrees.

Required range: -90 <= x <= 90
longitude
number<double>
required

Longitude of the point to search around, in WGS84 decimal degrees.

Required range: -180 <= x <= 180
radiusMiles
integer
required

How far from the coordinates to search, in straight-line miles.

Required range: 1 <= x <= 25
pageSize
integer
default:25

How many results to return per page.

Required range: 1 <= x <= 100
cursor
string

The nextCursor from the previous page. Send it with the same parameters as the original request.

Response

Expected response to a valid request

practitionerLocations
object[]
required

Results, ordered best-first by score. Empty when we have no estimate of fit for any practitioner within the radius.

servedModels
object
required

The version of each model whose output appears in this response.

nextCursor
string

Opaque cursor for the next page, to be passed back as the cursor query parameter. Absent when there are no additional results.