/healthReadiness: 200 once a dataset is loaded, 503 NOT_READY before
Example request
curl "https://api.forlab.io/geo/health"
Example response
{ "status": "ok" }
81 provinces (il), 973 districts (ilçe) and about 50,000 official TÜİK neighborhoods (mahalle) and villages (köy) in Turkey, plus countries and regions worldwide. Data is kept up to date from official and open sources; neighborhood boundaries are only partially covered. This page is a crawlable summary of the live API contract.
All /v1 endpoints share one base URL.
Apify Store pricing (no public direct API key pricing), each per 1,000 calls: reference lookups and list rows $0.10; coordinate $0.30; boundary (overview/standard) $1.00; full boundary $3.00; plus $0.001 per run start.
Base URL: https://api.forlab.io/geo
/healthReadiness: 200 once a dataset is loaded, 503 NOT_READY before
curl "https://api.forlab.io/geo/health"
{ "status": "ok" }
/openapi.jsonThis document
curl "https://api.forlab.io/geo/openapi.json"
{ "openapi": "3.1.0", … }
/v1/metaKeylessDataset version, public tileset URLs, sources and licences
curl "https://api.forlab.io/geo/v1/meta"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
/v1/countriesKeylessAll countries and dependencies with their profile
| Name | In | Required | Description |
|---|---|---|---|
lang | query | No | Comma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language. |
curl "https://api.forlab.io/geo/v1/countries?lang=tr%2Cen"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
/v1/countries/{cc}KeylessOne country: names, calling codes, currencies, languages, timezones, levels with coverage
| Name | In | Required | Description |
|---|---|---|---|
cc | path | Yes | |
lang | query | No | Comma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language. |
curl "https://api.forlab.io/geo/v1/countries/TR?lang=tr%2Cen"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
/v1/placesKeylessChildren of a place (`parent`) or a name prefix search (`q`); exactly one of the two
| Name | In | Required | Description |
|---|---|---|---|
parent | query | No | Country, region (il), county (ilçe) ID. An ilçe lists its official mahalle and köy (TÜİK); places off that list are not children. |
q | query | No | Name prefix (e.g. kuşa); case, diacritics and Turkish i/ı are ignored |
country | query | No | Only with q, e.g. TR |
lang | query | No | Comma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language. |
limit | query | No | Default 1000 for parent, 20 (max 100) for q |
offset | query | No |
curl "https://api.forlab.io/geo/v1/places?parent=TR-35&lang=tr%2Cen&limit=10&offset=0"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
/v1/places/{id}KeylessOne place with its path (ancestors, country first)
| Name | In | Required | Description |
|---|---|---|---|
id | path | Yes | |
lang | query | No | Comma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language. |
curl "https://api.forlab.io/geo/v1/places/TR-35?lang=tr%2Cen"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
/v1/places/{id}/boundaryThe boundary as one GeoJSON Feature (application/geo+json, not wrapped in `data`), ready for MapLibre. properties: id, name, detail, dataset_version, attribution. Sent gzip-compressed when the client accepts gzip.
| Name | In | Required | Description |
|---|---|---|---|
id | path | Yes | |
detail | query | No | overview is for country and region maps, standard for a city view, full is the source geometry |
curl \
-H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/places/TR-35/boundary?detail=overview"
{
"type": "Feature",
"geometry": { "type": "Polygon", "coordinates": [ … ] },
"properties": {
"id": "TR-35",
"name": "İzmir",
"detail": "overview",
"dataset_version": "…",
"attribution": "…"
}
}
/v1/containsEvery unit whose land contains the point (country, region, county; in Turkey also mahalle), most general first; match is none at sea or outside the loaded countries
| Name | In | Required | Description |
|---|---|---|---|
lat | query | Yes | |
lon | query | Yes |
curl \
-H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/contains?lat=38.4237&lon=27.1428"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
/v1/timezoneIANA timezone of a point (timezone-boundary-builder polygons: land and territorial waters) with the current UTC offset, DST flag and local time; match is none on the open sea. `dst` is true when the zone's clocks are advanced at that instant: its offset is the larger of the two it shows in that year (1 January and 1 July); a zone with one offset all year is never DST (Morocco: +01:00 and the +00:00 of Ramadan are both `dst: false`). When zones share an edge or overlap, `ambiguous` is true, `timezone` and the other fields are the first zone by name and `candidates` lists all of them (each with its own offset, dst and local time). 503 NOT_READY on a dataset built before the feature
| Name | In | Required | Description |
|---|---|---|---|
lat | query | Yes | |
lon | query | Yes |
curl \
-H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/timezone?lat=38.4237&lon=27.1428"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
/v1/nearbyThe nearest populated places (GeoNames cities500: 500 inhabitants or more, or a seat of government) with distance in km, population and path, nearest first. 503 NOT_READY on a dataset built before the feature
| Name | In | Required | Description |
|---|---|---|---|
lat | query | Yes | |
lon | query | Yes | |
limit | query | No | Default 10 |
radius | query | No | Kilometres, default 100; places farther away are not returned |
lang | query | No | Comma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language. |
curl \
-H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/nearby?lat=38.4237&lon=27.1428&limit=10&radius=50&lang=tr%2Cen"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
/v1/postalThe places of a postal code (GeoNames); case, spaces and hyphens in the code are ignored. `partial` is true for the countries GeoNames gives only in part (CA, NL, GB: first part; CL, CN, AR: first digits; IE, MT: first letters; BR: major codes). 503 NOT_READY on a dataset built before the feature
| Name | In | Required | Description |
|---|---|---|---|
country | query | Yes | |
code | query | Yes | |
limit | query | No | Default 100 |
offset | query | No |
curl \
-H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/postal?country=TR&code=35030&limit=10&offset=0"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
/v1/postal/nearbyThe postal codes nearest to a point (GeoNames), nearest first, with distance in km. 503 NOT_READY on a dataset built before the feature
| Name | In | Required | Description |
|---|---|---|---|
lat | query | Yes | |
lon | query | Yes | |
limit | query | No | Default 10 |
radius | query | No | Kilometres, default 50 |
curl \
-H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/postal/nearby?lat=38.4237&lon=27.1428&limit=10&radius=50"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
/v1/phoneKeylessValidate and format a phone number
| Name | In | Required | Description |
|---|---|---|---|
number | query | Yes | Send a leading + as %2B |
country | query | No | Default region for numbers without a + prefix |
curl "https://api.forlab.io/geo/v1/phone?number=%2B905321234567&country=TR"
{
"data": { … },
"meta": {
"dataset_version": "…",
"attribution": "…"
}
}
Every error returns a stable code; same set as the OpenAPI schema.
INVALID_REQUEST
UNAUTHORIZED
NOT_FOUND
METHOD_NOT_ALLOWED
REQUEST_TIMEOUT
PLACE_RETIRED
PAYLOAD_TOO_LARGE
RATE_LIMITED
CAPACITY_EXCEEDED
INTERNAL_ERROR
NOT_READY
BOUNDARY_UNAVAILABLE