---
title: "Booked appointments nearest a contact's address"
description: "Returns up to `limit` appointments within `radius_miles` of the given contact, one row per neighbouring contact, ranked by straight-line distance. `est_drive_minutes` is an ESTIMATE derived from that straight line at an assumed 30mph — it is NOT a routed drive time and must be labelled as an estimate wherever it is displayed. Gated by the NEARBY_APPOINTMENTS workspace feature flag (404 when off).\n"
---

> Documentation Index
> Fetch the complete documentation index at: https://developer.channelautomations.com/llms.txt
> Use this file to discover all available pages before exploring further.

Path: Channel Automation API › Contacts

`GET /api/nearby-appointments`

Returns up to `limit` appointments within `radius_miles` of the given contact, one row per neighbouring contact, ranked by straight-line distance. `est_drive_minutes` is an ESTIMATE derived from that straight line at an assumed 30mph — it is NOT a routed drive time and must be labelled as an estimate wherever it is displayed. Gated by the NEARBY_APPOINTMENTS workspace feature flag (404 when off).

## Query parameters

- `contact_id` (`get/api/nearby-appointments.query.contact_id`; string, required) — The contact to search around.
  - format `uuid`
- `workspace_id` (`get/api/nearby-appointments.query.workspace_id`; string, optional) — Workspace ID. May also come from auth or the x-workspace-id header.
- `radius_miles` (`get/api/nearby-appointments.query.radius_miles`; number, optional)
  - min 1; max 500; default `50`
- `limit` (`get/api/nearby-appointments.query.limit`; integer, optional)
  - min 1; max 50; default `10`

## Code samples

### cURL

```bash
curl --request GET \
  --url 'https://api.channelautomation.com/api/nearby-appointments?contact_id=497f6eca-6276-4993-bfeb-53cbbbba6f08'
```

### TypeScript

```typescript
const url = 'https://api.channelautomation.com/api/nearby-appointments?contact_id=497f6eca-6276-4993-bfeb-53cbbbba6f08';
const options = {method: 'GET'};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.channelautomation.com/api/nearby-appointments?contact_id=497f6eca-6276-4993-bfeb-53cbbbba6f08"

response = requests.get(url)

print(response.text)
```

## Responses

### 200

Nearby appointments, plus a `state` naming why the list may be empty: `ok` (rows returned), `no_neighbors` (contact geocoded, nothing in radius), `not_geocoded` (no coordinates yet), or `no_address` (contact has no usable address to geocode).

### 400

Missing workspace_id or contact_id.

### 404

Feature flag disabled, or contact not found in this workspace.


Source: https://developer.channelautomations.com/api/get-api-nearby-appointments/index.md