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

**q** `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.

**limit** `integer` (default: 10)

Maximum suggestions to return, from 1 to 30.

## 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 |
| 500 | Unexpected server error; response body is plain text |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.