Turkey province, district and neighborhood list API
Fill the province → district → neighborhood dropdowns of an address form from one endpoint. Geo API serves 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 as JSON, each with a stable ID. The data is kept up to date from official and open sources.
How it works
/v1/places?parent= returns one level below a place: parent=TR gives the 81 provinces, parent=TR-34 the 39 districts of Istanbul, and a district's ID its neighborhoods and villages. Each row has an ID, a name, a type, the local type (il, ilçe, mahalle, köy) and a level.
The list, search and place detail endpoints work without a key: 1,000 requests per IPv4 address or IPv6 /64 per UTC day free, shared across all keyless routes (meta, countries, countries/{cc}, places, places/{id}, phone). The X-RateLimit-Remaining header shows what is left. For higher volume or calls from a server, use an API key or the Apify Actor.
Stable IDs and the official list
Provinces carry their ISO 3166-2 code (Istanbul is TR-34). Districts, neighborhoods and villages have a stable ID made of TR- plus 8 characters (for example TR-PG39B8X4); a neighborhood's ID is never given to another place. Store the ID rather than the name: the record keeps pointing at the same place even if the name changes.
Neighborhoods and villages come from TÜİK's address-based population register (ADNKS); each row's local_type says mahalle or köy. The Dörtdivan district of Bolu has 8 neighborhoods and 24 villages; metropolitan districts such as Şile in Istanbul have neighborhoods only.
Search as you type and a place's full path
For search as you type, use /v1/places?q=kadikoy&country=TR: case, diacritics and Turkish ı/İ are ignored, and each candidate comes with its parents. /v1/places/{id} gives a place's name, centre coordinate, population and, in path, its ancestors from the country down: a neighborhood in Kadıköy has the path Türkiye › İstanbul › Kadıköy.
The same endpoint works worldwide: parent=DE lists Germany's states. There are about 3,900 first-level regions (states, provinces) in 226 countries.
Example request and response
The first four neighborhoods and villages of the Dörtdivan district in Bolu. No key needed; meta.total gives the full count (32), page with limit and offset.
Request
curl "https://api.forlab.io/geo/v1/places?parent=TR-7N6BAMXN&limit=4"Response excerpt
{
"data": [
{ "id": "TR-PG39B8X4", "name": "Adakınık", "type": "neighborhood", "local_type": "mahalle", "level": 3 },
{ "id": "TR-72TKWWHE", "name": "Adaköy", "type": "neighborhood", "local_type": "köy", "level": 3 },
{ "id": "TR-VPG03CA4", "name": "Aşağıdüğer", "type": "neighborhood", "local_type": "köy", "level": 3 },
{ "id": "TR-36WGHZ2G", "name": "Aşağısayık", "type": "neighborhood", "local_type": "köy", "level": 3 }
],
"meta": { "total": 32, "limit": 4, "offset": 0, … }
}The same job with the Apify Actor
Without a key, or for a batch, give the Geo Reference Actor a list: each item becomes one result row that keeps the value you sent. Example input:
{"operation": "places", "items": [{"parent": "TR"}, {"parent": "TR-14"}]}What it costs
- Without a key: 1,000 requests per IPv4 address or IPv6 /64 per UTC day free, shared across all keyless routes (meta, countries, countries/{cc}, places, places/{id}, phone).
- Apify Actor, lists (places operation): $0.10 per 1,000 rows returned.
- Apify Actor, single place detail (place operation): $0.10 per 1,000 lookups.
On Apify you pay as you go: only answered lookups are charged, items that cannot become a request are free, and each run adds a $0.001 start fee. The Apify free plan's $5 monthly credit covers about 16,000 coordinate lookups. For a direct API key, email api@forlab.io.
Frequently asked questions
Is the neighborhood list complete?
Yes. Neighborhoods and villages come from TÜİK's official list: all 81 provinces, all 973 districts and all of the about 50,000 neighborhoods and villages are there. meta.coverage.neighborhood: "partial" in the reply is about boundaries, not the list; only some neighborhoods have a map boundary.
Are villages included?
Yes. Villages sit at the same level as neighborhoods, under their district, with local_type köy. A belde is not a separate level; it is a field in the detail of a neighborhood or village (/v1/places/{id}).
Do the IDs change?
No. Provinces carry their ISO code and the other units have stable IDs. If a unit is removed, its ID is never reused; a lookup returns PLACE_RETIRED with the ID that replaces it (replaced_by).
Can I use it for free?
Lists and search work without a key: 1,000 requests per IPv4 address or IPv6 /64 per UTC day free, shared across all keyless routes (meta, countries, countries/{cc}, places, places/{id}, phone). For more, use the Geo Reference Actor on Apify or ask for a key at api@forlab.io.