Find providers near a member

This guide shows how to return a ranked list of providers near a member, optionally narrowed to a service type. Use it when a member needs to see care options around their current location.

The request is a member-path call. Authenticate as a member client first; see Authentication.

Search around a location

Call GET /v1/search/proximity with the centre of the search. latitude and longitude are required and use WGS84 coordinates.

curl --get "$CAIL_API_BASE_URL/v1/search/proximity" \
  --data-urlencode "latitude=51.5074" \
  --data-urlencode "longitude=-0.1278" \
  --header "Authorization: Bearer $CAIL_TOKEN"

Narrow the search

Three optional parameters refine the result:

For example, to find one service type within 5 kilometres:

curl --get "$CAIL_API_BASE_URL/v1/search/proximity" \
  --data-urlencode "latitude=51.5074" \
  --data-urlencode "longitude=-0.1278" \
  --data-urlencode "serviceTypeCode=50849002" \
  --data-urlencode "radiusKm=5" \
  --header "Authorization: Bearer $CAIL_TOKEN"

Read the result

The response is a ranked page of providers:

{
  "data": [
    {
      "providerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "St Thomas' Hospital",
      "distanceMetres": 1820,
      "serviceTypes": ["50849002"],
      "isOpenNow": true,
      "availabilityStatus": "open_now",
      "routingReasonCodes": ["match.service_type", "match.open_now"]
    }
  ],
  "meta": {
    "requestId": "4a3b2c1d-5e6f-4890-9abc-def0fedcba98",
    "timestamp": "2026-05-13T14:21:00.000Z",
    "durationMs": 42
  }
}

Two fields matter most when presenting options to a member:

• availabilityStatus and isOpenNow describe whether the provider can take the member now.
• routingReasonCodes explain why a provider ranked where it did. Surface them so the member understands the recommendation.

Results are ordered by routing fit, which weighs service-type match and current availability alongside distance. Do not re-sort by distanceMetres alone.

Next steps

• To walk the member through a pathway and on to a chosen provider, see Navigate a member to care.
• To check how busy a location is, see Check provider wait times.