Developers

Geo API reference: places, boundaries and reverse geocoding endpoints

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.

Base URL and authentication

All /v1 endpoints share one base URL.

  • Keyless routes (x-worker-keyless): Without Authorization: 1000 requests per IPv4 address or IPv6 /64 per UTC day across the keyless routes.
  • Other routes: Authorization: Bearer <API key>. Success responses are {data, meta}; errors are {status: failed, code}.

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.

Endpoints

Base URL: https://api.forlab.io/geo

GET/health

Readiness: 200 once a dataset is loaded, 503 NOT_READY before

Example request

                curl "https://api.forlab.io/geo/health"
              

Example response

                { "status": "ok" }
              
GET/openapi.json

This document

Example request

                curl "https://api.forlab.io/geo/openapi.json"
              

Example response

                { "openapi": "3.1.0", … }
              
GET/v1/metaKeyless

Dataset version, public tileset URLs, sources and licences

Example request

                curl "https://api.forlab.io/geo/v1/meta"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/countriesKeyless

All countries and dependencies with their profile

Parameters

NameInRequiredDescription
langqueryNoComma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language.

Example request

                curl "https://api.forlab.io/geo/v1/countries?lang=tr%2Cen"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/countries/{cc}Keyless

One country: names, calling codes, currencies, languages, timezones, levels with coverage

Parameters

NameInRequiredDescription
ccpathYes
langqueryNoComma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language.

Example request

                curl "https://api.forlab.io/geo/v1/countries/TR?lang=tr%2Cen"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/placesKeyless

Children of a place (`parent`) or a name prefix search (`q`); exactly one of the two

Parameters

NameInRequiredDescription
parentqueryNoCountry, 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.
qqueryNoName prefix (e.g. kuşa); case, diacritics and Turkish i/ı are ignored
countryqueryNoOnly with q, e.g. TR
langqueryNoComma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language.
limitqueryNoDefault 1000 for parent, 20 (max 100) for q
offsetqueryNo

Example request

                curl "https://api.forlab.io/geo/v1/places?parent=TR-35&lang=tr%2Cen&limit=10&offset=0"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/places/{id}Keyless

One place with its path (ancestors, country first)

Parameters

NameInRequiredDescription
idpathYes
langqueryNoComma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language.

Example request

                curl "https://api.forlab.io/geo/v1/places/TR-35?lang=tr%2Cen"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/places/{id}/boundary

The 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.

Parameters

NameInRequiredDescription
idpathYes
detailqueryNooverview is for country and region maps, standard for a city view, full is the source geometry

Example request

                curl \
  -H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/places/TR-35/boundary?detail=overview"
              

Example response

                {
  "type": "Feature",
  "geometry": { "type": "Polygon", "coordinates": [ … ] },
  "properties": {
    "id": "TR-35",
    "name": "İzmir",
    "detail": "overview",
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/contains

Every 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

Parameters

NameInRequiredDescription
latqueryYes
lonqueryYes

Example request

                curl \
  -H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/contains?lat=38.4237&lon=27.1428"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/timezone

IANA 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

Parameters

NameInRequiredDescription
latqueryYes
lonqueryYes

Example request

                curl \
  -H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/timezone?lat=38.4237&lon=27.1428"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/nearby

The 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

Parameters

NameInRequiredDescription
latqueryYes
lonqueryYes
limitqueryNoDefault 10
radiusqueryNoKilometres, default 100; places farther away are not returned
langqueryNoComma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language.

Example request

                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"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/postal

The 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

Parameters

NameInRequiredDescription
countryqueryYes
codequeryYes
limitqueryNoDefault 100
offsetqueryNo

Example request

                curl \
  -H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/postal?country=TR&code=35030&limit=10&offset=0"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/postal/nearby

The postal codes nearest to a point (GeoNames), nearest first, with distance in km. 503 NOT_READY on a dataset built before the feature

Parameters

NameInRequiredDescription
latqueryYes
lonqueryYes
limitqueryNoDefault 10
radiusqueryNoKilometres, default 50

Example request

                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"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/phoneKeyless

Validate and format a phone number

Parameters

NameInRequiredDescription
numberqueryYesSend a leading + as %2B
countryqueryNoDefault region for numbers without a + prefix

Example request

                curl "https://api.forlab.io/geo/v1/phone?number=%2B905321234567&country=TR"
              

Example response

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              

Error codes

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