Geo API: places, boundaries and reverse geocoding API

One API for the world's countries and their first-level regions, plus Turkey's provinces (il), districts (ilçe) and neighborhoods (mahalle). It tells you which country, province and district a coordinate falls in, the nearest places and the timezone; it finds postal codes, serves boundaries as map-ready GeoJSON, and validates and formats phone numbers.

Live demo

Search for a place in the box at the top, click an example in a tab, or pick a point on the map. The result opens in the tab; the requests sent to the Geo API, their responses and code appear under the map. The demo runs on our own server: 300 lookups per hour per IP.

— countries— provinces— districtsData version —

The API supports more than 300 languages; the 20 most used are here.

Which country, province, district and neighborhood holds a point, which places are nearest, and what time is it there? Click the map or pick an example.

Click the map or pick an example to select a place.

Loading the map…

This map is drawn only from the Geo API's vector tiles; hover a place to see its name.

Requests to the API

Pick an example or click the map: every request our server sends to the Geo API, with its status, time, response and code, shows up here.

Time is the response time measured from our server to the Geo API. The code runs on a server: GEO_API_URL and GEO_API_KEY are your own values; the key never reaches the browser.

What you can do with Geo API

Countries and regions worldwide, Turkey's provinces, districts and neighborhoods, boundaries, nearby places, timezones, postal codes and phone numbers come from one versioned dataset.

Coordinate to country and state

Send a latitude and longitude and get the country and state or province that contain it, plus the district in Turkey, tested against real boundaries (reverse geocoding). A point at sea returns no match instead of a guess.

Nearest places

Get the cities, towns and villages nearest to a coordinate with their distance (km) and population; each comes with its country and region. Source: GeoNames, every place in the world with more than 500 people or a seat of government.

Timezone and local time by coordinate

Get a point's IANA timezone (for example Europe/Istanbul), its current UTC offset, whether daylight saving time is in effect, and the local time. Where zones overlap, every candidate is listed; on the open sea there is no guess.

250 country and dependency profiles

Each country comes with ISO codes, calling codes, currencies, languages, timezones and administrative levels, with how far each level is covered.

Country, state and district lists for address forms

Fill dropdowns from one endpoint: country → state → district → neighborhood. Worldwide there are about 3,900 first-level regions (states, provinces) in 226 countries. In Turkey: all 81 provinces (il), all 973 districts (ilçe) and about 50,000 neighborhoods (mahalle) and villages (köy) from TÜİK's official list; the data is kept up to date from official and open sources.

Postal code lookup

Find the places of a postal code and the postal codes nearest to a point. About 120 countries are covered (GeoNames, CC BY 4.0); for the United Kingdom, Canada and the Netherlands only the first part of the code is available. Turkish codes are linked to their district.

Population

Countries, regions, Turkey's provinces and districts and nearby places come with their population (GeoNames). Most neighborhoods have none.

Place search as you type

Finds places by the first letters of their name; case, diacritics and Turkish ı/İ are ignored. Search can be limited to one country, and each candidate comes with its parents.

Full path of a place

Get a place's name, type, centre coordinate and its ancestors from the country down (path) by its ID: a neighborhood in Kadıköy has the path Türkiye › İstanbul › Kadıköy.

Boundaries as GeoJSON

A country, state or district boundary comes as one GeoJSON Feature, ready for MapLibre and Leaflet. Three levels of detail: overview map, city view and source geometry.

Vector map tiles (PMTiles)

Country and region boundaries worldwide, plus Turkey's provinces, districts and neighborhoods, are served as PMTiles files; the map draws without an API key.

Phone number validation

Tells whether a number is valid and its line type (mobile, fixed line), and returns it in E.164, national and international format.

Multilingual place names

Names come in the local language; the lang parameter (for example lang=en,de) adds names in other languages. Place names exist in more than 600 language tags, country and currency names in more than 300 languages. Coverage varies by language: German, French, English, Spanish and Turkish have thousands of place names each, and a missing name comes back as null.

Stable IDs

IDs such as TR and TR-34 are kept across data updates. A retired ID answers 410 with the ID that replaced it (replaced_by), so stored records keep working.

Versioned open data, OpenAPI and stable error codes

Every reply carries the data version and attribution; sources and licences are in /v1/meta. The whole contract is in the OpenAPI document, and every error has a fixed code.

Responses in milliseconds

The data sits ready on the server, so queries return in milliseconds. Lists can be cached per data version.

Start in 3 steps

  1. Keep the key on your own server; every /v1 call needs an Authorization: Bearer header. Never put the key in the browser.
  2. Send a GET request. Every action in the demo gives its requests as curl, Node and Python code.
  3. Read the reply: {data, meta}. meta carries the data version and attribution; errors return {status: "failed", code}. Cache lists per data version.
curl -H "Authorization: Bearer $GEO_API_KEY" "$GEO_API_URL/v1/contains?lat=41.0082&lon=28.9784"

Every endpoint, parameter and response schema is in the OpenAPI document. · API reference · openapi.json

Use cases

One page per job: what it returns, a real request and response, the price and common questions.