{"openapi":"3.1.0","info":{"title":"City API","version":"1.0.0","description":"City API gives autocomplete, search, and reverse lookup for cities, with names in multiple languages."},"servers":[{"url":"https://api.onde.earth"}],"tags":[{"name":"Cities","description":"While a person types, use [autocomplete](#autocompleteCities). Then send the ID of the selected city to [Get a city](#getCity). For a full name, such as `Burlington, Vermont`, use [search](#searchCities). To refuse a guess, accept only a city with `exact` or `alias` in `match`."},{"name":"Countries","description":"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."},{"name":"Meta","description":"This route returns the dataset version that the API serves."}],"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer"},"queryKey":{"type":"apiKey","in":"query","name":"key"}},"schemas":{"Worldview":{"type":"string","enum":["ar","cn","in","jp","ma","rs","ru","tr","us"],"default":"us","description":"The `worldview` parameter sets the country of cities in disputed areas. The default is `us`.\n\nThe worldview changes these values:\n\n- `country` of each city\n- the `country` filter\n- the [list of countries](#listCountries)\n- the country after a comma in search\n- the country that reverse lookup prefers\n\nIf the worldview changes the country of a city, `region` is `null`. `disputed` does not change.\n\nCountry codes and names are not a political position.","oneOf":[{"const":"ar","description":"Argentina"},{"const":"cn","description":"China"},{"const":"in","description":"India"},{"const":"jp","description":"Japan"},{"const":"ma","description":"Morocco"},{"const":"rs","description":"Serbia"},{"const":"ru","description":"Russia"},{"const":"tr","description":"Türkiye"},{"const":"us","description":"United States"}]},"MatchedCity":{"allOf":[{"$ref":"#/components/schemas/City"},{"type":"object","properties":{"match":{"type":"string","enum":["exact","alias","prefix","fuzzy"],"description":"The type of match between the text and the city: exact, alias, prefix, or fuzzy."}},"required":["match"]}],"description":"Autocomplete, search, reverse lookup, and batch reverse lookup return the city object. [Get a city](#getCity) returns the full city object. The full city object adds the fields with the full city label, such as the names in each language."},"City":{"type":"object","properties":{"id":{"type":"string","description":"The city ID. The ID never changes."},"name":{"type":"string","description":"The display name in the requested language."},"localName":{"type":["string","null"],"description":"The name in the main language of the country, such as München, or null."},"type":{"type":"string","enum":["city","district"],"description":"The place type: city, or district for a part of a larger city."},"parentCityId":{"type":["string","null"],"description":"The ID of the parent city of a district, otherwise null."},"country":{"type":"object","properties":{"code":{"type":"string","description":"The ISO 3166-1 alpha-2 code."},"name":{"type":"string","description":"The name in the requested language."}},"required":["code","name"],"description":"The country of the city."},"region":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The value for the `region` parameter of search."},"isoCode":{"type":["string","null"],"description":"The ISO 3166-2 code, or null."},"name":{"type":"string","description":"The name in the requested language."}},"required":["id","isoCode","name"],"description":"The region, which is the first-order division of the country, or null."},"coordinates":{"type":"object","properties":{"latitude":{"type":"number","description":"The latitude in degrees."},"longitude":{"type":"number","description":"The longitude in degrees."}},"required":["latitude","longitude"],"description":"The position of the city."},"population":{"type":"integer","description":"The population in the dataset."},"timeZone":{"type":"string","description":"The IANA time zone of the city."},"isCapital":{"type":"boolean","description":"True for a national capital."},"disputed":{"type":"boolean","description":"True if the city is in an area on a published list of disputed areas. The value is not a political position."}},"required":["id","name","localName","type","parentCityId","country","region","coordinates","population","timeZone","isCapital","disputed"],"description":"Autocomplete, search, reverse lookup, and batch reverse lookup return the city object. [Get a city](#getCity) returns the full city object. The full city object adds the fields with the full city label, such as the names in each language."},"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string","oneOf":[{"const":"invalid_request","description":"A parameter or the body is not valid. The `errors` field lists each parameter that is not valid.","x-status":400},{"const":"unauthorized","description":"The request has no key, the key is not valid, or a secret key is in the URL.","x-status":401},{"const":"origin_not_allowed","description":"The origin of the request is not one of the allowed origins of the public key.","x-status":403},{"const":"not_found","description":"The city ID or the country code does not exist.","x-status":404},{"const":"city_retired","description":"The city ID is retired and has no replacement.","x-status":410},{"const":"rate_limited","description":"The requests are above a limit of requests per second.","x-status":429},{"const":"quota_exceeded","description":"The account is above its monthly limit of units.","x-status":429},{"const":"internal_error","description":"An error occurred on the server.","x-status":500}]},"requestId":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"parameter":{"type":"string"},"message":{"type":"string"}},"required":["parameter","message"]}}},"required":["type","title","status","detail","code","requestId"]},"ReverseCity":{"allOf":[{"$ref":"#/components/schemas/City"},{"type":["object","null"],"properties":{"distanceKm":{"type":"number","description":"The distance from the position in kilometers."}},"required":["distanceKm"]}],"description":"Autocomplete, search, reverse lookup, and batch reverse lookup return the city object. [Get a city](#getCity) returns the full city object. The full city object adds the fields with the full city label, such as the names in each language."},"CityDetail":{"allOf":[{"$ref":"#/components/schemas/City"},{"type":"object","properties":{"country":{"type":"object","properties":{"code":{"type":"string","description":"The ISO 3166-1 alpha-2 code."},"name":{"type":"string","description":"The name in the requested language."},"names":{"type":"object","properties":{"en":{"type":"string"},"de":{"type":"string"},"es":{"type":"string"},"fr":{"type":"string"},"it":{"type":"string"},"nl":{"type":"string"},"pt":{"type":"string"},"ru":{"type":"string"},"ja":{"type":"string"},"ko":{"type":"string"},"zh":{"type":"string"},"ar":{"type":"string"},"hi":{"type":"string"}},"description":"The country name in each language, by language code."}},"required":["code","name","names"],"description":"The country of the city."},"region":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The value for the `region` parameter of search."},"isoCode":{"type":["string","null"],"description":"The ISO 3166-2 code, or null."},"name":{"type":"string","description":"The name in the requested language."},"names":{"type":"object","properties":{"en":{"type":"string"},"de":{"type":"string"},"es":{"type":"string"},"fr":{"type":"string"},"it":{"type":"string"},"nl":{"type":"string"},"pt":{"type":"string"},"ru":{"type":"string"},"ja":{"type":"string"},"ko":{"type":"string"},"zh":{"type":"string"},"ar":{"type":"string"},"hi":{"type":"string"}},"description":"The region name in each language, by language code."}},"required":["id","isoCode","name","names"],"description":"The region, which is the first-order division of the country, or null."},"names":{"type":"object","properties":{"en":{"type":"string"},"de":{"type":"string"},"es":{"type":"string"},"fr":{"type":"string"},"it":{"type":"string"},"nl":{"type":"string"},"pt":{"type":"string"},"ru":{"type":"string"},"ja":{"type":"string"},"ko":{"type":"string"},"zh":{"type":"string"},"ar":{"type":"string"},"hi":{"type":"string"}},"description":"The name in each language, by language code."}},"required":["names"]}],"description":"Autocomplete, search, reverse lookup, and batch reverse lookup return the city object. [Get a city](#getCity) returns the full city object. The full city object adds the fields with the full city label, such as the names in each language."}},"parameters":{}},"paths":{"/v1/cities/autocomplete":{"get":{"operationId":"autocompleteCities","summary":"Autocomplete","tags":["Cities"],"security":[{"bearerKey":[]},{"queryKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"The text to match, up to 100 characters."},"required":true,"description":"The text to match, up to 100 characters.","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"The number of cities to return."},"required":false,"description":"The number of cities to return.","name":"limit","in":"query"},{"schema":{"type":"string","pattern":"^[A-Z]{2}(,[A-Z]{2}){0,9}$","description":"Up to 10 ISO 3166-1 alpha-2 codes, separated by commas."},"required":false,"description":"Up to 10 ISO 3166-1 alpha-2 codes, separated by commas.","name":"country","in":"query"},{"schema":{"type":"string","enum":["en","de","es","fr","it","nl","pt","ru","ja","ko","zh","ar","hi"],"default":"en","description":"The language of the names."},"required":false,"description":"The language of the names.","name":"language","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/Worldview"},{"description":"The worldview, which sets the country of a city in a disputed area."}]},"required":false,"description":"The worldview, which sets the country of a city in a disputed area.","name":"worldview","in":"query"}],"responses":{"200":{"description":"Cities that start with the text","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MatchedCity"}},"meta":{"type":"object","properties":{"dataset":{"type":"string","description":"The dataset version."}},"required":["dataset"]}},"required":["data","meta"]}}}},"400":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cities/search":{"get":{"operationId":"searchCities","summary":"Search","tags":["Cities"],"security":[{"bearerKey":[]},{"queryKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"The text to match, up to 100 characters."},"required":true,"description":"The text to match, up to 100 characters.","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"The number of cities to return."},"required":false,"description":"The number of cities to return.","name":"limit","in":"query"},{"schema":{"type":"string","pattern":"^[A-Z]{2}(,[A-Z]{2}){0,9}$","description":"Up to 10 ISO 3166-1 alpha-2 codes, separated by commas."},"required":false,"description":"Up to 10 ISO 3166-1 alpha-2 codes, separated by commas.","name":"country","in":"query"},{"schema":{"type":"string","enum":["en","de","es","fr","it","nl","pt","ru","ja","ko","zh","ar","hi"],"default":"en","description":"The language of the names."},"required":false,"description":"The language of the names.","name":"language","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/Worldview"},{"description":"The worldview, which sets the country of a city in a disputed area."}]},"required":false,"description":"The worldview, which sets the country of a city in a disputed area.","name":"worldview","in":"query"},{"schema":{"type":"string","pattern":"^region_[0123456789abcdefghjkmnpqrstvwxyz]{10}$","description":"A region ID, such as region_yjwfrtj0fe."},"required":false,"description":"A region ID, such as region_yjwfrtj0fe.","name":"region","in":"query"}],"responses":{"200":{"description":"Cities that match a full name","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MatchedCity"}},"meta":{"type":"object","properties":{"dataset":{"type":"string","description":"The dataset version."}},"required":["dataset"]}},"required":["data","meta"]}}}},"400":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cities/reverse":{"get":{"operationId":"reverseCity","summary":"Reverse lookup","description":"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.","tags":["Cities"],"security":[{"bearerKey":[]},{"queryKey":[]}],"parameters":[{"schema":{"type":"number","example":0,"description":"The latitude of the position."},"required":true,"description":"The latitude of the position.","name":"latitude","in":"query"},{"schema":{"type":"number","example":0,"description":"The longitude of the position."},"required":true,"description":"The longitude of the position.","name":"longitude","in":"query"},{"schema":{"type":"string","enum":["en","de","es","fr","it","nl","pt","ru","ja","ko","zh","ar","hi"],"default":"en","description":"The language of the names."},"required":false,"description":"The language of the names.","name":"language","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/Worldview"},{"description":"The worldview, which sets the country of a city in a disputed area."}]},"required":false,"description":"The worldview, which sets the country of a city in a disputed area.","name":"worldview","in":"query"}],"responses":{"200":{"description":"The city at a position, or null","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReverseCity"},"meta":{"type":"object","properties":{"dataset":{"type":"string","description":"The dataset version."}},"required":["dataset"]}},"required":["data","meta"]}}}},"400":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cities/reverse/batch":{"post":{"operationId":"batchReverseCities","summary":"Batch reverse lookup","description":"`data` has the [reverse lookup](#reverseCity) 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.","tags":["Cities"],"security":[{"bearerKey":[]},{"queryKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"positions":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"The latitude of the position."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"The longitude of the position."}},"required":["latitude","longitude"]},"minItems":1,"maxItems":100,"description":"The positions. The results have the same order."},"language":{"type":"string","enum":["en","de","es","fr","it","nl","pt","ru","ja","ko","zh","ar","hi"],"default":"en","description":"The language of the names."},"worldview":{"allOf":[{"$ref":"#/components/schemas/Worldview"},{"description":"The worldview, which sets the country of a city in a disputed area."}]}},"required":["positions"]}}}},"responses":{"200":{"description":"The city at each position, or null, in the request order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReverseCity"}},"meta":{"type":"object","properties":{"dataset":{"type":"string","description":"The dataset version."}},"required":["dataset"]}},"required":["data","meta"]}}}},"400":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/cities/{id}":{"get":{"operationId":"getCity","summary":"Get a city","description":"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`.","tags":["Cities"],"security":[{"bearerKey":[]},{"queryKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^city_[0123456789abcdefghjkmnpqrstvwxyz]{10}$","example":"city_39sy1dm2dj","description":"The city ID."},"required":true,"description":"The city ID.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","de","es","fr","it","nl","pt","ru","ja","ko","zh","ar","hi"],"default":"en","description":"The language of the names."},"required":false,"description":"The language of the names.","name":"language","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/Worldview"},{"description":"The worldview, which sets the country of a city in a disputed area."}]},"required":false,"description":"The worldview, which sets the country of a city in a disputed area.","name":"worldview","in":"query"}],"responses":{"200":{"description":"The city with the ID","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CityDetail"},"meta":{"type":"object","properties":{"dataset":{"type":"string","description":"The dataset version."},"retiredId":{"type":["string","null"]}},"required":["dataset","retiredId"]}},"required":["data","meta"]}}}},"400":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/countries":{"get":{"operationId":"listCountries","summary":"List countries","tags":["Countries"],"security":[{"bearerKey":[]},{"queryKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","de","es","fr","it","nl","pt","ru","ja","ko","zh","ar","hi"],"default":"en","description":"The language of the names."},"required":false,"description":"The language of the names.","name":"language","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/Worldview"},{"description":"The worldview, which sets the country of a city in a disputed area."}]},"required":false,"description":"The worldview, which sets the country of a city in a disputed area.","name":"worldview","in":"query"}],"responses":{"200":{"description":"All countries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"The ISO 3166-1 alpha-2 code."},"name":{"type":"string","description":"The name in the requested language."},"continentCode":{"type":"string","description":"The continent code."}},"required":["code","name","continentCode"]}},"meta":{"type":"object","properties":{"dataset":{"type":"string","description":"The dataset version."}},"required":["dataset"]}},"required":["data","meta"]}}}},"400":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/countries/{code}/regions":{"get":{"operationId":"listRegions","summary":"List regions","tags":["Countries"],"security":[{"bearerKey":[]},{"queryKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"FR","description":"The ISO 3166-1 alpha-2 country code."},"required":true,"description":"The ISO 3166-1 alpha-2 country code.","name":"code","in":"path"},{"schema":{"type":"string","enum":["en","de","es","fr","it","nl","pt","ru","ja","ko","zh","ar","hi"],"default":"en","description":"The language of the names."},"required":false,"description":"The language of the names.","name":"language","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/Worldview"},{"description":"The worldview, which sets the country of a city in a disputed area."}]},"required":false,"description":"The worldview, which sets the country of a city in a disputed area.","name":"worldview","in":"query"}],"responses":{"200":{"description":"The regions of a country","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The value for the `region` parameter of search."},"isoCode":{"type":["string","null"],"description":"The ISO 3166-2 code, or null."},"name":{"type":"string","description":"The name in the requested language."}},"required":["id","isoCode","name"]}},"meta":{"type":"object","properties":{"dataset":{"type":"string","description":"The dataset version."}},"required":["dataset"]}},"required":["data","meta"]}}}},"400":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/meta":{"get":{"operationId":"getMeta","summary":"Get dataset details","tags":["Meta"],"responses":{"200":{"description":"The dataset version","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"dataset":{"type":"string","description":"The dataset version."}},"required":["dataset"]},"meta":{"type":"object","properties":{"dataset":{"type":"string","description":"The dataset version."}},"required":["dataset"]}},"required":["data","meta"]}}}}}}}},"webhooks":{}}