---
title: "Find practices by location"
method: POST
path: "/intent/locations/search"
tags: ["intent"]
---

# Find practices by location

`POST /intent/locations/search`

## Request

- Base URL: `https://nexhealth.info`
- URL: `https://nexhealth.info/intent/locations/search`
- Auth: API key in header `Authorization`

Returns granted practice locations near a point, ranked by distance.
Soft failures return `{ ok: false, reason:, message: }` rather than an HTTP error.

### Example request

```
curl -X POST https://nexhealth.info/intent/locations/search \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{ "location": { "zip": "98101" }, "radius_miles": 15 }'
```

### Example success response

```json
{ "ok": true,
  "locations": [
    { "location_id": 42, "name": "Main St Dental",
      "address": "1 Main St, Seattle, WA, 98101", "distance_miles": 1.2 }
  ] }
```

### Reason catalog (branch on `reason` when `ok` is false)

| `reason` | Meaning | Recommended agent recovery |
|----------|---------|----------------------------|
| `location_required` | No location input supplied. | Ask the user for a ZIP, city, or coordinates and re-call. |
| `location_not_understood` | The input could not be resolved to coordinates. | Ask for a 5-digit US ZIP or lat/lng and re-call. |
| `no_locations_in_radius` | No granted practices within the radius. | Widen `radius_miles` or ask for a different area. |

## Request body

- PostIntentLocationsSearch: Find practices by location
  - `location` object
    - `text` string: City, neighbourhood, or ZIP to search near (5-digit ZIP only).
    - `zip` string: US ZIP code.
    - `lat` number, float: WGS-84 latitude; supply with lng.
    - `lng` number, float: WGS-84 longitude; supply with lat.
  - `radius_miles` number, float: Search radius in miles (default 20, must be positive).

## Response `200`

Find practices by location

---

[API](https://skmtc.dev/nexhealth/apis/scheduling-intent-beta.md) - [All operations](https://skmtc.dev/nexhealth/apis/scheduling-intent-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/nexhealth/apis/scheduling-intent-beta/revisions/f69a30d3cf2e?raw)