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

Avrupa Ekonomik Alanı (AEA) geliştiricileri

Coğrafi kodlama terimi genellikle okunabilir bir adresin harita üzerindeki bir konuma çevrilmesini ifade eder. Bunun tam tersi olan, haritadaki bir konumu okunabilir bir adrese çevirme işlemine tersine coğrafi kodlama adı verilir.

Tersine coğrafi kodlama istekleri

Gerekli parametreler

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

İsteğe bağlı parametreler

Ters 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ği için bu liste kapsamlı olmayabilir.
    • language sağlanmazsa coğrafi kodlayıcı, Accept-Language üstbilgisinde belirtilen tercih edilen dili veya isteğin gönderildiği alan adının yerel dilini kullanmaya çalışır.
    • Coğrafi kodlayıcı, hem kullanıcı hem de yerel halk tarafından okunabilir bir açık adres sağlamak için elinden geleni yapar. Bu hedefi gerçekleştirmek için tercih edilen dili dikkate alarak gerekirse sokak adreslerini yerel dilde ve kullanıcının okuyabileceği bir alfabeye çevrilmiş olarak döndürür. Diğer tüm adresler tercih edilen dilde döndürülür. Adres bileşenlerinin tümü aynı dilde döndürülür. Bu dil, ilk bileşenden seçilir.
    • Bir ad tercih edilen dilde kullanılamıyorsa coğrafi kodlayıcı en yakın eşleşmeyi kullanır.
  • region: ccTLD ("üst düzey alan") olarak belirtilen, iki karakterlik bir değer olan bölge kodu. Parametre, geçerli yasaya göre sonuçları da etkileyebilir.
  • result_type: Bir veya daha fazla adres türünün boru işaretiyle (|) 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. İşleme hakkında not: result_type parametresi, aramayı belirtilen adres türleriyle sınırlandırmaz. 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ıtın GeocodeResult gövdesindeki types dizisi, adres türünü belirtir. Adres türlerine örnek olarak açık adres, ülke veya siyasi birim verilebilir. GeocodeResult gövdesinin AddressComponents alanındaki types dizisi, adresin her bir bölümünün türünü belirtir. Örneğin, bina numarası veya ülke.

    Adresler birden fazla türde 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 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 bir tüzel kişi. Genellikle bu tür, bir idari birimin poligonunu gösterir.
    country Ulusal siyasi varlık ve genellikle Coğrafi Kodlayıcı tarafından döndürülen en yüksek sıralı türdür.
    administrative_area_level_1 Ülke düzeyinin altındaki birinci dereceden sivil alan. ABD'de bu idari düzeyler eyaletlerdir. Bazı ülkelerde bu idari düzeyler bulunmaz. Ç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 yakından 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 düzey sivil idari birim. Amerika Birleşik Devletleri'nde bu idari düzeyler ilçelerdir. Bazı ülkelerde bu idari düzeyler bulunmaz.
    administrative_area_level_3 Ülke düzeyinin altındaki üçüncü düzey sivil idari birim. Bu tür, küçük bir idari bölgeyi gösterir. Bazı ülkelerde bu idari düzeyler bulunmaz.
    administrative_area_level_4 Ülke düzeyinin altında dördüncü düzey bir sivil varlık. Bu tür, küçük bir idari bölgeyi gösterir. Bazı ülkelerde bu idari düzeyler bulunmaz.
    administrative_area_level_5 Ülke düzeyinin altında beşinci dereceden bir idari birim. Bu tür, küçük bir idari bölgeyi gösterir. Bazı ülkelerde bu idari düzeyler bulunmaz.
    administrative_area_level_6 Ülke düzeyinin altında altıncı dereceden bir idari birim. Bu tür, küçük bir idari bölgeyi gösterir. Bazı ülkelerde bu idari düzeyler bulunmaz.
    administrative_area_level_7 Ülke düzeyinin altındaki yedinci dereceden bir sivil varlık. Bu tür, küçük bir idari bölgeyi gösterir. Bazı ülkelerde bu idari düzeyler bulunmaz.
    colloquial_area Tüzel kişi için yaygın olarak kullanılan alternatif bir ad.
    locality Tüzel kişiliğe sahip bir şehir veya kasaba siyasi tüzel kişiliği.
    sublocality Bir yerleşim biriminin altındaki birinci dereceden sivil alan. Bazı konumlar için sublocality_level_1 ile sublocality_level_5 arasındaki ek türlerden biri kullanılabilir. Her alt yerleşim birimi düzeyi, sivil bir varlıktır. 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 ortak bir ada sahip bir bina veya binalar topluluğu.
    subpremise Tesis düzeyinin altında, adreslenebilir bir varlık (ör. apartman, birim veya süit).
    plus_code Enlem ve boylamdan elde edilen, kodlanmış bir konum referansı. Plus code'lar, sokak adreslerinin olmadığı yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı yerler) sokak adreslerinin 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 alan.
    airport Havalimanı
    park Adlandırılmış bir park.
    point_of_interest Adlandırılmış bir önemli yer. Bu "ÖY"ler genellikle "Empire State Binası" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca uymayan, öne çıkan yerel varlıklardır.

    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: Dikey çubukla (|) ayrılmış bir veya daha fazla konum türünün 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 not: location_type parametresi, aramayı belirtilen konum türleriyle sınırlandırmaz. Bunun yerine, location_type, arama sonrası filtre görevi görür: API, belirtilen latlng için tüm sonuçları getirir, ardından belirtilen konum türleriyle eşleşmeyen sonuçları atar. Aşağıdaki değerler desteklenir:
    • "ROOFTOP" yalnızca Google'ın sokak adresi hassasiyetine kadar 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 elde edilen, yaklaşık değerleri (genellikle bir yol üzerinde) yansıtan adresleri döndürür. İnterpolasyonlu bir aralık genellikle çatı üstü coğrafi kodların bir sokak adresi için kullanılamadığını gösterir.
    • "GEOMETRIC_CENTER" yalnızca bir konumun geometrik merkezlerini (ör. çoklu çizgi (sokak) veya poligon (bölge)) döndürür.
    • "APPROXIMATE" yalnızca yaklaşık olarak nitelendirilen 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çeriyor:

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

Yukarıdaki sorgu şu 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> ...

Ters 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 konuma coğrafi olarak ad vermenin herhangi bir yoludur. Örneğin, Chicago şehrindeki bir nokta coğrafi olarak kodlandığında, coğrafi olarak kodlanmış nokta sokak adresi, şehir (Chicago), eyalet (Illinois) veya ülke (ABD) olarak belirtilebilir. Bunların tümü, coğrafi kodlayıcıya "adres" olarak gönderilir. Ters coğrafi kod çözücü, bu türlerden herhangi birini geçerli sonuç olarak döndürür.

Ters coğrafi kodlayıcı, siyasi varlıkları (ü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österilmektedir.

{
   "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 ayrıntılı sokak adresinden daha az ayrıntılı siyasi birimlere (ör. mahalleler, şehirler, ilçeler ve eyaletler) kadar farklı türde adresler döndürür. Daha kesin adres genellikle en belirgin sonuçtur (bu örnekte olduğu gibi). Belirli bir adres türüyle eşleşmek istiyorsanız sonuçları türe göre kısıtlama ile ilgili aşağıdaki bölüme bakın. Bu nedenle, sonuçların birbirlerine göre konumu değişebilir.

Tersine coğrafi kodlama, türe göre filtrelenir.

Aşağıdaki örnek, döndürülen adresleri yalnızca ROOFTOP konum türüne ve street_address adres türüne sahip olanları içerecek şekilde filtreler.

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 ters 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. Geocoding yanıtları bölümünü inceleyin. Ters 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 ters coğrafi kodlamanın neden çalışmadığını bulmanıza yardımcı olacak hata ayıklama bilgilerini 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", ters 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 iletilirse ortaya çıkabilir.
  • "OVER_QUERY_LIMIT", kotanızı aştığınızı gösterir.
  • "REQUEST_DENIED", isteğin reddedildiğini gösterir. İstek, result_type veya location_type parametresini içeriyor ancak API anahtarı içermiyor olabilir.
  • "INVALID_REQUEST" genellikle aşağıdakilerden birini gösterir:
    • Sorgu (address, components veya latlng) eksik.
    • Geçersiz bir result_type veya location_type değeri verildi.
  • "UNKNOWN_ERROR", sunucu hatası nedeniyle isteğin işlenemediğini gösterir. Tekrar denerseniz istek başarılı olabilir.

Plus Code'ları tersine coğrafi kodlama

Coğrafi kodlama yanıtındaki plus_code alanı, sorgulanan enlem ve boylamı en iyi şekilde yaklaştıran bir artı kodu içerir. Ayrıca, JSON sonuç dizisi çoğu durumda bir artı kodu içeren bir adres ve plus_code türüyle birlikte tam bir Coğrafi Kodlama sonucu içerir. Çözülen artı kodu ile istek noktası arasındaki mesafenin 10 metrenin altında olduğu garanti edilir.