Ters coğrafi kodlama (adres arama) isteği ve yanıtı

Avrupa Ekonomik Alanı'ndaki (AEA) geliştiriciler

Coğrafi kodlama terimi genellikle, insanlar tarafından okunabilen bir adresin haritadaki bir konuma dönüştürülmesini ifade eder. Bunun tam tersi olan, haritadaki bir konumu insanların okuyabileceği bir adrese dönüştürme işlemine ise tersine coğrafi kodlama denir.

Tersine coğrafi kodlama istekleri

Gerekli parametreler

  • latlng: En yakın, okunabilir adresi istediğiniz konumu belirten enlem ve boylam koordinatları.
  • key: Uygulamanızın API anahtarı. Bu anahtar, kota yönetimi amacıyla uygulamanızı tanımlar. Anahtar almayı öğrenin.

İsteğe bağlı parametreler

Tersine coğrafi kodlama isteğine ekleyebileceğiniz isteğe bağlı parametreler şunlardır:

  • language: Sonuçların döndürüleceği dil.
    • Desteklenen dillerin listesini inceleyin. Google, desteklenen dilleri sık sık güncellediğinden bu liste kapsamlı olmayabilir.
    • language sağlanmazsa coğrafi kodlayıcı, Accept-Language başlığında belirtilen tercih edilen dili veya isteğin gönderildiği alanın ana dilini kullanmaya çalışır.
    • Coğrafi kodlayıcı, hem kullanıcı hem de yerel halk tarafından okunabilen bir açık adres sağlamak için elinden geleni yapar. Bu amaca ulaşmak için açık adresleri yerel dilde döndürür. Gerekirse tercih edilen dili dikkate alarak kullanıcı tarafından okunabilir bir alfabeye dönüştürür. Diğer tüm adresler tercih edilen dilde döndürülür. Adres bileşenlerinin tümü, ilk bileşenden seçilen dilde döndürülür.
    • Tercih edilen dilde bir ad yoksa coğrafi kodlayıcı en yakın eşleşmeyi kullanır.
  • region: İki karakterli bir ccTLD ("üst düzey alan") değeri olarak belirtilen bölge kodu. Parametre, geçerli yasaya göre sonuçları da etkileyebilir.
  • result_type: Bir veya daha fazla adres türünün dikey çizgiyle (|) ayrılmış filtresi. Parametre birden fazla adres türü içeriyorsa API, türlerden herhangi biriyle eşleşen tüm adresleri döndürür. İşlemeyle ilgili bir not: result_type parametresi, aramayı belirtilen adres türleriyle kısıtlamaz. Bunun yerine, result_type arama sonrası filtre görevi görür: API, belirtilen latlng için tüm sonuçları getirir, ardından belirtilen adres türleriyle eşleşmeyen sonuçları siler. Aşağıdaki değerler desteklenir:

    Adres türleri ve adres bileşeni türleri

    Yanıttaki GeocodeResult gövdesinde bulunan types dizisi, adres türünü gösterir. Adres türlerine örnek olarak açık adres, ülke veya siyasi bir varlık verilebilir. GeocodeResult gövdesinin AddressComponents alanındaki types dizisi, adresin her bir bölümünün türünü gösterir. Bina numarası veya ülke buna örnek olarak verilebilir.

    Adreslerin birden fazla türü olabilir. Türler "etiket" olarak kabul edilebilir. Örneğin, birçok şehir political ve locality türleriyle etiketlenir.

    Aşağıdaki türler desteklenir ve hem adres türü hem de adres bileşeni türü dizilerinde döndürülür:

    Adres Türü Açıklama
    street_address Tam açık adres.
    route Adlandırılmış bir rota (ör. "US 101").
    intersection Genellikle iki ana yolun kesiştiği büyük bir kavşak.
    political Siyasi tüzel kişi Genellikle bu tür, bir sivil idarenin poligonunu gösterir.
    country Ulusal siyasi varlıktır ve genellikle Coğrafi Kodlayıcı tarafından döndürülen en yüksek düzeydeki türdür.
    administrative_area_level_1 Ülke düzeyinin altındaki birinci dereceden idari bölge. Amerika Birleşik Devletleri'nde bu idari düzeyler eyaletlerdir. Bu idari düzeyler bazı ülkelerde kullanılmaz. Çoğu durumda administrative_area_level_1 kısa adları, ISO 3166-2 alt bölümleri ve yaygın olarak kullanılan diğer listelerle büyük ölçüde eşleşir. Ancak coğrafi kodlama sonuçlarımız çeşitli sinyallere ve konum verilerine dayandığından bu durum garanti edilmez.
    administrative_area_level_2 Ülke düzeyinin altındaki ikinci dereceden idari bölge. Amerika Birleşik Devletleri'nde bu idari düzeyler ilçelerdir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    administrative_area_level_3 Ülke düzeyinin altındaki üçüncü düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    administrative_area_level_4 Ülke düzeyinin altındaki dördüncü düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    administrative_area_level_5 Ülke düzeyinin altındaki beşinci düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    administrative_area_level_6 Ülke düzeyinin altındaki altıncı düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    administrative_area_level_7 Ülke düzeyinin altındaki yedinci düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    colloquial_area Varlığın yaygın olarak kullanılan alternatif adı.
    locality Tüzel kişiliğe sahip bir şehir veya kasaba siyasi kuruluşu.
    sublocality Bir yerleşim yerinin altındaki birinci dereceden idari bölge. Bazı konumlarda ek türlerden biri (sublocality_level_1 - sublocality_level_5) gösterilebilir. Her alt idari bölge düzeyi bir sivil tüzel kişidir. Daha büyük sayılar daha küçük bir coğrafi alanı gösterir.
    neighborhood Adlandırılmış bir mahalle.
    premise Adlandırılmış bir konum. Genellikle bir bina veya ortak adı olan bir bina grubudur.
    subpremise Tesis düzeyinin altında, adreslenebilir bir varlık (ör. apartman dairesi, birim veya süit).
    plus_code Enlem ve boylamdan türetilen, kodlanmış bir konum referansı. Plus Kodlar, açık adreslerin bulunmadığı yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı yerler) açık adreslerin yerine kullanılabilir. Ayrıntılar için https://plus.codes adresini ziyaret edin.
    postal_code Ülke içinde posta göndermek için kullanılan posta kodu.
    natural_feature Belirgin bir doğal özellik.
    airport Havaalanı.
    park Adlandırılmış bir park.
    point_of_interest Adlandırılmış önemli yer. Genellikle bu "ÖY"ler, "Empire State Binası" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca uymayan önemli yerel öğelerdir.

    Boş bir tür listesi, belirli adres bileşeni için bilinen bir tür olmadığını gösterir (örneğin, Fransa'da Lieu-dit).

  • location_type: Bir veya daha fazla konum türünün dikey çizgiyle (|) ayrılmış filtresi. Parametre birden fazla konum türü içeriyorsa API, türlerden herhangi biriyle eşleşen tüm adresleri döndürür. İşleme hakkında bir not: location_type parametresi, aramayı belirtilen konum türleriyle sınırlamaz. Bunun yerine location_type, arama sonrası filtre işlevi görür: API, belirtilen latlng için tüm sonuçları getirir ve ardından belirtilen konum türleriyle eşleşmeyen sonuçları siler. Aşağıdaki değerler desteklenir:
    • "ROOFTOP", yalnızca Google'ın açık adres düzeyinde doğru konum bilgisine sahip olduğu adresleri döndürür.
    • "RANGE_INTERPOLATED", yalnızca iki kesin nokta (ör. kavşaklar) arasında enterpolasyonla hesaplanan bir yaklaşık değeri (genellikle bir yol üzerinde) yansıtan adresleri döndürür. Ara değerlerle hesaplanan bir aralık, genellikle bir açık adres için çatı coğrafi kodlarının kullanılamadığını gösterir.
    • "GEOMETRIC_CENTER", yalnızca bir konumun geometrik merkezlerini (ör. sokak gibi bir çoklu çizgi veya bölge gibi bir poligon) döndürür.
    • "APPROXIMATE", yalnızca yaklaşık olarak tanımlanan adresleri döndürür.
  • extra_computations: Yanıtta aşağıdaki ek özellikleri belirtmek için bu parametreyi kullanın: Aynı API isteği için bu özelliklerden birden fazlasını etkinleştirmek istiyorsanız her özellik için isteğe extra_computations parametresini ekleyin. Örneğin: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Hem result_type hem de location_type filtreleri mevcutsa API yalnızca hem result_type hem de location_type değerleriyle eşleşen sonuçları döndürür. Filtre değerlerinden hiçbiri kabul edilebilir değilse API, ZERO_RESULTS değerini döndürür.

Tersine coğrafi kodlama örneği

Aşağıdaki sorgu, Brooklyn'deki bir konumun enlem/boylam değerini içerir:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

Yukarıdaki sorgu aşağıdaki sonucu döndürür:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

Tersine coğrafi kodlayıcının birden fazla sonuç döndürdüğünü unutmayın. "formatted_address" sonuçları yalnızca posta adresleri değil, bir konumun coğrafi olarak adlandırılmasının herhangi bir yoludur. Örneğin, Chicago şehrindeki bir noktanın coğrafi kodu oluşturulurken coğrafi kodu oluşturulan nokta açık adres, şehir (Chicago), eyalet (Illinois) veya ülke (ABD) olarak gösterilebilir. Bunların tümü, coğrafi kodlayıcı için "adres" niteliğindedir. Tersine coğrafi kodlayıcı, bu türlerden herhangi birini geçerli sonuç olarak döndürür.

Tersine coğrafi kodlayıcı; siyasi birimleri (ülkeler, iller, şehirler ve mahalleler), açık adresleri ve posta kodlarını eşleştirir.

Önceki sorgu tarafından döndürülen formatted_address değerlerinin tam listesi aşağıda gösterilmiştir.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

Bu API, en spesifik açık adresten mahalle, şehir, ilçe ve eyalet gibi daha az spesifik idari birimlere kadar farklı adres türleri döndürür. Daha kesin olan adres genellikle en belirgin sonuçtur. Bu örnekte de durum böyledir. Belirli bir adres türünü eşleştirmek istiyorsanız aşağıdaki sonuçları türe göre kısıtlama bölümüne bakın. Bu nedenle, sonuçların birbirine göre konumu değişebilir.

Türe göre filtrelenmiş tersine coğrafi kodlama

Aşağıdaki örnekte, döndürülen adresler yalnızca konum türü ROOFTOP ve adres türü street_address olanları içerecek şekilde filtrelenmektedir.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Not: Bu filtreler yalnızca tersine coğrafi kodlama için geçerlidir.

Tersine coğrafi kodlama yanıtları

Tersine coğrafi kodlama yanıtının biçimi, coğrafi kodlama yanıtıyla aynıdır. Coğrafi kodlama yanıtları bölümüne bakın. Tersine coğrafi kodlama yanıtında olası durum kodları aşağıda verilmiştir.

Tersine coğrafi kodlama durum kodları

Coğrafi kodlama yanıt nesnesindeki "status" alanı, isteğin durumunu içerir ve tersine coğrafi kodlamanın neden çalışmadığını bulmanıza yardımcı olacak hata ayıklama bilgileri içerebilir. "status" alanı aşağıdaki değerleri içerebilir:

  • "OK", hata oluşmadığını ve en az bir adresin döndürüldüğünü gösterir.
  • "ZERO_RESULTS", tersine coğrafi kodlamanın başarılı olduğunu ancak sonuç döndürmediğini gösterir. Bu durum, coğrafi kodlayıcıya uzak bir konumda latlng iletildiğinde ortaya çıkabilir.
  • "OVER_QUERY_LIMIT", kotanızı aştığınızı gösterir.
  • "REQUEST_DENIED", isteğin reddedildiğini gösterir. Bunun nedeni, isteğin result_type veya location_type parametresi içermesi ancak API anahtarı içermemesi olabilir.
  • "INVALID_REQUEST" genellikle aşağıdakilerden birini gösterir:
    • Sorgu (address, components veya latlng) eksik.
    • Geçersiz bir result_type veya location_type girildi.
  • "UNKNOWN_ERROR", isteğin bir sunucu hatası nedeniyle işlenemediğini gösterir. Tekrar denerseniz istek başarılı olabilir.

Tersine coğrafi kodlama Plus Code'ları

Geocoding yanıtındaki plus_code alanı, sorgulanan enlem ve boylama en yakın Plus Code'u içerir. Ayrıca, JSON sonuçları dizisi çoğu durumda plus_code türünde tam bir coğrafi kodlama sonucu ve Plus Code içeren bir adres içerir. Kodu çözülen Plus Code ile istek noktası arasındaki mesafenin 10 metreden az olduğu garanti edilir.