> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cail.health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cail.health/_mcp/server.

# 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](/api-reference/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.

```bash
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:

| Parameter         | Effect                                                     |
| ----------------- | ---------------------------------------------------------- |
| `serviceTypeCode` | Restrict results to a single service type.                 |
| `radiusKm`        | Search radius in kilometres. Defaults to 10, maximum 1000. |
| `limit`           | Maximum number of results. Defaults to 10.                 |

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

```bash
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:

```json
{
  "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](/guides/navigate-a-member-to-care).
* To check how busy a location is, see [Check provider wait times](/guides/check-provider-wait-times).