> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/api/lookups/locations.md).

# Location find

## Find locations

Find location codes with `POST /v9/locations/find`. Use them in `hq_location` for organization headquarters or `country` for jobs and people. Country, state, and city codes work in both filters. Region codes work only in `hq_location`.

### Request modes

| Request body         | Result                                                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `{"query":"austin"}` | Search country, state, and city names and aliases.                                                                        |
| `{"parent":"US"}`    | List a location's children. `US` returns states, and `US:Texas` returns cities. A region returns subregions or countries. |
| `{}`                 | List top-level regions and countries.                                                                                     |

Pass `query`, `parent`, or neither. Passing both fields, or a blank value for either field, returns a 422 error. Using an unknown code or a city code as `parent` returns a 400 error. Cities have no children.

Name searches return up to 100 results, ordered by exact name match first, then by job count. City listings return up to 500 results, ordered by job count. Name searches do not return regions.

### Location codes

Use each returned `code` exactly as given. Codes are case-sensitive and use colons to separate the country, state, and city. A code has one, two or three parts; a code with more parts, an empty country, or an empty last part is rejected.

| Location type | Example code      |
| ------------- | ----------------- |
| Country       | `US` or `UK`      |
| State         | `US:Texas`        |
| City          | `US:Texas:Austin` |
| Region        | `EMEA`            |

State codes use full names, such as `US:California`. A code such as `US:CA` is invalid. Name searches also match abbreviations and aliases, so `{"query":"CA"}` finds California and `{"query":"san fran"}` finds San Francisco. The returned code uses the full name. The United Kingdom's code is `UK`.

Region codes are `EMEA`, `APAC`, `NAMER`, `LATAM`, `Americas`, `Europe`, `MiddleEast`, and `Africa`. To filter jobs or people by a region, first find its country codes. For example:

1. Send `{"parent":"EMEA"}` to get `Europe`, `MiddleEast`, and `Africa`.
2. Pass each returned code as `parent`, such as `{"parent":"Europe"}`, to get the countries in that subregion.
3. Combine those country codes in a `country IN (...)` clause.

For headquarters, use the region code directly, such as `hq_location IN ('EMEA')`.

### Response fields

Each entry in `locations` contains:

| Field          | Meaning                                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `code`         | Location code to use in a filter.                                                                                   |
| `name`         | Display name.                                                                                                       |
| `type`         | `region`, `country`, `state`, or `city`.                                                                            |
| `path`         | Ancestor names, outermost first. For Austin, this is `["United States", "Texas"]`. Empty for regions and countries. |
| `expandable`   | Whether this location has children you can list by passing its `code` as `parent`.                                  |
| `orgs_count`   | Number of organizations headquartered there.                                                                        |
| `jobs_count`   | Number of job posts located there.                                                                                  |
| `people_count` | Number of people located there.                                                                                     |

### Credit cost

1 credit for a request that returns at least one location. Requests with no matches cost no credits.