> 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.

# Search providers near a location

GET https://staging.cail.health/v1/search/proximity

Returns ranked candidate providers near the supplied coordinates. Results are ordered by great-circle distance from the search origin, filtered to the supplied service type when present, and capped at the requested radius. The response carries operational signals such as open hours, recent wait times, and a coarse data-quality tier, so a member client can render an actionable list without a second round-trip. Distances are reported in metres; coordinates use WGS84. Anonymous: no authentication is required. Rate limits apply per source IP; clients SHOULD render a friendly message on a 429 response and back off. This endpoint is not a clinical triage tool; it is access infrastructure for discovering providers.

Reference: https://docs.cail.health/api-references/api-reference/find-care/proximity

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: cail-api
  version: 1.0.0
paths:
  /v1/search/proximity:
    get:
      operationId: proximity
      summary: Search providers near a location
      description: >-
        Returns ranked candidate providers near the supplied coordinates.
        Results are ordered by great-circle distance from the search origin,
        filtered to the supplied service type when present, and capped at the
        requested radius. The response carries operational signals such as open
        hours, recent wait times, and a coarse data-quality tier, so a member
        client can render an actionable list without a second round-trip.
        Distances are reported in metres; coordinates use WGS84. Anonymous: no
        authentication is required. Rate limits apply per source IP; clients
        SHOULD render a friendly message on a 429 response and back off. This
        endpoint is not a clinical triage tool; it is access infrastructure for
        discovering providers.
      tags:
        - subpackage_findCare
      parameters:
        - name: latitude
          in: query
          description: >-
            Search centre latitude (WGS84). Combine with longitude to define the
            centre of the search radius.
          required: true
          schema:
            type: number
            format: double
        - name: longitude
          in: query
          description: Search centre longitude (WGS84).
          required: true
          schema:
            type: number
            format: double
        - name: serviceTypeCode
          in: query
          description: >-
            Restrict results to a specific service type. Accepts the snake_case
            key `service_type_code` from member clients.
          required: false
          schema:
            type: string
        - name: radiusKm
          in: query
          description: >-
            Search radius in kilometres. Defaults to 10. Maximum 1000. Accepts
            the snake_case key `radius_km`.
          required: false
          schema:
            type: number
            format: double
        - name: limit
          in: query
          description: Maximum number of results to return. Defaults to 10. Maximum 1000.
          required: false
          schema:
            type: number
            format: double
      responses:
        '200':
          description: A ranked page of nearby providers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProximitySearchResponse'
servers:
  - url: https://staging.cail.health
    description: https://staging.cail.health
components:
  schemas:
    ProviderAddressInfo:
      type: object
      properties:
        line:
          type: array
          items:
            type: string
          description: Address lines as printed.
        city:
          type: string
          description: Town or city.
        district:
          type: string
          description: Administrative district.
        postalCode:
          type: string
          description: Postal code.
      required:
        - line
        - city
        - district
        - postalCode
      title: ProviderAddressInfo
    ProviderSearchResultPhone:
      type: object
      properties: {}
      description: Contact phone number for the provider location, if published.
      title: ProviderSearchResultPhone
    ProviderSearchResultWebsite:
      type: object
      properties: {}
      description: Public website for the provider location, if published.
      title: ProviderSearchResultWebsite
    ProviderCoordinatesInfo:
      type: object
      properties:
        latitude:
          type: number
          format: double
          description: WGS84 latitude.
        longitude:
          type: number
          format: double
          description: WGS84 longitude.
      required:
        - latitude
        - longitude
      title: ProviderCoordinatesInfo
    ProviderSearchResultDistanceMetres:
      type: object
      properties: {}
      description: >-
        Great-circle distance from the search origin in metres. Always populated
        for proximity search.
      title: ProviderSearchResultDistanceMetres
    ProviderSearchResultIsOpenNow:
      type: object
      properties: {}
      description: >-
        True when the location is open right now. Null when hours data is
        unavailable.
      title: ProviderSearchResultIsOpenNow
    ProviderWaitTimeInfoMedianMinutes:
      type: object
      properties: {}
      description: >-
        Median wait time in minutes across recent reports. Null when no reports
        are available.
      title: ProviderWaitTimeInfoMedianMinutes
    ProviderWaitTimeInfoNewestReportAt:
      type: object
      properties: {}
      description: ISO 8601 timestamp of the most recent contributing report.
      title: ProviderWaitTimeInfoNewestReportAt
    ProviderWaitTimeInfo:
      type: object
      properties:
        medianMinutes:
          oneOf:
            - $ref: '#/components/schemas/ProviderWaitTimeInfoMedianMinutes'
            - type: 'null'
          description: >-
            Median wait time in minutes across recent reports. Null when no
            reports are available.
        reportCount:
          type: number
          format: double
          description: Number of reports backing the median.
        isStale:
          type: boolean
          description: >-
            True when the most recent report is older than the freshness window.
            Stale data SHOULD be rendered with a "last updated" hint.
        newestReportAt:
          oneOf:
            - $ref: '#/components/schemas/ProviderWaitTimeInfoNewestReportAt'
            - type: 'null'
          description: ISO 8601 timestamp of the most recent contributing report.
      required:
        - medianMinutes
        - reportCount
        - isStale
        - newestReportAt
      title: ProviderWaitTimeInfo
    ProviderSearchResultAvailabilityStatus:
      type: string
      enum:
        - open_now
        - opens_later
        - closed_today
        - unknown_hours
      description: Synthesised availability, derived from open hours and schedule data.
      title: ProviderSearchResultAvailabilityStatus
    ProviderSearchResultAction:
      oneOf:
        - type: object
          properties:
            kind:
              type: string
              enum:
                - call
              description: 'Discriminator value: call'
            phone:
              type: string
              description: E.164 or locally-formatted phone number to call.
          required:
            - kind
            - phone
          description: call variant
        - type: object
          properties:
            kind:
              type: string
              enum:
                - visit_website
              description: 'Discriminator value: visit_website'
            url:
              type: string
              description: Absolute URL to open as the primary engagement action.
          required:
            - kind
            - url
          description: visit_website variant
        - type: object
          properties:
            kind:
              type: string
              enum:
                - navigate
              description: 'Discriminator value: navigate'
          required:
            - kind
          description: navigate variant
        - type: object
          properties:
            kind:
              type: string
              enum:
                - none
              description: 'Discriminator value: none'
          required:
            - kind
          description: none variant
      discriminator:
        propertyName: kind
      description: >-
        Recommended primary engagement action. Single-valued by precedence (call
        > visit_website > navigate > none).
      title: ProviderSearchResultAction
    ProviderConfidenceInfoLevel:
      type: string
      enum:
        - high
        - medium
        - low
        - unknown
      description: >-
        Coarse data-quality tier. Render this prominently when guiding member
        decisions.
      title: ProviderConfidenceInfoLevel
    ProviderConfidenceInfo:
      type: object
      properties:
        level:
          $ref: '#/components/schemas/ProviderConfidenceInfoLevel'
          description: >-
            Coarse data-quality tier. Render this prominently when guiding
            member decisions.
        reasonCodes:
          type: array
          items:
            type: string
          description: >-
            Machine-readable reason codes explaining the confidence level.
            Sorted and deduplicated. Stable for analytics.
      required:
        - level
        - reasonCodes
      title: ProviderConfidenceInfo
    ProviderSearchResult:
      type: object
      properties:
        providerId:
          type: string
          description: Stable provider identifier.
        name:
          type: string
          description: Display name for the provider.
        address:
          $ref: '#/components/schemas/ProviderAddressInfo'
        phone:
          oneOf:
            - $ref: '#/components/schemas/ProviderSearchResultPhone'
            - type: 'null'
          description: Contact phone number for the provider location, if published.
        website:
          oneOf:
            - $ref: '#/components/schemas/ProviderSearchResultWebsite'
            - type: 'null'
          description: Public website for the provider location, if published.
        coordinates:
          $ref: '#/components/schemas/ProviderCoordinatesInfo'
        distanceMetres:
          oneOf:
            - $ref: '#/components/schemas/ProviderSearchResultDistanceMetres'
            - type: 'null'
          description: >-
            Great-circle distance from the search origin in metres. Always
            populated for proximity search.
        serviceTypes:
          type: array
          items:
            type: string
          description: Service-type codes offered at this location.
        isOpenNow:
          oneOf:
            - $ref: '#/components/schemas/ProviderSearchResultIsOpenNow'
            - type: 'null'
          description: >-
            True when the location is open right now. Null when hours data is
            unavailable.
        waitTime:
          oneOf:
            - $ref: '#/components/schemas/ProviderWaitTimeInfo'
            - type: 'null'
          description: >-
            Wait-time data for the location. Null when no recent reports are
            available.
        availabilityStatus:
          $ref: '#/components/schemas/ProviderSearchResultAvailabilityStatus'
          description: Synthesised availability, derived from open hours and schedule data.
        routingReasonCodes:
          type: array
          items:
            type: string
          description: Operational reason codes describing why this result is actionable.
        action:
          $ref: '#/components/schemas/ProviderSearchResultAction'
          description: >-
            Recommended primary engagement action. Single-valued by precedence
            (call > visit_website > navigate > none).
        confidence:
          $ref: '#/components/schemas/ProviderConfidenceInfo'
      required:
        - providerId
        - name
        - address
        - phone
        - website
        - coordinates
        - distanceMetres
        - serviceTypes
        - isOpenNow
        - availabilityStatus
        - routingReasonCodes
        - action
        - confidence
      title: ProviderSearchResult
    OffsetPageInfo:
      type: object
      properties:
        total:
          type: number
          format: double
          description: Total number of items across all pages.
        limit:
          type: number
          format: double
          description: Echoes the requested page size for client convenience.
        offset:
          type: number
          format: double
          description: Echoes the requested zero-based offset.
        hasMore:
          type: boolean
          description: True when more results exist after this page.
      required:
        - total
        - limit
        - offset
        - hasMore
      title: OffsetPageInfo
    ResponseMeta:
      type: object
      properties:
        requestId:
          type: string
          description: >-
            Opaque request identifier echoed for support traceability. Matches
            the x-request-id response header.
        timestamp:
          type: string
          description: ISO 8601 timestamp at which the server completed the request.
        durationMs:
          type: number
          format: double
          description: Server-measured request duration in milliseconds.
      required:
        - requestId
        - timestamp
        - durationMs
      title: ResponseMeta
    ProximitySearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProviderSearchResult'
          description: >-
            Ranked candidate providers, ordered by distance from the search
            origin.
        pagination:
          $ref: '#/components/schemas/OffsetPageInfo'
          description: Pagination metadata for stepping forward by offset.
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - data
        - pagination
        - meta
      title: ProximitySearchResponse

```

## Examples



**Response**

```json
{
  "data": [
    {
      "providerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "St Thomas' Hospital",
      "address": {
        "line": [
          "Westminster Bridge Road"
        ],
        "city": "London",
        "district": "Greater London",
        "postalCode": "SE1 7EH"
      },
      "phone": "+442071887188",
      "website": "https://example.nhs.uk",
      "coordinates": {
        "latitude": 51.4988,
        "longitude": -0.1187
      },
      "distanceMetres": 1820,
      "serviceTypes": [
        "50849002"
      ],
      "isOpenNow": true,
      "availabilityStatus": "open_now",
      "routingReasonCodes": [
        "match.service_type",
        "match.proximity",
        "match.open_now"
      ],
      "action": {
        "kind": "call",
        "phone": "+442071887188"
      },
      "confidence": {
        "level": "high",
        "reasonCodes": [
          "data.has_hours",
          "data.recent_wait_time",
          "data.has_contact_method"
        ]
      },
      "waitTime": {
        "medianMinutes": 18,
        "reportCount": 12,
        "isStale": false,
        "newestReportAt": "2026-05-12T14:21:00.000Z"
      }
    }
  ],
  "pagination": {
    "total": 7,
    "limit": 10,
    "offset": 0,
    "hasMore": false
  },
  "meta": {
    "requestId": "4a3b2c1d-5e6f-4890-9abc-def0fedcba98",
    "timestamp": "2026-05-13T14:21:00.000Z",
    "durationMs": 42
  }
}
```

**SDK Code**

```python Two open emergency departments within 5 km
import requests

url = "https://staging.cail.health/v1/search/proximity"

querystring = {"latitude":"51.5","longitude":"-0.128"}

response = requests.get(url, params=querystring)

print(response.json())
```

```javascript Two open emergency departments within 5 km
const url = 'https://staging.cail.health/v1/search/proximity?latitude=51.5&longitude=-0.128';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Two open emergency departments within 5 km
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://staging.cail.health/v1/search/proximity?latitude=51.5&longitude=-0.128"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Two open emergency departments within 5 km
require 'uri'
require 'net/http'

url = URI("https://staging.cail.health/v1/search/proximity?latitude=51.5&longitude=-0.128")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java Two open emergency departments within 5 km
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://staging.cail.health/v1/search/proximity?latitude=51.5&longitude=-0.128")
  .asString();
```

```php Two open emergency departments within 5 km
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://staging.cail.health/v1/search/proximity?latitude=51.5&longitude=-0.128');

echo $response->getBody();
```

```csharp Two open emergency departments within 5 km
using RestSharp;

var client = new RestClient("https://staging.cail.health/v1/search/proximity?latitude=51.5&longitude=-0.128");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift Two open emergency departments within 5 km
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://staging.cail.health/v1/search/proximity?latitude=51.5&longitude=-0.128")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```