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

Coğrafi kodlama terimi genellikle, insanlar tarafından okunabilen bir adresi haritadaki bir konuma dönüştürmeyi ifade eder. Bunun tam tersini yapmak, yani haritadaki bir konumu kullanıcılar tarafından okunabilen bir adrese çevirmek işlemine ters coğrafi kodlama adı verilir.

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 edinme hakkında bilgi edinin.

İ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ğinden bu liste tam 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 yerel 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, tercih edilen dile göre sokak adreslerini yerel dilde, gerekirse kullanıcı tarafından okunabilen bir yazım sistemine dönüştürülmüş şekilde döndü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 aynı dilde döndürülür.
    • Bir ad tercih edilen dilde mevcut değilse coğrafi kodlayıcı en yakın eşlemeyi kullanır.
  • region: ccTLD ("üst düzey alan") iki karakterli değer olarak belirtilen bölge kodu. Parametre, geçerli yasaya göre sonuçları da etkileyebilir.
  • result_type: Bir veya daha fazla adres türünden oluşan, boru (|) ile ayrılmış bir filtre. 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 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 ve ardından belirtilen adres türleriyle eşleşmeyen sonuçları atar. Aşağıdaki değerler desteklenir:
    • street_address, tam açık adresi gösterir.
    • route, adlandırılmış bir rotayı belirtir ("US 101" gibi).
    • intersection, genellikle iki ana yolun kesiştiği önemli bir kavşağı gösterir.
    • political, siyasi bir tüzel kişiyi gösterir. Genellikle bu tür, bir sivil idarenin poligonunu gösterir.
    • country, ulusal siyasi varlığı belirtir ve genellikle Coğrafi Kodlayıcı tarafından döndürülen en yüksek sipariş türüdür.
    • administrative_area_level_1, ülke düzeyinin altındaki birinci sınıf sivil bir varlığı gösterir. Amerika Birleşik Devletleri'nde bu idari düzeyler eyaletlerdir. Tüm ülkeler bu idari düzeyleri göstermez. Çoğu durumda, administrative_area_level_1 kısa adları ISO 3166-2 alt bölümleriyle 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ığı için bu eşleşme her zaman garanti edilmez.
    • administrative_area_level_2, ülke düzeyinin altındaki ikinci düzey sivil bir varlığı gösterir. Amerika Birleşik Devletleri'nde bu idari düzeyler illerdir. Tüm ülkeler bu idari düzeyleri göstermez.
    • administrative_area_level_3, ülke düzeyinin altındaki üçüncü düzey sivil bir varlığı gösterir. Bu tür, küçük bir idari bölümü belirtir. Tüm ülkelerde bu idari düzeyler bulunmaz.
    • administrative_area_level_4, ülke düzeyinin altında dördüncü düzey bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir idari bölümü belirtir. Tüm ülkelerde bu idari düzeyler bulunmaz.
    • administrative_area_level_5, ülke düzeyinin altındaki beşinci düzey sivil bir varlığı belirtir. Bu tür, küçük bir idari bölümü belirtir. Tüm ülkelerde bu idari düzeyler bulunmaz.
    • administrative_area_level_6, ülke düzeyinin altındaki altıncı düzey sivil bir varlığı belirtir. Bu tür, küçük bir idari bölümü belirtir. Tüm ülkelerde bu idari düzeyler bulunmaz.
    • administrative_area_level_7, ülke düzeyinin altındaki yedinci düzey sivil bir varlığı belirtir. Bu tür, küçük bir idari bölümü belirtir. Tüm ülkelerde bu idari düzeyler bulunmaz.
    • colloquial_area, öğe için yaygın olarak kullanılan alternatif bir adı gösterir.
    • locality, tüzel kişiliğe sahip bir şehir veya kasaba siyasi tüzel kişisini gösterir.
    • sublocality, bir yerleşimin altındaki birinci sınıf sivil bir varlığı gösterir. Bazı konumlar için ek türlerden birini alabilirsiniz: sublocality_level_1 ila sublocality_level_5. Her alt yerleşim birimi düzeyi yasal bir varlıktır. Daha büyük sayılar daha küçük bir coğrafi alanı gösterir.
    • neighborhood, adlandırılmış bir mahalleyi gösterir.
    • premise, genellikle ortak bir ada sahip bir bina veya bina topluluğu olan adlandırılmış bir konumu gösterir.
    • subpremise, tesis düzeyinin altındaki adreslenebilir bir varlığı (ör. apartman, daire veya suit) gösterir.
    • plus_code, enlem ve boylamdan türetilen kodlanmış bir konum referansını gösterir. Plus code'lar, açık adreslerin bulunmadığı yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı yerlerde) açık adreslerin yerine kullanılabilir. Ayrıntılar için https://plus.codes adresine bakın.
    • postal_code, ülke içinde posta adresleri için kullanılan posta kodunu gösterir.
    • natural_feature belirgin bir doğal özelliği gösterir.
    • airport, havaalanını gösterir.
    • park, adlandırılmış bir parkı gösterir.
    • point_of_interest, adlandırılmış bir önemli yeri gösterir. Bu "ÖY"ler genellikle "Empire State Building" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca sığmayan belirgin yerel varlıklardır.
  • location_type: Bir veya daha fazla konum türünden oluşan, eğik çizgiyle (|) ayrılmış bir filtre. Parametre birden fazla konum türü içeriyorsa API, türlerden herhangi biriyle eşleşen tüm adresleri döndürür. İşlemeyle ilgili not: location_type parametresi, aramayı belirtilen konum türleriyle kısıtlamaz. Aksine, location_type arama sonrası filtre görevi 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ı atar. Aşağıdaki değerler desteklenir:
    • "ROOFTOP" yalnızca Google'ın konum bilgilerinin sokak adresi doğruluğuna kadar doğru olduğu adresleri döndürür.
    • "RANGE_INTERPOLATED" yalnızca iki kesin nokta (ör. kavşaklar) arasında interpolasyon uygulanmış bir yaklaşık değeri (genellikle bir yolda) yansıtan adresleri döndürür. Düzenlenmiş aralık genellikle bir sokak adresi için çatı jeokodlarının kullanılamadığını gösterir.
    • "GEOMETRIC_CENTER" yalnızca bir konumun geometrik merkezlerini (ör. birden fazla çizgi veya 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 özelliklerin birden fazlasını etkinleştirmek isterseniz her bir ö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 edilemezse 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> ...

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 konumu coğrafi olarak adlandırmanın her yoludur. Örneğin, Chicago şehrindeki bir noktanın coğrafi kodlaması yapılırken coğrafi kodlanmış nokta bir sokak adresi, şehir (Chicago), eyalet (Illinois) veya ülke (ABD) olarak gösterilebilir. Bunların tümü, coğrafi kodlayıcı için "adreslerdir". Ters coğrafi kodlayıcı, bu türlerden herhangi birini geçerli sonuçlar 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ö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 ayrıntılı sokak adresinden mahalle, şehir, ilçe ve eyalet gibi daha az ayrıntılı siyasi varlıklara kadar farklı adres türleri döndürür. Daha doğru 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 sınırlama ile ilgili aşağıdaki bölüme bakın. Bu nedenle, sonuçların birbirine göre konumu değişebilir.

Türe göre filtrelenen 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 olan adresleri içerecek şekilde filtrelenir.

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.

Yanıtları tersine coğrafi kodlama

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. Ters coğrafi kodlama yanıtında kullanılabilecek durum kodları aşağıda verilmiştir.

Tersine coğrafi kodlama durum kodları

Coğrafi kodlama yanıt nesnesinin "status" alanı, isteğin durumunu içerir ve ters coğrafi kodlamanın neden çalışmadığını belirlemenize yardımcı olacak hata ayıklama bilgilerini içerebilir. "status" alanına aşağıdaki değerler girilebilir:

  • "OK", hata olmadığını ve en az bir adres 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 iletilmesi durumunda ortaya çıkabilir.
  • "OVER_QUERY_LIMIT", kotanızı aştığınızı gösterir.
  • "REQUEST_DENIED", isteğin reddedildiğini gösterir. Bunun nedeni, istekte result_type veya location_type parametresi bulunması ancak API anahtarının bulunmaması olabilir.
  • "INVALID_REQUEST" genellikle aşağıdakilerden birini gösterir:
    • Sorgu (address, components veya latlng) eksik.
    • Geçersiz bir result_type veya location_type sağlandı.
  • "UNKNOWN_ERROR", isteğinin sunucu hatası nedeniyle işlenemediğini gösterir. Tekrar denerseniz istek başarılı olabilir.

Plus kodlarını tersine coğrafi kodlama

Coğrafi kodlama yanıtındaki plus_code alanı, sorgulanan enlem ve boylama en yakın artı kodu içerir. Ayrıca, JSON sonuçları dizisi çoğu durumda plus_code türüne sahip tam bir Coğrafi Kodlama sonucu ve artı kodu içeren bir adres içerir. Kodu çözülmüş artı kodu ile istek noktası arasındaki mesafenin 10 metrenin altında olması garanti edilir.