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

# Locations

> Resolve places and list your board's normalized, geocoded locations

Kardow handles job locations in two layers:

1. **Freeform text on each job.** When you [create a job](/docs/api-reference/jobs/post-job) you pass `location` as plain text (for example `"Paris, France"`, `"Remote"`, or a full street address). That is what shows on the listing.
2. **Normalized locations.** Geocoded entities (city, state, country, coordinates) that power location landing pages and filters. Each job is linked to one.

Resolve the place first with `POST /locations`, then pass the returned `id` as `location_id` when you create the job. That is the reliable path: you see exactly which place you are about to use, and the job is guaranteed to land on the right city page and filter.

<Info>
  Street addresses resolve to their **city**. A job is browsed by city, so the city is the entity. Keep the full street address in the job's own `location` text: that is what candidates read, and its exact coordinates are stored on the job for map pins.
</Info>

## Resolve a place

```http theme={null}
POST https://api.kardow.com/locations
```

<ParamField body="query" type="string" required>Any place description: `"Gatineau, QC"`, `"33 Rue des Freres-Moncion, Gatineau"`, a postal code, or `"Remote"`.</ParamField>
<ParamField body="country" type="string">Two-letter country code to disambiguate, e.g. `ca`. Recommended whenever you know it: without it, `"Victoria"` could be Australia or British Columbia.</ParamField>
<ParamField body="create" type="boolean" default="false">`false` previews matches without writing anything. `true` commits the best match and returns its `id`.</ParamField>
<ParamField body="limit" type="number" default="5">Maximum candidates to return, up to 10.</ParamField>

Preview first when the place could be ambiguous:

```bash cURL theme={null}
curl --request POST \
  --url "https://api.kardow.com/locations" \
  --header "x-api-key: your-api-key-here" \
  --header "Content-Type: application/json" \
  --data '{ "query": "33 Rue des Freres-Moncion, Gatineau", "country": "ca" }'
```

```json theme={null}
{
  "data": [
    {
      "id": null,
      "display_name": "Gatineau, QC",
      "city": "Gatineau",
      "state": "Quebec",
      "state_code": "QC",
      "country": "Canada",
      "country_code": "CA",
      "latitude": 45.426926,
      "longitude": -75.71554,
      "location_type": "city",
      "full_address": "33 Rue Des Frères-Moncion, Gatineau, Quebec J8M 1E5, Canada",
      "source": "geocoded",
      "confidence": "high"
    }
  ],
  "meta": { "query": "33 Rue des Freres-Moncion, Gatineau", "created": false, "ambiguous": false }
}
```

`id` is `null` when the place is not on your board yet. Re-send with `"create": true` to commit it:

```json theme={null}
{
  "data": { "id": "7f8a...", "display_name": "Gatineau, QC", "created": true },
  "meta": { "query": "Gatineau, QC", "created": true }
}
```

### Fields

<ResponseField name="id" type="string | null">The location entity id. `null` means this place is not on your board yet.</ResponseField>
<ResponseField name="source" type="string">Where the match came from: `existing` (already on your board), `cache`, `geocoded`, or `remote`.</ResponseField>
<ResponseField name="confidence" type="string">`exact` (already an entity, or a single unambiguous hit), `high` (clear top hit), or `low` (one of several plausible hits: confirm before using).</ResponseField>
<ResponseField name="full_address" type="string | null">The street-level address that matched, when your query was an address. Useful as the job's `location` text.</ResponseField>

<Note>
  Resolution checks your board's existing locations first, then a shared geocode cache, and only calls the geocoder as a last resort. Repeat queries and places you already cover cost nothing.
</Note>

## Filtering jobs by location

Use the `locations` query parameter on [Get Jobs](/docs/api-reference/jobs/get-jobs) (comma-separated, matched against the job's freeform location):

```bash cURL theme={null}
curl --url "https://api.kardow.com/jobs?locations=Remote,London" \
  --header "x-api-key: your-api-key-here"
```

## List your locations

```http theme={null}
GET https://api.kardow.com/locations
```

<ParamField query="search" type="string">Match against the location name, display name, or city.</ParamField>
<ParamField query="country_code" type="string">Two-letter country code filter, e.g. `US`.</ParamField>
<ParamField query="page" type="number" default="1">Page number.</ParamField>
<ParamField query="per_page" type="number" default="50">Records per page, up to 100.</ParamField>

```bash cURL theme={null}
curl --url "https://api.kardow.com/locations?search=london" \
  --header "x-api-key: your-api-key-here"
```

```json theme={null}
{
  "data": [
    {
      "id": "7f8a...",
      "name": "London",
      "slug": "london",
      "display_name": "London, England, United Kingdom",
      "city": "London",
      "state": "England",
      "country": "United Kingdom",
      "country_code": "GB",
      "latitude": 51.5074,
      "longitude": -0.1278
    }
  ],
  "meta": { "pagination": { "current_page": 1, "per_page": 50, "total_items": 1, "total_pages": 1, "has_more": false } }
}
```