Giriş yap

GELİŞTİRİCİ BELGELERİ · v1

Geo API

Geo, Türkiye için adres arama, koordinattan adres bulma ve driving araç rotası sunan bir konum API’sidir. Base URL: https://geo.midp.io.

Veri kaynakları

Yer verileri, Overture Maps Foundation verilerini (CDLA-Permissive-2.0) ve Foursquare Open Source Places verilerini (Apache License 2.0) içerir. Ayrıca Konya Büyükşehir Belediyesi Açık Veri Platformu — Mahalle-Cadde-Sokak İsim Listesi verisini (CC BY 4.0, biçimi düzenlenerek) içerir. Ayrıca Trabzon Büyükşehir Belediyesi Açık Veri Platformu yol bazlı numarataj verisini (Trabzon Açık Veri Lisansı, biçimi düzenlenerek) içerir. Ayrıca Kadıköy Belediyesi Açık Veri — Kadıköy Sokak ve Cadde Bilgisi verisini (CC BY 4.0, biçimi düzenlenerek) içerir. Ayrıca Denizli Büyükşehir Belediyesi Açık Veri — Denizli İlçelerine Ait CSBM Adı ve Türleri verisini (Denizli Açık Veri Lisansı, biçimi düzenlenerek) içerir. Ayrıca Kayseri Büyükşehir Belediyesi Açık Veri — İlçe CSBM Listeleri verisini (CC BY 4.0, biçimi düzenlenerek) içerir. Ayrıca Sivas Belediyesi Açık Veri — Sokak Verileri ve Mahalle Sınırı Haritası verilerini (Sivas Açık Veri Lisansı, biçimi düzenlenerek) içerir.

Foursquare OS Places Notice

© 2026 Foursquare Labs, Inc. All rights reserved.

The Foursquare OS Places dataset (the “Data”) is licensed under the Apache License, Version 2.0 (the “License”). You may not use, modify, or distribute the Data except in compliance with the License.

As set forth more fully in the License, if you use, modify, or distribute the Data, you must:
– provide recipients with a copy of the License.
– if applicable, include prominent notices to the extent you’ve changed the Data.
– preserve attribution to Foursquare, including preserving the full content of this NOTICE.txt file.

To ensure appropriate attribution to Foursquare, we recommend the following:
– if using/distributing the Data in flat file form as-is or after making changes/modifications: include this NOTICE.txt file, which may be modified to include an additional notice of your changes/modifications, if any.
– if using/distributing the Data in API form as-is or after making changes/modifications: include a copy of the content from this NOTICE.txt file prominently in your developer documentation for such API, which may be modified to include an additional notice of your changes/modifications, if any.

You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, the Data distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Kimlik doğrulama

Konsola giriş yapın, projeniz için API key oluşturun ve her istekte Authorization: Bearer header’ı gönderin. Key’i yalnız sunucuda secret olarak saklayın; kaynak koduna, tarayıcıya, mobil uygulamaya veya loglara koymayın. CORS desteği yoktur; çağrıları backend üzerinden yapın.

Ücretlendirme

Her kişiye ilk 1.000 başarılı istek ücretsizdir (tek seferlik); günlük ücretsiz kota yoktur. Kredi bittiğinde API 402 payment_required döner. Başarılı (2xx) 1.000 istek 1 USD’dir; search, reverse, route ve boundaries aynı fiyattır. 4xx/5xx ücretlendirilmez. Dönem UTC takvim ayıdır; aylık tutar konsolun Billing sayfasında görünür.

Endpoint ve parametreler

GET /v1/geocode/search

Adres veya yer arar. Sonuç yoksa 200 ve boş results döner. Query parametreleri URL encoded olmalıdır.

AdTürAralık / açıklamaVarsayılan
qstringZorunlu; trim sonrası 1–256 Unicode karakter, kontrol karakteri yok—
limitinteger1–105
languagestringtr veya entr
proximitylon,latboylam −180…180, enlem −90…90; yakınlık referansıyok
bboxwest,south,east,northboylam −180…180, enlem −90…90; west < east, south < northyok

GET /v1/geocode/reverse

En yakın eşleşmeyi arar; sıfır veya bir sonuç döner.

AdTürAralık / açıklamaVarsayılan
lonnumberZorunlu; −180…180—
latnumberZorunlu; −90…90—
languagestringtr veya entr
radius_minteger1–1000 metre100

POST /v1/route

JSON body gönderin; query parametresi kabul edilmez. İki nokta farklı olmalıdır. Content-Type: application/json (isteğe bağlı UTF-8 charset); Content-Encoding kabul edilmez.

AdTürAralık / açıklamaVarsayılan
waypointsarrayZorunlu; tam iki {lon, lat} noktası, sıralı—
waypoints[].lonnumberZorunlu; −180…180—
waypoints[].latnumberZorunlu; −90…90—
modestringdriving veya motorcycledriving
geometrystringnone, polyline5 veya geojsonnone

GET /v1/boundaries

Seçilebilir idari alanları listeler: parametresiz il (province), province ile ilçe (district), province ve district ile mahalle (neighbourhood) listesi. Ad değerlerini bu listeden aynen geri gönderin. Yanıt: level (province, district, neighbourhood), results[] (name; mahallede ayrıca opaque id), request_id.

AdTürAralık / açıklamaVarsayılan
provincestringListeden il adı; district verilirse zorunluyok
districtstringListeden ilçe adıyok

GET /v1/boundaries/geometry

Seçilen il, ilçe veya mahallenin sınırını GeoJSON Feature olarak döner: geometry (Polygon veya MultiPolygon, [lon,lat]), bbox: [west,south,east,north], properties (level, province, district, name, mahallede id, area_km2, simplify_m, approximate) ve request_id. approximate: true, sınırın bir kısmının tahmini olduğunu belirtir. İl ve ilçe sınırları mahallelerin birleşimidir.

AdTürAralık / açıklamaVarsayılan
provincestringZorunlu; listeden il adı—
districtstringListeden ilçe adı; neighbourhood_id verilirse zorunluyok
neighbourhood_idstringMahalle listesindeki idyok
simplifyinteger0–1000 metre sadeleştirme toleransı; 0 sadeleştirmezprovince 50, district 10, neighbourhood 0

Bilinmeyen, boş veya tekrarlanan parametreler reddedilir. GET body kabul etmez.

Hızlı başlangıç

Örneklerde GEO_API_KEY sunucunun ortam değişkenidir. Her örnek üç endpoint’i çağırır.

curl

curl -G 'https://geo.midp.io/v1/geocode/search' -H "Authorization: Bearer $GEO_API_KEY" --data-urlencode 'q=Moda Caddesi Kadıköy' --data-urlencode 'limit=3'
curl -G 'https://geo.midp.io/v1/geocode/reverse' -H "Authorization: Bearer $GEO_API_KEY" --data-urlencode 'lon=29.0262' --data-urlencode 'lat=40.9845'
curl 'https://geo.midp.io/v1/route' -H "Authorization: Bearer $GEO_API_KEY" -H 'Content-Type: application/json' --data '{"waypoints":[{"lon":29.025,"lat":40.985},{"lon":29.03,"lat":40.99}]}' 

Python · requests

import os
import requests

base = "https://geo.midp.io"
headers = {"Authorization": "Bearer " + os.environ["GEO_API_KEY"]}
search = requests.get(base + "/v1/geocode/search", headers=headers, params={"q": "Moda Caddesi Kadıköy", "limit": 3}, timeout=15)
reverse = requests.get(base + "/v1/geocode/reverse", headers=headers, params={"lon": 29.0262, "lat": 40.9845}, timeout=15)
route = requests.post(base + "/v1/route", headers=headers, json={"waypoints": [{"lon": 29.025, "lat": 40.985}, {"lon": 29.03, "lat": 40.99}]}, timeout=15)
for response in (search, reverse, route):
    response.raise_for_status()
    print(response.json())

JavaScript · server-side Node.js fetch

const base = "https://geo.midp.io";
const headers = { Authorization: `Bearer ${process.env.GEO_API_KEY}` };
const search = new URL(base + "/v1/geocode/search");
search.search = new URLSearchParams({ q: "Moda Caddesi Kadıköy", limit: "3" });
const reverse = new URL(base + "/v1/geocode/reverse");
reverse.search = new URLSearchParams({ lon: "29.0262", lat: "40.9845" });
const responses = [await fetch(search, { headers }), await fetch(reverse, { headers }),
  await fetch(base + "/v1/route", { method: "POST", headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ waypoints: [{ lon: 29.025, lat: 40.985 }, { lon: 29.03, lat: 40.99 }] }) })];
for (const response of responses) {
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  console.log(await response.json());
}

Go

package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strings"
    "time"
)

func main() {
    base := "https://geo.midp.io"
    client := &http.Client{Timeout: 15 * time.Second}
    search := url.Values{"q": {"Moda Caddesi Kadıköy"}, "limit": {"3"}}
    reverse := url.Values{"lon": {"29.0262"}, "lat": {"40.9845"}}
    calls := []struct{ method, path, body string }{
        {"GET", "/v1/geocode/search?" + search.Encode(), ""},
        {"GET", "/v1/geocode/reverse?" + reverse.Encode(), ""},
        {"POST", "/v1/route", `{"waypoints":[{"lon":29.025,"lat":40.985},{"lon":29.03,"lat":40.99}]}`},
    }
    for _, call := range calls {
        req, err := http.NewRequest(call.method, base+call.path, strings.NewReader(call.body))
        if err != nil { panic(err) }
        req.Header.Set("Authorization", "Bearer " + os.Getenv("GEO_API_KEY"))
        if call.method == "POST" { req.Header.Set("Content-Type", "application/json") }
        resp, err := client.Do(req)
        if err != nil { panic(err) }
        body, err := io.ReadAll(resp.Body)
        resp.Body.Close()
        if err != nil { panic(err) }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 { panic(fmt.Sprintf("HTTP %d: %s", resp.StatusCode, body)) }
        fmt.Println(string(body))
    }
}

Yanıt şeması ve örnekler

Geocode: results[], request_id. Her sonuç id (aynı yer için sabit, ayrıştırılmaması gereken opaque nullable string), name (nullable), label, type (address, street, area, place, other), location: {lon, lat}, nullable bbox: [west,south,east,north], address, nullable distance_m içerir. Address: nullable street, house_number, neighbourhood, district, province, postal_code, country; country_code TR’dir. distance_m proximity veya reverse referansına metre cinsinden uzaklıktır.

Route: Rota hız ve mesafe dengelenerek seçilir (en hızlı veya en kısa rota değildir); motorcycle motosiklet için hesaplanır. route içinde mode, seçilen rotanın metre cinsinden yol mesafesi distance_m, trafiksiz tahmini süre (saniye) duration_s, nullable geometry ve iki sıralı waypoint bulunur. Waypoint: input, yola eşlenen location, metre cinsinden snap_distance_m ve nullable name. Geometry none için null; polyline5 için {format, precision: 5, data: string}, geojson için {format, data: LineString} (coordinates [lon,lat]). Ayrıca request_id döner.

Aşağıdaki yanıtlar canlı probe’dan alınmıştır; search sonuç dizisi kısaltılmıştır.

Arama

{
  "results": [
    {
      "id": "plc_rqsncr73cbuv3r52qiid3t7n",
      "name": "Moda Caddesi",
      "label": "Moda Caddesi, Bahariye, Kadıköy, İstanbul, 34710, Türkiye",
      "type": "street",
      "location": {
        "lon": 29.0252216,
        "lat": 40.9879337
      },
      "bbox": [
        29.0249048,
        40.9871083,
        29.0256872,
        40.9887985
      ],
      "address": {
        "street": null,
        "house_number": null,
        "neighbourhood": "Bahariye",
        "district": "Kadıköy",
        "province": "İstanbul",
        "postal_code": "34710",
        "country": "Türkiye",
        "country_code": "TR"
      },
      "distance_m": null
    }
  ],
  "request_id": "caa759ab243f3d2c987bab2d382cddeb"
}

Ters geocoding

{
  "results": [
    {
      "id": "plc_eubo67ao27wiailhjivbxc3i",
      "name": "Ruşen Ağa Sokağı",
      "label": "Ruşen Ağa Sokağı, Moda, Kadıköy, İstanbul, 34710, Türkiye",
      "type": "street",
      "location": {
        "lon": 29.0261849,
        "lat": 40.9844285
      },
      "bbox": [
        29.0260523,
        40.9842248,
        29.0263174,
        40.9846322
      ],
      "address": {
        "street": null,
        "house_number": null,
        "neighbourhood": "Moda",
        "district": "Kadıköy",
        "province": "İstanbul",
        "postal_code": "34710",
        "country": "Türkiye",
        "country_code": "TR"
      },
      "distance_m": 8.050848364401514
    }
  ],
  "request_id": "1e95b3c75026ab644d0a8843756b31e6"
}

Rota

{
  "route": {
    "mode": "driving",
    "distance_m": 2536.963,
    "duration_s": 488.177,
    "geometry": null,
    "waypoints": [
      {
        "input": {
          "lon": 29.025,
          "lat": 40.985
        },
        "location": {
          "lon": 29.025048,
          "lat": 40.98508
        },
        "snap_distance_m": 9.765513250015507,
        "name": "Bademaltı Sokağı"
      },
      {
        "input": {
          "lon": 29.03,
          "lat": 40.99
        },
        "location": {
          "lon": 29.030013,
          "lat": 40.990026
        },
        "snap_distance_m": 3.0901216774611417,
        "name": "Kuşdili Caddesi"
      }
    ]
  },
  "request_id": "d6f4f43a6afc56e9e8a7aa298c3b37f2"
}

Hatalar ve retry

Geo hata body’si {"error":{"code":"…","message":"…","retryable":false},"request_id":"…"} biçimindedir. Kararı message yerine code ve retryable ile verin. Yalnız retryable hataları, Retry-After değerine uyarak ve artan backoff ile tekrar deneyin. Edge kaynaklı bağlantı/TLS hataları bu envelope’u taşımayabilir. Bağlantı koparsa veya Geo JSON hata envelope’u olmadan bir 5xx gelirse (örneğin edge veya proxy kaynaklı), bunu geçici kabul edip üstel backoff ile tekrar deneyin; retryable alanı yalnızca Geo envelope’larında bulunur.

HTTPcoderetryableAnlam
400invalid_requestfalseGeçersiz parametre veya body
401unauthorizedfalseKey eksik veya geçersiz; WWW-Authenticate: Bearer
402payment_requiredfalseKullanım kredisi bitti
403no_planfalseProjenin planı yok
404not_foundfalseEndpoint veya sürüm bulunamadı
405method_not_allowedfalseMethod desteklenmiyor; Allow header
413payload_too_largefalseBody sınırı aşıldı
414uri_too_longfalseURI sınırı aşıldı
415unsupported_media_typefalseContent-Type veya Content-Encoding geçersiz
404area_not_foundfalseİdari alan bulunamadı veya kapsam dışında
422geometry_too_largefalseSınır yanıt sınırını aşıyor; simplify değerini artırın
422location_out_of_coveragefalseKoordinat coverage dışında
422location_not_routablefalseYakında uygun yol yok veya snap 1000 m üzerinde
422route_not_foundfalseRota bulunamadı
422route_too_longfalseRota uzunluk sınırı aşıldı
429rate_limitedtrueHız limiti aşıldı
429quota_exceededtrueGünlük kota doldu
503service_unavailabletrueBağımlılık geçici olarak erişilemiyor
503server_busytrueKapasite dolu
503service_timeouttrueZaman aşımı
503service_errortrueGeçici hata

Header, limit ve kota

Günlük kotası olmayan planlardaki (Enterprise) projeler X-Quota-* header’larını almaz ve kota nedeniyle asla reddedilmez.

HeaderAnlam / birim
X-Request-Id32 küçük hex karakter; body request_id ile aynı, her istekte yeni
X-RateLimit-LimitKey başına token bucket kapasitesi (burst)
X-RateLimit-RemainingBu denemeden sonra kalan tam token sayısı
X-RateLimit-ResetBucket tamamen dolacağı zaman; Unix epoch saniye
X-Quota-LimitProjenin günlük kotası
X-Quota-RemainingYanıt anında kalan kota; bekleyen rezervasyonlar dahil
X-Quota-ResetSonraki UTC 00:00; Unix epoch saniye
X-Quota-OverageSoft policy ile kota aşılmışsa true
Retry-After429 ve 503 için bekleme süresi, saniye
X-Geo-CacheCache sonucu: hit veya miss; bazı yanıtlarda yok

Rate limit key başına, günlük kota proje başınadır ve UTC 00:00’da sıfırlanır. Yalnız 2xx yanıtlar kotadan sayılır; boş sonuçlar ve cache hit dahil. 4xx/5xx kota tüketmez. Header değerleri eşzamanlı isteklerde anlık görüntüdür; statik key’lerde plan/kota header’ları bulunmaz. Hard policy limiti uygular, soft policy aşımı bildirebilir.

Route body en çok 64 KiB, URI 4096 byte, yanıt 2 MiB (boundaries geometry 8 MiB). Geometry varsayılan olarak none’dur.

Kapsam

Veri Türkiye ile sınırlıdır. Coverage bbox: west 25.60, south 35.80, east 44.85, north 42.15 (lon, lat). Bbox ülke sınırı değildir; içindeki her nokta için sonuç veya yol garantisi vermez. Search bbox bu alanla kesiştirilir; kesişim yoksa boş sonuç döner. Reverse ve route için dışındaki noktalar 422 döner. İdari sınırlar Türkiye'nin 81 ilini kapsar; bulunamayan seçimler 404 area_not_found döner.

Değişiklikler ve sürümleme

2026-10-28 v1 — new endpoints, legacy paths removed.

API sürümü URL’de belirtilir; geriye uyumsuz sözleşme değişiklikleri yeni bir sürüm altında sunulur.