Locations

Kardow handles job locations in two layers:

Freeform text on each job. When you create a job you pass location as plain text (for example "Paris, France", "Remote", or a full street address). That is what shows on the listing.
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.

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.

Resolve a place

POST https://api.kardow.com/locations

string

required

Any place description: "Gatineau, QC", "33 Rue des Freres-Moncion, Gatineau", a postal code, or "Remote".

string

Two-letter country code to disambiguate, e.g. ca. Recommended whenever you know it: without it, "Victoria" could be Australia or British Columbia.

boolean

default:"false"

false previews matches without writing anything. true commits the best match and returns its id.

number

default:"5"

Maximum candidates to return, up to 10.

Preview first when the place could be ambiguous:

cURL

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" }'

{
  "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:

{
  "data": { "id": "7f8a...", "display_name": "Gatineau, QC", "created": true },
  "meta": { "query": "Gatineau, QC", "created": true }
}

Fields

string | null

The location entity id. null means this place is not on your board yet.

string

Where the match came from: existing (already on your board), cache, geocoded, or remote.

string

exact (already an entity, or a single unambiguous hit), high (clear top hit), or low (one of several plausible hits: confirm before using).

string | null

The street-level address that matched, when your query was an address. Useful as the job’s location text.

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.

Filtering jobs by location

Use the locations query parameter on Get Jobs (comma-separated, matched against the job’s freeform location):

cURL

curl --url "https://api.kardow.com/jobs?locations=Remote,London" \
  --header "x-api-key: your-api-key-here"

List your locations

GET https://api.kardow.com/locations

string

Match against the location name, display name, or city.

string

Two-letter country code filter, e.g. US.

number

default:"1"

Page number.

number

default:"50"

Records per page, up to 100.

cURL

curl --url "https://api.kardow.com/locations?search=london" \
  --header "x-api-key: your-api-key-here"

{
  "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 } }
}

Getting Started

Analytics

Jobs

Applications

Content

Members

Users

Webhooks

Secrets

CMS

Resolve a place

Fields

Filtering jobs by location

List your locations

​Resolve a place

​Fields

​Filtering jobs by location

​List your locations

Resolve a place

Fields

Filtering jobs by location

List your locations