Geo API

Koordinattan il, ilçe ve mahalle bulma API

Bir enlem ve boylam gönderin; Geo API noktayı içeren ülkeyi, ili ve ilçeyi gerçek sınırlarla bulur, sınırı olan yerlerde mahalleyi de ekler. Buna ters coğrafi kodlama (reverse geocoding) denir: bir GPS konumunu, teslimat noktasını ya da fotoğraf koordinatını idari birime çevirir.

Nasıl çalışır

/v1/contains?lat=&lon= noktayı içeren her birimi en genelden başlayarak döndürür: ülke, il, ilçe, mahalle. Her birim kalıcı kimliği, türü ve adıyla gelir; kimlikle /v1/places/{id} uç noktasından yerin tam ayrıntısını alırsınız.

Nokta denizdeyse ya da hiçbir birimin içinde değilse yanıt match: "none" ve boş bir liste olur. En yakın yeri tahmin edip yanlış bir il döndürmek yerine bunu açıkça söyler.

Türkiye'de ve dünyada kapsam

Türkiye'de 81 il ve 973 ilçenin tamamının sınırı var; karadaki her nokta il ve ilçesine düşer. Mahalle sınırları kısmi: resmî listedeki mahallelerin yalnız bir kısmının sınırı olduğundan bazı noktalarda yanıt ilçede biter.

Dünyada ülkeler ve birinci düzey bölgeler (eyalet, il) sınırlarıyla bulunur; birçok ülkede bir alt düzey de gelir. Münih'teki bir nokta Almanya'yı, Bavyera eyaletini ve Münih ilçesini döndürür.

Ne için kullanılır

Mobil uygulamada kullanıcının konumundan il ve ilçe seçimini doldurmak, kurye ya da saha ekibi kayıtlarını ilçe bazında raporlamak, ilan veya mağaza listesindeki koordinatları idari birime bağlamak. Aynı koordinatla saat dilimini ve en yakın yerleşimleri de alabilirsiniz.

Örnek istek ve yanıt

İstanbul Kadıköy'de bir nokta: yanıt ülke, il, ilçe ve mahalleyi en genelden başlayarak verir. Bu uç nokta API anahtarı ister.

İstek

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

Yanıttan bir kesit

{
  "data": {
    "match": "found",
    "places": [
      { "id": "TR", "type": "country", "local_type": "country", "name": "Türkiye" },
      { "id": "TR-34", "type": "region", "local_type": "il", "name": "İstanbul" },
      { "id": "TR-A73FCPZ0", "type": "county", "local_type": "ilçe", "name": "Kadıköy" },
      { "id": "TR-3NF9XEBT", "type": "neighborhood", "local_type": "mahalle", "name": "Osmanağa" }
    ]
  },
  "meta": { … }
}

Aynı iş Apify Actor ile

Anahtar almadan ya da toplu iş için Geo Reference Actor'üne bir liste verin; her öğe bir sonuç satırı olur ve gönderdiğiniz değer satırda kalır. Örnek girdi:

{"operation": "contains", "items": [{"lat": 40.9903, "lon": 29.0291}]}

Ne kadar tutar

  • Apify Actor (contains işlemi): 1.000 koordinat sorgusu için 0,30 $.
  • Bu uç noktada anahtarsız ücretsiz kullanım yok; anahtar için api@forlab.io adresine yazın.
  • Geo API sayfasındaki canlı haritada anahtarsız deneyebilirsiniz.

Apify'da kullandıkça ödersiniz: yalnız yanıtlanan sorgular ücretlenir, isteğe dönüşemeyen öğeler ücretsizdir, her çalıştırmaya ayrıca 0,001 $ başlangıç ücreti eklenir. Apify'ın ücretsiz planındaki aylık 5 $ kredi yaklaşık 16.000 koordinat sorgusuna yeter. Doğrudan API anahtarı için api@forlab.io adresine yazın.

Sık sorulan sorular

Her noktada mahalle döner mi?

Hayır. Türkiye'de karadaki her nokta için il ve ilçe döner. Mahalle yalnız sınırı olan mahallelerde gelir; resmî listedeki mahallelerin hepsinin sınırı yok, bu yüzden bazı noktalarda yanıt ilçede biter.

Nokta denizdeyse ne olur?

Yanıt match: "none" ve boş bir places listesi olur; tahmin yürütülmez. Noktaya en yakın yerleşimleri isterseniz /v1/nearby uç noktasını kullanın.

Çok sayıda koordinatı nasıl sorgularım?

Apify'daki Geo Reference Actor'üne koordinat listesini verin: her koordinat bir sonuç satırı olur ve yalnız yanıtlanan satırlar ücretlenir. Doğrudan API'de her koordinat ayrı bir istektir.

Sokak adı ve bina numarası döner mi?

Hayır. Geo API idari birimleri (ülke, il, ilçe, mahalle) döndürür; sokak ve bina numarası vermez.

Geo API ile başka neler yapılır