Source: https://www.puesto.dev/docs/api/locations/search-locations
Markdown source: https://www.puesto.dev/docs/api/locations/search-locations.md
Description: Type-ahead over every place in the jobs corpus — countries, states, cities and regions — in one ranked list. Built to be called per keystroke and to hand back a value you can feed straight into a jobs query.

**Using a result.** Every row carries a `kind` and a `code`; `kind` tells you which filter the `code` belongs to:

| `kind` | example `code` | jobs filter |
| --- | --- | --- |
| `country` | `US` | `country` |
| `state` | `US-TX` | `state` |
| `city` | `austin-tx-us` | the location filter |
| `region` | `emea` | the location filter |

Codes are opaque identifiers — switch on `kind` and pass `code` through verbatim rather than parsing it. (City and region codes are accepted by the location filter; until that filter ships, `country` and `state` suggestions are the ones you can act on.)

**Matching.** `q` is matched case- and diacritic-insensitively (`zurich` finds Zürich, `sao paulo` finds São Paulo) as a substring of the place name. A two-character `q` additionally matches country and state codes exactly, so `ny` finds New York and `de` finds Germany — abbreviations are how people type states, and no name-based match can serve them. That code tier disappears at the third keystroke.

**Ranking.** Exact two-letter code matches first, then names that START with `q`, then names that merely contain it. Within a tier, larger places come first (population, descending), with `country` > `state` > `city` > `region` as the tiebreak between equally sized places. Consequences worth knowing: a bare `q` is global, so `dal` ranks Dalian above Dallas — scope with `country` for a regional board; and at exactly two characters, code matches outrank even large cities (`la` → Laos, Louisiana, then Lahore).

**Regions** are the five multi-country buckets, matched by name like anything else: `amer` (Americas), `apac` (Asia-Pacific), `emea` (Europe, Middle East & Africa), `latam` (Latin America), `worldwide`. They belong to no single country, so supplying `country` excludes them.

Suggestions are drawn from the location dimension, which only contains places that have been seen on a job posting. It does not tell you how many jobs are OPEN there today — a suggestion can resolve to zero current results.

# Search locations

`GET /api/v1/locations/search`

Type-ahead over every place in the jobs corpus — countries, states, cities and regions — in one ranked list. Built to be called per keystroke and to hand back a value you can feed straight into a jobs query.

**Using a result.** Every row carries a `kind` and a `code`; `kind` tells you which filter the `code` belongs to:

| `kind` | example `code` | jobs filter |
| --- | --- | --- |
| `country` | `US` | `country` |
| `state` | `US-TX` | `state` |
| `city` | `austin-tx-us` | the location filter |
| `region` | `emea` | the location filter |

Codes are opaque identifiers — switch on `kind` and pass `code` through verbatim rather than parsing it. (City and region codes are accepted by the location filter; until that filter ships, `country` and `state` suggestions are the ones you can act on.)

**Matching.** `q` is matched case- and diacritic-insensitively (`zurich` finds Zürich, `sao paulo` finds São Paulo) as a substring of the place name. A two-character `q` additionally matches country and state codes exactly, so `ny` finds New York and `de` finds Germany — abbreviations are how people type states, and no name-based match can serve them. That code tier disappears at the third keystroke.

**Ranking.** Exact two-letter code matches first, then names that START with `q`, then names that merely contain it. Within a tier, larger places come first (population, descending), with `country` > `state` > `city` > `region` as the tiebreak between equally sized places. Consequences worth knowing: a bare `q` is global, so `dal` ranks Dalian above Dallas — scope with `country` for a regional board; and at exactly two characters, code matches outrank even large cities (`la` → Laos, Louisiana, then Lahore).

**Regions** are the five multi-country buckets, matched by name like anything else: `amer` (Americas), `apac` (Asia-Pacific), `emea` (Europe, Middle East & Africa), `latam` (Latin America), `worldwide`. They belong to no single country, so supplying `country` excludes them.

Suggestions are drawn from the location dimension, which only contains places that have been seen on a job posting. It does not tell you how many jobs are OPEN there today — a suggestion can resolve to zero current results.

## Parameters

### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | Yes | The typeahead query. Matched case- and diacritic-insensitively against location names (prefix matches rank above substring matches), plus an exact two-letter country/state code match (`q=ny` finds New York). 1-100 characters after trimming. |
| `country` | string[] | No | Restrict suggestions to these ISO 3166-1 alpha-2 country codes. Repeat the parameter or comma-separate values (e.g. `country=us,ca`). Up to 20 values; case-insensitive. Region rows (`emea`, `apac`, …) belong to no country and are therefore never returned when this filter is supplied. |
| `limit` | integer | No | Maximum number of suggestions to return. Defaults to 10; values above 25 are clamped to 25. |

## Response

The ranked suggestions (possibly empty).

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object[] | Matching locations, best match first. Empty when nothing matches. |

## Authentication

Send your secret API key (prefixed `sk_`) as a bearer token in the `Authorization` header. See [Authentication](https://www.puesto.dev/docs/authentication.md).

## Errors

Errors use the RFC 7807 `application/problem+json` format. See [Errors](https://www.puesto.dev/docs/errors.md).

## Example request

```bash
curl -X GET "https://www.puesto.dev/api/v1/locations/search" \
  -H "Authorization: Bearer sk_your_key_here"
```

Full spec: https://www.puesto.dev/api/v1/openapi.json