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

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Coğrafi kodlama terimi, genellikle kullanıcıların okuyabileceği bir adresi haritadaki bir konuma çevirme anlamına gelir. Bunun tersini yapmak için, haritadaki bir konumu kullanıcıların okuyabileceği bir adrese çevirmek, ters coğrafi kodlama olarak bilinir.

Ters coğrafi kodlama istekleri

Gerekli parametreler

  • latlng — İnsanların okuyabileceği en yakın adresi elde etmek istediğiniz konumu belirten enlem ve boylam değerleri.
  • key — Uygulamanızın API anahtarı. Bu anahtar, kota yönetimi için 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 listesine bakın. Google genellikle desteklenen dilleri güncellediğinden bu liste tam kapsamlı olmayabilir.
    • language sağlanmazsa coğrafi kodlama uzmanı, Accept-Language başlığında belirtilen tercih edilen dili veya isteğin gönderildiği alanın yerel dilini kullanmaya çalışır.
    • Coğrafi kodlama uzmanı, hem kullanıcı hem de yerel kullanıcılar için okunabilir bir açık adres sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için yerel dilde açık adresleri döndürür. Gerekirse kullanıcının okuyabileceği bir komut dosyasına dönüştürülür ve tercih edilen dil göz önünde bulundurulur. 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.
    • Tercih edilen dilde bir ad yoksa, coğrafi kodlama en yakın eşleşmeyi kullanır.
  • result_type - Bir veya daha fazla adres türü içeren ve dikey çizgiyle (|) ayrılmış filtre. Parametre birden fazla adres türü içeriyorsa API, bu 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, bir arama sonrası filtre olarak çalışır: API, belirtilen latlng için tüm sonuçları alır, ardından belirtilen adres türleriyle eşleşmeyen bu sonuçları siler. Aşağıdaki değerler desteklenir:
    • street_address açık adresi belirtir.
    • route, adlandırılmış bir rotayı belirtir (ör. "US 101").
    • intersection genellikle iki ana yoldan oluşan ana kesişimi belirtir.
    • political, siyasi bir varlığı belirtir. Genellikle bu, bir sivil yönetimin poligonunu gösterir.
    • country, ulusal siyasi varlığı belirtir ve genellikle Geocoder tarafından döndürülen en yüksek sipariş türüdür.
    • administrative_area_level_1, ülke düzeyinin altındaki birinci taraf sivil tüzel kişiyi belirtir. ABD'de bu yönetim düzeyleri eyalet düzeyindedir. Bu yönetim düzeyleri tüm ülkeler tarafından görülemez. Çoğu durumda, admin_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 sinyalleri ve konum verilerini temel aldığından bu garanti edilmez.
    • administrative_area_level_2, ülke düzeyinin altında ikinci taraf sivil kuruluşu belirtir. Amerika Birleşik Devletleri'nde bu idari bölgeler ilçedir. Bu yönetim düzeyleri tüm ülkeler tarafından görülemez.
    • administrative_area_level_3, ülke düzeyinin altında üçüncü taraf sivil kuruluşu belirtir. Bu tür, küçük bir hukuki bölümü gösterir. Bu idari düzey her ülke tarafından gösterilmemektedir.
    • administrative_area_level_4, ülke düzeyinin altında dördüncü taraf sivil kuruluşu belirtir. Bu tür, küçük bir hukuki bölümü gösterir. Bu idari düzey her ülke tarafından gösterilmemektedir.
    • administrative_area_level_5, ülke düzeyinin beşinci sırada yer alan bir tüzel kişi olduğunu belirtir. Bu tür, küçük bir hukuki bölümü gösterir. Bu idari düzey her ülke tarafından gösterilmemektedir.
    • administrative_area_level_6, ülke düzeyinin altında olan altıncı bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir hukuki bölümü gösterir. Bu idari düzey her ülke tarafından gösterilmemektedir.
    • administrative_area_level_7, ülke düzeyinin altında yedinci düzey medeni tüzel kişiyi belirtir. Bu tür, küçük bir hukuki bölümü gösterir. Bu idari düzey her ülke tarafından gösterilmemektedir.
    • colloquial_area, varlık için yaygın olarak kullanılan bir alternatif adı belirtir.
    • locality, ilişkili şehir veya ilçe siyasi varlığını belirtir.
    • sublocality, bir mahallenin altındaki birinci taraf sivil tüzel kişiyi belirtir. Bazı konumlar için şu ek türlerinden birini alabilir: sublocality_level_1 - sublocality_level_5. Her semt, bir tüzel kişidir. Daha büyük sayılar, daha küçük bir coğrafi alanı belirtir.
    • neighborhood, adlandırılmış bir mahalleyi gösteriyor
    • premise, adlandırılmış bir konumu belirtir. Bu konum genellikle bir bina veya ortak ada sahip bir bina koleksiyonudur
    • subpremise, adlandırılmış bir konumun altındaki birinci taraf varlığını belirtir (genellikle aynı ada sahip bina koleksiyonundaki tek bir bina).
    • plus_code, enlem ve boylamdan türetilen kodlanmış bir konum referansını belirtir. Artı kodları, var olmayan yerlerde (binaların numaralandırılmamış veya sokakların adlandırılmamış olduğu) açık adresler yerine kullanılabilir. Ayrıntılar için https://plus.codes sayfasına bakın.
    • postal_code, ülke içindeki posta kodları için kullanılan posta kodunu belirtir.
    • natural_feature belirgin bir doğal özelliği belirtir.
    • airport, bir havaalanını gösteriyor.
    • park, park adını belirtir.
    • point_of_interest, adlandırılan bir önemli noktayı belirtir. Genellikle bu "ÖY'ler", "Empire State Binası" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca sığmayan önemli yerel varlıklardır.
  • location_type - Bir veya daha fazla konum türünün, dikey çizgiyle (|) ayrılmış bir filtresi. Parametre birden fazla konum türü içeriyorsa API, bu türlerden herhangi biriyle eşleşen tüm adresleri döndürür. İşlemeyle ilgili bir not: location_type parametresi, aramayı belirtilen konum türleriyle kısıtlamaz. Bunun yerine, location_type, bir arama sonrası filtre olarak çalışır: API, belirtilen latlng sonucuna ait tüm sonuçları getirir, ardından belirtilen konum türleriyle eşleşmeyen sonuçları siler. Aşağıdaki değerler desteklenir:
    • "ROOFTOP" adresi, yalnızca adres bilgilerinin Google'da doğru adresi olduğu kesin değerleri döndürür.
    • "RANGE_INTERPOLATED" yalnızca, iki tam nokta (kesişimler gibi) arasındaki bir mesafeyi (genellikle yol üzerinde) yansıtan adresleri döndürür. Aralıklı aralık, genellikle açık adres için çatı coğrafi kodlamalarının kullanılamadığını gösterir.
    • "GEOMETRIC_CENTER" yalnızca bir poligon (örneğin, sokak) veya poligon (bölge) gibi bir yerin geometrik merkezlerini döndürür.
    • "APPROXIMATE" yalnızca yaklaşık olarak tanımlanan adresleri döndürür.

Hem result_type hem de location_type filtresi varsa API yalnızca result_type ve 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.

Ters 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 kodlamanı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 bir yoludur. Örneğin, Chicago şehrinde bir noktanın coğrafi kodlamasını yaparken coğrafi kodlamalı nokta şehir, (Chicago), eyaleti (Illinois) veya ülke (Amerika Birleşik Devletleri) olarak gösterilebilir. Bunların tümü, coğrafi kodlama uzmanının "adresleri"dir. Ters coğrafi kodlayıcı, bu türlerden herhangi birini geçerli sonuç olarak döndürür.

Ters coğrafi kodlama, siyasi tüzel kişiler (ülkeler, iller, şehirler ve mahalleler), açık adresler ve posta kodlarıyla eşleşir.

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

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

Genellikle adresler en spesifik olandan en az spesifik olana döndürülür; daha kesin adres, bu örnekte olduğu gibi, en belirgin sonuçtur. En açık sokak adresinden mahalleler, şehirler, ilçeler, eyaletler gibi daha az politik varlıklara kadar farklı türlerde adresler döndürdüğümüzü unutmayın. Belirli bir adres türüyle eşleştirme yapmak isterseniz aşağıdaki sonuçları türe göre kısıtlama bölümüne bakın.

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

Aşağıdaki örnekte, yalnızca konum türü ROOFTOP ve adres türü street_address olan adresler dahil edilecek şekilde döndürülen adresler 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.

Ters coğrafi kodlama yanıtları

Ters coğrafi kodlama yanıtının biçimi, coğrafi kodlama yanıtıyla aynıdır. Coğrafi kodlama yanıtları başlıklı makaleyi inceleyin. Ters coğrafi kodlama yanıtında olası durum kodları aşağıda verilmiştir.

Ters 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ı izlemenize yardımcı olacak hata ayıklama bilgilerini içerebilir. "status" alanı, aşağıdaki değerleri içerebilir:

  • "OK", hiçbir hatanın oluşmadığını ve en az bir adresin döndürüldüğünü belirtir.
  • "ZERO_RESULTS", ters coğrafi kodlamanın başarılı olduğunu ancak hiçbir sonuç döndürmediğini belirtir. Bu durum, coğrafi kodlamanın uzak bir yerde latlng iletilmesinden kaynaklanabilir.
  • "OVER_QUERY_LIMIT", kotanızı aştığınızı gösterir.
  • "REQUEST_DENIED", isteğin reddedildiğini belirtir. Muhtemelen istek bir result_type veya location_type parametresi içeriyor, ancak API anahtarı içermiyordur.
  • "INVALID_REQUEST" genellikle aşağıdakilerden birini gösterir:
    • Sorgu (address, components veya latlng) eksik.
    • Geçersiz bir result_type veya location_type verildi.
  • "UNKNOWN_ERROR", bir sunucu hatası nedeniyle isteğin işlenemediğini gösterir. Tekrar denemeniz durumunda istek başarılı olabilir.

Ters coğrafi kodlama artı kodları

Coğrafi kodlama yanıtı nesnesindeki plus_code alanı, sorgulanan enlem ve boylamı en iyi şekilde tahmin eden bir artı kodu içerir. Buna ek olarak JSON sonuç dizisi, çoğu durumda plus_code türündeki tam bir coğrafi kodlama sonucunu ve artı kodu içeren bir adresi içerir. Kodu çözülmüş artı kodu ve istek noktası arasındaki mesafe 10 metrenin altında olmalıdır.