API reference

The base URL is https://api.onde.earth. All requests use HTTPS and return JSON. Send live requests in City API on the landing page.

A successful response has data and meta. data is one object or a list. meta.dataset is the dataset version. Errors gives the format of an error.

Quick start

If you distribute the data, keep this credit: Contains data from GeoNames, CC BY 4.0, modified.

Request

curl "https://api.onde.earth/v1/cities/autocomplete?q=kyoto" \
  -H "Authorization: Bearer $ONDE_KEY"

Authentication

A secret key starts with onde_sk_. Send the secret key from a server, in the Authorization header. The API refuses a secret key in the URL.

A public key starts with onde_pk_. Use a public key in a browser. Send the public key in ?key=, because an Authorization header adds an OPTIONS request for each new URL. The API accepts a public key only from the allowed origins of the key.

Rate limits

Each plan sets a monthly limit of units and a limit of requests per second. A unit is a response with status 200 from any endpoint. A reverse lookup that finds no city also counts one unit. A batch reverse lookup counts one unit for each position, and one request for the limit of requests per second. If the positions are more than the units left in the month, the API refuses the full batch.

A public key also has a limit of 10 requests per second for each IP network. If the requests are above a limit, the API sends status 429 and a Retry-After header. The Retry-After value is in seconds.

Errors

An error response has the content type application/problem+json. The body has code, detail, and requestId.

Code	Status	Meaning
`invalid_request`	400	A parameter or the body is not valid. The `errors` field lists each parameter that is not valid.
`unauthorized`	401	The request has no key, the key is not valid, or a secret key is in the URL.
`origin_not_allowed`	403	The origin of the request is not one of the allowed origins of the public key.
`not_found`	404	The city ID or the country code does not exist.
`city_retired`	410	The city ID is retired and has no replacement.
`rate_limited`	429	The requests are above a limit of requests per second.
`quota_exceeded`	429	The account is above its monthly limit of units.
`internal_error`	500	An error occurred on the server.

City API

City API gives autocomplete, search, and reverse lookup for cities, with names in 13 languages.

Cities

While a person types, use autocomplete. Then send the ID of the selected city to Get a city. For a full name, such as Burlington, Vermont, use search. To refuse a guess, accept only a city with exact or alias in match.

Autocomplete GET /v1/cities/autocomplete
Search GET /v1/cities/search
Reverse lookup GET /v1/cities/reverse
Batch reverse lookup POST /v1/cities/reverse/batch
Get a city GET /v1/cities/{id}

The city object

Autocomplete, search, reverse lookup, and batch reverse lookup return the city object. Get a city returns the full city object. The full city object adds the fields with the full city label, such as the names in each language.

Fields

id string The city ID. The ID never changes.
name string The display name in the requested language.
localName string or null The name in the main language of the country, such as München, or null.
type string The place type: city, or district for a part of a larger city.
parentCityId string or null The ID of the parent city of a district, otherwise null.
country object The country of the city.
- code string The ISO 3166-1 alpha-2 code.
- name string The name in the requested language.
- names object full city The country name in each language, by language code.
region object or null The region, which is the first-order division of the country, or null.
- id string The value for the `region` parameter of search.
- isoCode string or null The ISO 3166-2 code, or null.
- name string The name in the requested language.
- names object full city The region name in each language, by language code.
coordinates object The position of the city.
- latitude number The latitude in degrees.
- longitude number The longitude in degrees.
population integer The population in the dataset.
timeZone string The IANA time zone of the city.
isCapital boolean True for a national capital.
disputed boolean True if the city is in an area on a published list of disputed areas. The value is not a political position.
names object full city The name in each language, by language code.

The city object

{
  "id": "city_f56eq77e1f",
  "name": "Paris",
  "localName": "Paris",
  "type": "city",
  "parentCityId": null,
  "country": {
    "code": "FR",
    "name": "France",
    "names": {
      "en": "France",
      "de": "Frankreich",
      "es": "Francia",
      "fr": "France",
      "it": "Francia",
      "nl": "Frankrijk",
      "pt": "França",
      "ru": "Франция",
      "ja": "フランス",
      "ko": "프랑스",
      "zh": "法国",
      "ar": "فرنسا",
      "hi": "फ़्रांस"
    }
  },
  "region": {
    "id": "region_6b5jrtzvrz",
    "isoCode": "FR-IDF",
    "name": "Île-de-France",
    "names": {
      "en": "Île-de-France",
      "de": "Île-de-France",
      "es": "Isla de Francia",
      "fr": "Île-de-France",
      "it": "Île-de-France",
      "nl": "Île-de-France",
      "pt": "Ilha de França",
      "ru": "Иль-де-Франс",
      "ja": "イル・ド・フランス",
      "ko": "일드프랑스",
      "zh": "法兰西岛",
      "ar": "إيل دو فرانس",
      "hi": "इल-दा-फ़्रान्स"
    }
  },
  "coordinates": {
    "latitude": 48.85341,
    "longitude": 2.3488
  },
  "population": 2138551,
  "timeZone": "Europe/Paris",
  "isCapital": true,
  "disputed": false,
  "names": {
    "en": "Paris",
    "de": "Paris",
    "es": "París",
    "fr": "Paris",
    "it": "Parigi",
    "nl": "Parijs",
    "pt": "Paris",
    "ru": "Париж",
    "ja": "パリ",
    "ko": "파리",
    "zh": "巴黎",
    "ar": "باريس",
    "hi": "पैरिस"
  }
}

Worldviews

The worldview parameter sets the country of cities in disputed areas. The default is us.

The worldview changes these values:

country of each city
the country filter
the list of countries
the country after a comma in search
the country that reverse lookup prefers

If the worldview changes the country of a city, region is null. disputed does not change.

Country codes and names are not a political position.

Value	Country
`ar`	Argentina
`cn`	China
`in`	India
`jp`	Japan
`ma`	Morocco
`rs`	Serbia
`ru`	Russia
`tr`	Türkiye
`us`	United States (default)

Autocomplete

GET /v1/cities/autocomplete

Cities that start with the text. This route needs a key.

Parameters

q string, query required The text to match, up to 100 characters.
limit integer, query The number of cities to return. From 1 to 10. Default: 5.
country string, query Up to 10 ISO 3166-1 alpha-2 codes, separated by commas.
language string, query The language of the names. Default: en. en, de, es, fr, it, nl, pt, ru, ja, ko, zh, ar, hi
worldview string, query The worldview, which sets the country of a city in a disputed area. Default: us. ar, cn, in, jp, ma, rs, ru, tr, us

Returns

This route returns a list of city objects with this extra field:

match string The type of match between the text and the city: exact, alias, prefix, or fuzzy.

Errors: 400, 401, 403, 429

Request

curl "https://api.onde.earth/v1/cities/autocomplete?q=kyoto" \
  -H "Authorization: Bearer $ONDE_KEY"

Response 200

{
  "data": [
    {
      "id": "city_39sy1dm2dj",
      "name": "Kyoto",
      "localName": "京都市",
      "type": "city",
      "parentCityId": null,
      "country": {
        "code": "JP",
        "name": "Japan"
      },
      "region": {
        "id": "region_yjwfrtj0fe",
        "isoCode": "JP-26",
        "name": "Kyoto"
      },
      "coordinates": {
        "latitude": 35.02107,
        "longitude": 135.75385
      },
      "population": 1463723,
      "timeZone": "Asia/Tokyo",
      "isCapital": false,
      "disputed": false,
      "match": "exact"
    }
  ],
  "meta": {
    "dataset": "2026-11-17"
  }
}

Search

GET /v1/cities/search

Cities that match a full name. This route needs a key.

Parameters

q string, query required The text to match, up to 100 characters.
limit integer, query The number of cities to return. From 1 to 10. Default: 5.
country string, query Up to 10 ISO 3166-1 alpha-2 codes, separated by commas.
language string, query The language of the names. Default: en. en, de, es, fr, it, nl, pt, ru, ja, ko, zh, ar, hi
worldview string, query The worldview, which sets the country of a city in a disputed area. Default: us. ar, cn, in, jp, ma, rs, ru, tr, us
region string, query A region ID, such as region_yjwfrtj0fe.

Returns

This route returns a list of city objects with this extra field:

match string The type of match between the text and the city: exact, alias, prefix, or fuzzy.

Errors: 400, 401, 403, 429

Request

curl "https://api.onde.earth/v1/cities/search?q=kyoto" \
  -H "Authorization: Bearer $ONDE_KEY"

Response 200

{
  "data": [
    {
      "id": "city_39sy1dm2dj",
      "name": "Kyoto",
      "localName": "京都市",
      "type": "city",
      "parentCityId": null,
      "country": {
        "code": "JP",
        "name": "Japan"
      },
      "region": {
        "id": "region_yjwfrtj0fe",
        "isoCode": "JP-26",
        "name": "Kyoto"
      },
      "coordinates": {
        "latitude": 35.02107,
        "longitude": 135.75385
      },
      "population": 1463723,
      "timeZone": "Asia/Tokyo",
      "isCapital": false,
      "disputed": false,
      "match": "exact"
    }
  ],
  "meta": {
    "dataset": "2026-11-17"
  }
}

Reverse lookup

GET /v1/cities/reverse

The city at a position, or null. This route needs a key.

Reverse lookup prefers a large city to a small neighbor city. Reverse lookup also prefers a capital or the seat of a region within 6 km of the position. If no city is near the position, data is null. Near a border, the country can be wrong. timeZone is the time zone of the city. This time zone can differ from the time zone at the position.

Parameters

latitude number, query required The latitude of the position.
longitude number, query required The longitude of the position.
language string, query The language of the names. Default: en. en, de, es, fr, it, nl, pt, ru, ja, ko, zh, ar, hi
worldview string, query The worldview, which sets the country of a city in a disputed area. Default: us. ar, cn, in, jp, ma, rs, ru, tr, us

Returns

This route returns a city object with this extra field:

distanceKm number The distance from the position in kilometers.

Errors: 400, 401, 403, 429

Request

curl "https://api.onde.earth/v1/cities/reverse?latitude=35.02&longitude=135.75" \
  -H "Authorization: Bearer $ONDE_KEY"

Response 200

{
  "data": {
    "id": "city_39sy1dm2dj",
    "name": "Kyoto",
    "localName": "京都市",
    "type": "city",
    "parentCityId": null,
    "country": {
      "code": "JP",
      "name": "Japan"
    },
    "region": {
      "id": "region_yjwfrtj0fe",
      "isoCode": "JP-26",
      "name": "Kyoto"
    },
    "coordinates": {
      "latitude": 35.02107,
      "longitude": 135.75385
    },
    "population": 1463723,
    "timeZone": "Asia/Tokyo",
    "isCapital": false,
    "disputed": false,
    "distanceKm": 0.37023042894617736
  },
  "meta": {
    "dataset": "2026-11-17"
  }
}

Batch reverse lookup

POST /v1/cities/reverse/batch

The city at each position, or null, in the request order. This route needs a key.

data has the reverse lookup result for each position, at the index of the position. If no city is near a position, the result is null. If one position is not valid, the request fails and returns no results.

Parameters

positions array, body required The positions. The results have the same order. From 1 to 100 items.
- latitude number required The latitude of the position. From -90 to 90.
- longitude number required The longitude of the position. From -180 to 180.
language string, body The language of the names. Default: en. en, de, es, fr, it, nl, pt, ru, ja, ko, zh, ar, hi
worldview string, body The worldview, which sets the country of a city in a disputed area. Default: us. ar, cn, in, jp, ma, rs, ru, tr, us

Returns

This route returns a list of city objects with this extra field:

distanceKm number The distance from the position in kilometers.

Errors: 400, 401, 403, 429

Request

curl "https://api.onde.earth/v1/cities/reverse/batch" \
  -H "Authorization: Bearer $ONDE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"positions":[{"latitude":35.02,"longitude":135.75}]}'

Response 200

{
  "data": [
    {
      "id": "city_39sy1dm2dj",
      "name": "Kyoto",
      "localName": "京都市",
      "type": "city",
      "parentCityId": null,
      "country": {
        "code": "JP",
        "name": "Japan"
      },
      "region": {
        "id": "region_yjwfrtj0fe",
        "isoCode": "JP-26",
        "name": "Kyoto"
      },
      "coordinates": {
        "latitude": 35.02107,
        "longitude": 135.75385
      },
      "population": 1463723,
      "timeZone": "Asia/Tokyo",
      "isCapital": false,
      "disputed": false,
      "distanceKm": 0.37023042894617736
    }
  ],
  "meta": {
    "dataset": "2026-11-17"
  }
}

Get a city

GET /v1/cities/{id}

The city with the ID. This route needs a key.

If the ID is retired and has a replacement, the API returns the replacement city, and meta.retiredId is the requested ID. Otherwise, meta.retiredId is null.

Parameters

id string, path required The city ID.
language string, query The language of the names. Default: en. en, de, es, fr, it, nl, pt, ru, ja, ko, zh, ar, hi
worldview string, query The worldview, which sets the country of a city in a disputed area. Default: us. ar, cn, in, jp, ma, rs, ru, tr, us

Returns

This route returns a full city object, with all fields.

Errors: 400, 401, 403, 404, 410, 429

Request

curl "https://api.onde.earth/v1/cities/city_f56eq77e1f" \
  -H "Authorization: Bearer $ONDE_KEY"

Response 200

{
  "data": {
    "id": "city_f56eq77e1f",
    "name": "Paris",
    "localName": "Paris",
    "type": "city",
    "parentCityId": null,
    "country": {
      "code": "FR",
      "name": "France",
      "names": {
        "en": "France",
        "de": "Frankreich",
        "es": "Francia",
        "fr": "France",
        "it": "Francia",
        "nl": "Frankrijk",
        "pt": "França",
        "ru": "Франция",
        "ja": "フランス",
        "ko": "프랑스",
        "zh": "法国",
        "ar": "فرنسا",
        "hi": "फ़्रांस"
      }
    },
    "region": {
      "id": "region_6b5jrtzvrz",
      "isoCode": "FR-IDF",
      "name": "Île-de-France",
      "names": {
        "en": "Île-de-France",
        "de": "Île-de-France",
        "es": "Isla de Francia",
        "fr": "Île-de-France",
        "it": "Île-de-France",
        "nl": "Île-de-France",
        "pt": "Ilha de França",
        "ru": "Иль-де-Франс",
        "ja": "イル・ド・フランス",
        "ko": "일드프랑스",
        "zh": "法兰西岛",
        "ar": "إيل دو فرانس",
        "hi": "इल-दा-फ़्रान्स"
      }
    },
    "coordinates": {
      "latitude": 48.85341,
      "longitude": 2.3488
    },
    "population": 2138551,
    "timeZone": "Europe/Paris",
    "isCapital": true,
    "disputed": false,
    "names": {
      "en": "Paris",
      "de": "Paris",
      "es": "París",
      "fr": "Paris",
      "it": "Parigi",
      "nl": "Parijs",
      "pt": "Paris",
      "ru": "Париж",
      "ja": "パリ",
      "ko": "파리",
      "zh": "巴黎",
      "ar": "باريس",
      "hi": "पैरिस"
    }
  },
  "meta": {
    "dataset": "2026-11-17",
    "retiredId": null
  }
}

Countries

These routes return the countries and the regions of a country. A region is a first-order division of a country. Use a region ID as the value of the region parameter of search.

List countries GET /v1/countries
List regions GET /v1/countries/{code}/regions

List countries

GET /v1/countries

All countries. This route needs a key.

Parameters

language string, query The language of the names. Default: en. en, de, es, fr, it, nl, pt, ru, ja, ko, zh, ar, hi
worldview string, query The worldview, which sets the country of a city in a disputed area. Default: us. ar, cn, in, jp, ma, rs, ru, tr, us

Returns

code string The ISO 3166-1 alpha-2 code.
name string The name in the requested language.
continentCode string The continent code.

Errors: 400, 401, 403, 429

Request

curl "https://api.onde.earth/v1/countries" \
  -H "Authorization: Bearer $ONDE_KEY"

Response 200

{
  "data": [
    {
      "code": "AD",
      "name": "Andorra",
      "continentCode": "EU"
    }
  ],
  "meta": {
    "dataset": "2026-11-17"
  }
}

List regions

GET /v1/countries/{code}/regions

The regions of a country. This route needs a key.

Parameters

code string, path required The ISO 3166-1 alpha-2 country code.
language string, query The language of the names. Default: en. en, de, es, fr, it, nl, pt, ru, ja, ko, zh, ar, hi
worldview string, query The worldview, which sets the country of a city in a disputed area. Default: us. ar, cn, in, jp, ma, rs, ru, tr, us

Returns

id string The value for the `region` parameter of search.
isoCode string or null The ISO 3166-2 code, or null.
name string The name in the requested language.

Errors: 400, 401, 403, 404, 429

Request

curl "https://api.onde.earth/v1/countries/FR/regions" \
  -H "Authorization: Bearer $ONDE_KEY"

Response 200

{
  "data": [
    {
      "id": "region_84pj8sf7v2",
      "isoCode": "FR-ARA",
      "name": "Auvergne-Rhône-Alpes"
    }
  ],
  "meta": {
    "dataset": "2026-11-17"
  }
}

Get dataset details

GET /v1/meta

The dataset version. This route needs no key.

Returns

dataset string The dataset version.

Request

curl "https://api.onde.earth/v1/meta"

Response 200

{
  "data": {
    "dataset": "2026-11-17"
  },
  "meta": {
    "dataset": "2026-11-17"
  }
}

Quick start

Authentication

Rate limits

Errors

Cities

The city object

Fields

Worldviews

Autocomplete

Parameters

Returns

Search

Parameters

Returns

Reverse lookup

Parameters

Returns

Batch reverse lookup

Parameters

Returns

Get a city

Parameters

Returns

Countries

List countries

Parameters

Returns

List regions

Parameters

Returns

Meta

Get dataset details

Returns