Geliştirici

Geo API referansı: il, ilçe, mahalle ve koordinat uçları

Türkiye'de 81 il, 973 ilçe ve TÜİK'in resmî listesindeki yaklaşık 50.000 mahalle ile köy; dünya genelinde ülkeler ve bölgeler. Veriler resmî ve açık kaynaklardan güncel tutulur; mahalle sınırları kısmi kapsamdadır. Bu sayfa canlı API sözleşmesinin tarayıcıda okunabilir özetidir.

Temel URL ve kimlik doğrulama

Tüm /v1 uç noktaları tek taban adresinde çalışır.

  • Anahtarsız (x-worker-keyless) uçlar: Without Authorization: 1000 requests per IPv4 address or IPv6 /64 per UTC day across the keyless routes.
  • Diğer uçlar: Authorization: Bearer <API anahtarı>. Başarılı yanıtlar {data, meta}; hatalar {status: failed, code} biçimindedir.

Apify Store ücretleri (doğrudan API anahtarı fiyatı yayımlanmaz), her biri 1.000 çağrı başına: referans ve liste satırları 0,10 USD; koordinat 0,30 USD; sınır (overview/standard) 1,00 USD; tam sınır (full) 3,00 USD; ayrıca çalıştırma başına 0,001 USD.

Uç noktalar

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

GET/health

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

Örnek istek

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

Örnek yanıt

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

This document

Örnek istek

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

Örnek yanıt

                { "openapi": "3.1.0", … }
              
GET/v1/metaAnahtarsız

Dataset version, public tileset URLs, sources and licences

Örnek istek

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

Örnek yanıt

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/countriesAnahtarsız

All countries and dependencies with their profile

Parametreler

AdKonumZorunluAçıklama
langqueryHayırComma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language.

Örnek istek

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

Örnek yanıt

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/countries/{cc}Anahtarsız

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

Parametreler

AdKonumZorunluAçıklama
ccpathEvet
langqueryHayırComma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language.

Örnek istek

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

Örnek yanıt

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/placesAnahtarsız

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

Parametreler

AdKonumZorunluAçıklama
parentqueryHayırCountry, 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.
qqueryHayırName prefix (e.g. kuşa); case, diacritics and Turkish i/ı are ignored
countryqueryHayırOnly with q, e.g. TR
langqueryHayırComma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language.
limitqueryHayırDefault 1000 for parent, 20 (max 100) for q
offsetqueryHayır

Örnek istek

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

Örnek yanıt

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/places/{id}Anahtarsız

One place with its path (ancestors, country first)

Parametreler

AdKonumZorunluAçıklama
idpathEvet
langqueryHayırComma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language.

Örnek istek

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

Örnek yanıt

                {
  "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.

Parametreler

AdKonumZorunluAçıklama
idpathEvet
detailqueryHayıroverview is for country and region maps, standard for a city view, full is the source geometry

Örnek istek

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

Örnek yanıt

                {
  "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

Parametreler

AdKonumZorunluAçıklama
latqueryEvet
lonqueryEvet

Örnek istek

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

Örnek yanıt

                {
  "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

Parametreler

AdKonumZorunluAçıklama
latqueryEvet
lonqueryEvet

Örnek istek

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

Örnek yanıt

                {
  "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

Parametreler

AdKonumZorunluAçıklama
latqueryEvet
lonqueryEvet
limitqueryHayırDefault 10
radiusqueryHayırKilometres, default 100; places farther away are not returned
langqueryHayırComma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language.

Örnek istek

                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"
              

Örnek yanıt

                {
  "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

Parametreler

AdKonumZorunluAçıklama
countryqueryEvet
codequeryEvet
limitqueryHayırDefault 100
offsetqueryHayır

Örnek istek

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

Örnek yanıt

                {
  "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

Parametreler

AdKonumZorunluAçıklama
latqueryEvet
lonqueryEvet
limitqueryHayırDefault 10
radiusqueryHayırKilometres, default 50

Örnek istek

                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"
              

Örnek yanıt

                {
  "data": { … },
  "meta": {
    "dataset_version": "…",
    "attribution": "…"
  }
}
              
GET/v1/phoneAnahtarsız

Validate and format a phone number

Parametreler

AdKonumZorunluAçıklama
numberqueryEvetSend a leading + as %2B
countryqueryHayırDefault region for numbers without a + prefix

Örnek istek

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

Örnek yanıt

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

Hata kodları

Her hata sabit bir code değeri döner; OpenAPI şeması ile aynı küme.

        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