Geo API

Posta kodu API: kod sorgulama ve en yakın posta kodları

Bir posta kodunun hangi yere ait olduğunu bulun ya da bir koordinata en yakın posta kodlarını alın. Geo API, Türkiye dahil yaklaşık 120 ülkenin posta kodlarını verir; Türkiye'deki her kod ilçesine ve ilçenin kalıcı kimliğine bağlanır.

Posta kodu sorgulama

/v1/postal?country=TR&code=34710 kodun yerlerini döndürür: yer adı, il ve ilçe adları, yaklaşık koordinat ve doğruluk derecesi (accuracy). Türkiye'deki satırlar place_id ve path alanlarıyla ilçeye bağlanır; kodu doğrudan il ve ilçe kimliğine çevirirsiniz.

Boşluk ve tire yok sayılır. Bir kodun birden çok yeri olabilir; limit ve offset ile sayfalayın.

Koordinata en yakın posta kodları

/v1/postal/nearby?lat=&lon= bir noktaya en yakın kodları mesafesiyle (km), en yakından başlayarak verir. Kullanıcının konumundan adres formundaki posta kodu alanını önermek için kullanılır.

Kapsam ve sınırlar

Kaynak GeoNames'tir (CC BY 4.0). Birleşik Krallık, Kanada ve Hollanda'da yalnız kodun ilk kısmı bulunur; bu ülkelerin ve kodu kısmi olan diğer ülkelerin satırlarında partial: true yazar. Koordinatların çoğu bir algoritmayla yerleştirildiği için her satır accuracy değerini taşır.

Örnek istek ve yanıt

Kadıköy'deki 34710 kodu: yer adı, il, ilçe ve ilçenin kimliği. Bu uç nokta API anahtarı ister.

İstek

curl -H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/postal?country=TR&code=34710"

Yanıttan bir kesit

{
  "data": [
    {
      "country": "TR", "code": "34710", "place_name": "Caferağa",
      "admin1": "İstanbul", "admin2": "Kadiköy", "admin3": null,
      "lat": 40.9887, "lon": 29.0236, "accuracy": 4, "partial": false,
      "place_id": "TR-A73FCPZ0",
      "path": [
        { "id": "TR", "name": "Türkiye", "type": "country" },
        { "id": "TR-34", "name": "İstanbul", "type": "region" },
        { "id": "TR-A73FCPZ0", "name": "Kadıköy", "type": "county" }
      ]
    }
  ],
  "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": "postal", "items": [{"country": "TR", "code": "34710"}, {"country": "DE", "code": "10115"}]}

Ne kadar tutar

  • Apify Actor, kod sorgulama (postal işlemi): döndürülen her 1.000 satır için 0,10 $.
  • Apify Actor, en yakın posta kodları (postal_nearby işlemi): 1.000 koordinat sorgusu için 0,30 $.
  • Bu uç noktalarda anahtarsız ücretsiz kullanım yok; anahtar için api@forlab.io adresine yazın.

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

Türkiye'de posta kodu mahalleye mi bağlanıyor?

Hayır, ilçeye. Yanıttaki place_name bir mahalle adı olabilir, ama place_id ve path ilçeyi gösterir. Bir noktanın mahallesini bulmak için koordinattan il, ilçe ve mahalle bulma uç noktasını kullanın.

Hangi ülkeler var?

Yaklaşık 120 ülke. Birleşik Krallık, Kanada ve Hollanda'da yalnız kodun ilk kısmı var; Arjantin, Brezilya, Şili, Çin, İrlanda ve Malta'da da kodlar kısmi olabilir ve bu satırlar partial: true taşır.

Posta kodu verisi güncel mi?

Evet, posta kodları GeoNames'ten güncel tutulur. Her yanıt, hangi veri sürümünden geldiğini meta.dataset_version alanında söyler.

Bir posta kodunun sınırını alabilir miyim?

Hayır. Posta kodları sınır olarak değil, yaklaşık bir nokta olarak gelir; il ve ilçe sınırları için Geo API'nin sınır uç noktasını kullanın.

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