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 —
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.
Country → province → district → neighborhood lists for an address form. The neighborhood list is partial; not every neighborhood is there.
Click the map or pick an example to select a place.
A country's codes, calling code, currency, language, timezone and administrative levels.
Pick a country.
A point's timezone, UTC offset, daylight saving time and local time. Click the map or pick an example.
Which places does a postal code belong to? Click the map to get the postal codes nearest to the point.
Click the map: the 5 postal codes nearest to the point appear.
About 120 countries; for the United Kingdom, Canada and the Netherlands only the first part of the code (for example SW1A). Source: GeoNames (CC BY 4.0).
The selected place's boundary as map-ready GeoJSON, and every boundary as vector tiles from one file.
Select a place first, or click an example.
Vector tiles
Every boundary sits in one PMTiles file; no key needed, and the browser downloads only the part in view. The URL carries the data version and is cached for a year. The URLs are in the /v1/meta reply.
import maplibregl from "maplibre-gl";
import { Protocol } from "pmtiles";
maplibregl.addProtocol("pmtiles", new Protocol().tile);
new maplibregl.Map({
container: "map",
style: {
version: 8,
sources: { tr: { type: "vector", url: "pmtiles://https://…/TR.pmtiles" } },
layers: [{ id: "il", type: "line", source: "tr", "source-layer": "il" }],
},
});Is the number valid, what are its E.164 and national formats, which line type?
If the number doesn't start with +, enter its country as two letters (TR, DE…).An ID you store survives data updates, and every error comes with a fixed code.
ID formats
- country: ISO 3166-1 code
- province: ISO 3166-2 code
- everything else: country code + 8 characters (Kadıköy district)
Error contract
400 INVALID_REQUEST- A parameter is missing or malformed.
401 UNAUTHORIZED- No key, or a wrong one.
404 NOT_FOUND- No place ever had this ID.
404 BOUNDARY_UNAVAILABLE- The place exists but has no boundary.
410 PLACE_RETIRED- The ID was retired; replaced_by names the new one.
429 RATE_LIMITED- Too many requests; try again shortly.
503 NOT_READY- No data loaded yet.
Retired ID sample
When a place changes in the source data, its old ID is not dropped: it answers 410 PLACE_RETIRED with the new one in replaced_by. The live data has no retired ID yet; the reply below is a sample of a real change (Mali, Bamako region).
GET /v1/places/ML-20 → 410
{ "status": "failed", "code": "PLACE_RETIRED", "replaced_by": "ML-BKO" }Sources and licences
Data version — · Every reply also carries them in its meta field.
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
- Keep the key on your own server; every /v1 call needs an Authorization: Bearer header. Never put the key in the browser.
- Send a GET request. Every action in the demo gives its requests as curl, Node and Python code.
- 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.