> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neariq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Places

> Session-authenticated location search endpoints used during business setup, competitor add, and map workflows.

Places endpoints are dashboard endpoints. They use the signed-in app session, not `X-NearIQ-Key`, and they are rate limited because they can call external location data providers. Reads are bounded to the fields NearIQ needs for setup and competitor discovery.

<Note>
  These endpoints are not public v1 API-key endpoints. They require an authenticated dashboard session and may return `401` when the session is missing.
</Note>

## POST /api/places/autocomplete

Returns short place suggestions for typeahead inputs. The app applies an IP rate limit and a per-user `places_search` daily safeguard.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.neariq.io/api/places/autocomplete" \
    -H "Content-Type: application/json" \
    -H "Cookie: <dashboard session cookie>" \
    -d '{ "input": "Aster Grove Fit" }'
  ```
</RequestExample>

<ParamField body="input" type="string" required>
  Search text. At least 2 characters.
</ParamField>

```json theme={null}
{
  "suggestions": [
    {
      "placeId": "ChIJ123...",
      "text": "Aster Grove Fitness, Austin, TX",
      "mainText": "Aster Grove Fitness",
      "secondaryText": "Austin, TX"
    }
  ]
}
```

## GET /api/places/search

Searches for businesses by text query and returns compact listing candidates.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.neariq.io/api/places/search?q=coffee%20shop%20austin" \
    -H "Cookie: <dashboard session cookie>"
  ```
</RequestExample>

<ParamField query="q" type="string" required>
  Business or category query. At least 2 characters.
</ParamField>

```json theme={null}
{
  "results": [
    {
      "place_id": "ChIJ123...",
      "name": "Aster Grove Coffee",
      "address": "100 Market St, Austin, TX",
      "rating": 4.8,
      "review_count": 188,
      "types": ["cafe", "food"],
      "website_url": "https://example.com"
    }
  ]
}
```

## POST /api/places/nearby

Finds nearby business candidates around an address. This powers competitor discovery and setup suggestions.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.neariq.io/api/places/nearby" \
    -H "Content-Type: application/json" \
    -H "Cookie: <dashboard session cookie>" \
    -d '{
      "address": "100 Market St, Austin, TX",
      "category": "Fitness",
      "subcategory": "Pilates studio",
      "radius_meters": 3000,
      "max_results": 8
    }'
  ```
</RequestExample>

<ParamField body="address" type="string" required>
  Address or area to search around.
</ParamField>

<ParamField body="category" type="string" required>
  Business category used to choose relevant nearby candidates.
</ParamField>

<ParamField body="subcategory" type="string">
  Optional more specific service or niche.
</ParamField>

<ParamField body="radius_meters" type="number">
  Search radius in meters. The API schema bounds this value.
</ParamField>

<ParamField body="max_results" type="number">
  Maximum number of returned candidates. The API schema bounds this value.
</ParamField>

```json theme={null}
{
  "results": [
    {
      "place_id": "ChIJ456...",
      "name": "Apex Grove Strength",
      "address": "210 Example Ave, Austin, TX",
      "rating": 4.7,
      "review_count": 312,
      "types": ["gym", "health"]
    }
  ],
  "center": {
    "latitude": 30.2672,
    "longitude": -97.7431
  }
}
```

## POST /api/places/reverse-geocode

Converts a map coordinate into a best-effort address label.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.neariq.io/api/places/reverse-geocode" \
    -H "Content-Type: application/json" \
    -H "Cookie: <dashboard session cookie>" \
    -d '{ "lat": 30.2672, "lng": -97.7431 }'
  ```
</RequestExample>

<ParamField body="lat" type="number" required>
  Latitude.
</ParamField>

<ParamField body="lng" type="number" required>
  Longitude.
</ParamField>

```json theme={null}
{
  "address": "100 Market St, Austin, TX"
}
```

## Errors

| Status | Meaning                                        |
| ------ | ---------------------------------------------- |
| `400`  | Invalid request body or query                  |
| `401`  | Missing dashboard session                      |
| `429`  | IP or `places_search` daily safeguard exceeded |
| `500`  | Location search is not configured              |
| `502`  | External location lookup failed                |