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.
| Ad | Tür | Aralık / açıklama | Varsayılan |
|---|---|---|---|
| q | string | Zorunlu; trim sonrası 1–256 Unicode karakter, kontrol karakteri yok | — |
| limit | integer | 1–10 | 5 |
| language | string | tr veya en | tr |
| proximity | lon,lat | boylam −180…180, enlem −90…90; yakınlık referansı | yok |
| bbox | west,south,east,north | boylam −180…180, enlem −90…90; west < east, south < north | yok |
GET /v1/geocode/reverse
En yakın eşleşmeyi arar; sıfır veya bir sonuç döner.
| Ad | Tür | Aralık / açıklama | Varsayılan |
|---|---|---|---|
| lon | number | Zorunlu; −180…180 | — |
| lat | number | Zorunlu; −90…90 | — |
| language | string | tr veya en | tr |
| radius_m | integer | 1–1000 metre | 100 |
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.
| Ad | Tür | Aralık / açıklama | Varsayılan |
|---|---|---|---|
| waypoints | array | Zorunlu; tam iki {lon, lat} noktası, sıralı | — |
| waypoints[].lon | number | Zorunlu; −180…180 | — |
| waypoints[].lat | number | Zorunlu; −90…90 | — |
| mode | string | driving veya motorcycle | driving |
| geometry | string | none, polyline5 veya geojson | none |
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.
| Ad | Tür | Aralık / açıklama | Varsayılan |
|---|---|---|---|
| province | string | Listeden il adı; district verilirse zorunlu | yok |
| district | string | Listeden 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.
| Ad | Tür | Aralık / açıklama | Varsayılan |
|---|---|---|---|
| province | string | Zorunlu; listeden il adı | — |
| district | string | Listeden ilçe adı; neighbourhood_id verilirse zorunlu | yok |
| neighbourhood_id | string | Mahalle listesindeki id | yok |
| simplify | integer | 0–1000 metre sadeleştirme toleransı; 0 sadeleştirmez | province 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.
| HTTP | code | retryable | Anlam |
|---|---|---|---|
| 400 | invalid_request | false | Geçersiz parametre veya body |
| 401 | unauthorized | false | Key eksik veya geçersiz; WWW-Authenticate: Bearer |
| 402 | payment_required | false | Kullanım kredisi bitti |
| 403 | no_plan | false | Projenin planı yok |
| 404 | not_found | false | Endpoint veya sürüm bulunamadı |
| 405 | method_not_allowed | false | Method desteklenmiyor; Allow header |
| 413 | payload_too_large | false | Body sınırı aşıldı |
| 414 | uri_too_long | false | URI sınırı aşıldı |
| 415 | unsupported_media_type | false | Content-Type veya Content-Encoding geçersiz |
| 404 | area_not_found | false | İdari alan bulunamadı veya kapsam dışında |
| 422 | geometry_too_large | false | Sınır yanıt sınırını aşıyor; simplify değerini artırın |
| 422 | location_out_of_coverage | false | Koordinat coverage dışında |
| 422 | location_not_routable | false | Yakında uygun yol yok veya snap 1000 m üzerinde |
| 422 | route_not_found | false | Rota bulunamadı |
| 422 | route_too_long | false | Rota uzunluk sınırı aşıldı |
| 429 | rate_limited | true | Hız limiti aşıldı |
| 429 | quota_exceeded | true | Günlük kota doldu |
| 503 | service_unavailable | true | Bağımlılık geçici olarak erişilemiyor |
| 503 | server_busy | true | Kapasite dolu |
| 503 | service_timeout | true | Zaman aşımı |
| 503 | service_error | true | Geç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.
| Header | Anlam / birim |
|---|---|
| X-Request-Id | 32 küçük hex karakter; body request_id ile aynı, her istekte yeni |
| X-RateLimit-Limit | Key başına token bucket kapasitesi (burst) |
| X-RateLimit-Remaining | Bu denemeden sonra kalan tam token sayısı |
| X-RateLimit-Reset | Bucket tamamen dolacağı zaman; Unix epoch saniye |
| X-Quota-Limit | Projenin günlük kotası |
| X-Quota-Remaining | Yanıt anında kalan kota; bekleyen rezervasyonlar dahil |
| X-Quota-Reset | Sonraki UTC 00:00; Unix epoch saniye |
| X-Quota-Overage | Soft policy ile kota aşılmışsa true |
| Retry-After | 429 ve 503 için bekleme süresi, saniye |
| X-Geo-Cache | Cache 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.