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

# Locations

> Find cities, states, and countries for job-search filters

Autocomplete cities, states, and countries. Each result includes a display
`label` and a structured `value` for use in a job search.

## Authentication and credits

Use `Authorization: Bearer YOUR_API_KEY`. An active API key is required. This
endpoint consumes no credits and works with zero or negative balances.

## Query parameters

<ParamField query="q" type="string" required>
  Search text with at least three non-whitespace characters. The full query may
  contain at most 200 characters. Leading and trailing whitespace is ignored.
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Maximum suggestions to return, from 1 to 30.
</ParamField>

## Example request

```bash theme={null}
curl 'https://api.sentrion.ai/api/v1/locations?q=new%20york&limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Response

```json theme={null}
{
  "locations": [
    {
      "label": "New York, United States",
      "value": {"country": "united states", "state": "new york", "city": null}
    },
    {
      "label": "New York, New York, United States",
      "value": {"country": "united states", "state": "new york", "city": "new york"}
    }
  ]
}
```

Pass selected `value` objects unchanged in `jobs_locations` or
`exclude_jobs_locations`. `state` and `city` may be null for broader locations.
Suggestions preserve relevance order and omit duplicates. No matches return an
empty `locations` array.

## Errors

| Status | Meaning                                                             |
| ------ | ------------------------------------------------------------------- |
| 403    | Missing, invalid, or inactive API key                               |
| 422    | Invalid query parameters                                            |
| 503    | Account information or location suggestions temporarily unavailable |

Errors use a `detail` field. Successful responses use the object shown above,
without a `success` or `data` wrapper.