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:

1
{
2
  "data": [
3
    {
4
      "providerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
5
      "name": "St Thomas' Hospital",
6
      "distanceMetres": 1820,
7
      "serviceTypes": ["50849002"],
8
      "isOpenNow": true,
9
      "availabilityStatus": "open_now",
10
      "routingReasonCodes": ["match.service_type", "match.open_now"]
11
    }
12
  ],
13
  "meta": {
14
    "requestId": "4a3b2c1d-5e6f-4890-9abc-def0fedcba98",
15
    "timestamp": "2026-05-13T14:21:00.000Z",
16
    "durationMs": 42
17
  }
18
}

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.