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 adresin haritadaki bir konuma çevrilmesini ifade eder. Bunun tersini yapmak, haritadaki bir konumu okunabilir bir adrese çevirmek, ters coğrafi kodlama olarak bilinir.

Ters coğrafi kodlama istekleri

Gerekli parametreler

  • latlng - İnsan tarafından okunabilir 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. Anahtar alma 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, genellikle desteklenen dilleri güncellediği için bu liste tam kapsamlı olmayabilir.
    • language sağlanmazsa coğrafi kodlama, 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ın okuyabileceği bir sokak adresi 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 dikkate alını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.
    • Tercih edilen dilde bir ad yoksa coğrafi kodlama en yakın eşleşmeyi kullanır.
  • result_type: Bir çizgi (|) ile ayrılmış bir veya daha fazla adres türünü içeren bir filtredir. Parametre birden fazla adres türü içeriyorsa 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ı bir filtre olarak çalışı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:
    • street_address açık bir adres belirtiyor.
    • route, adlandırılmış bir rotayı belirtir (ör. "US 101").
    • intersection genellikle iki ana yoldan oluşan büyük bir kesişimi gösterir.
    • political, siyasi bir varlığı belirtir. Genellikle bu tür, belirli bir idari yönetimin poligonunu belirtir.
    • 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 varlığı gösterir. ABD'de bu idari düzeyler eyalettir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir. Çoğu durumda, admin_area_level_1 kısa adları ISO 3166-2 alt bölümleri ve yaygın şekilde dolaşım sağlayan diğer listelerle yakından eşleşir. Ancak, coğrafi kodlama sonuçlarımız çeşitli sinyallere ve konum verilerine dayalı olduğundan bu garanti edilmez.
    • administrative_area_level_2, ülke düzeyinin altındaki ikinci düzey bir tüzel kişiyi gösterir. Amerika Birleşik Devletleri'nde bu idari bölgeler ilçelerdir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
    • administrative_area_level_3, ülke düzeyinin altındaki üçüncü taraf sivil tüzel kişiliğini gösterir. Bu tür, küçük bir sivil bölümü gösterir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
    • administrative_area_level_4, ülke düzeyinin altındaki dördüncü taraf bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil bölümü gösterir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
    • administrative_area_level_5, ülke düzeyinin altındaki beşinci sırada yer alan bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil bölümü gösterir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
    • administrative_area_level_6, ülke düzeyinin altındaki bir altıncı sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil bölümü gösterir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
    • administrative_area_level_7, ülke düzeyinin altındaki yedinci bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil bölümü gösterir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
    • colloquial_area, varlık için yaygın olarak kullanılan bir alternatif ad belirtir.
    • locality, birleşik bir şehir veya ilçe siyasi varlığını belirtir.
    • sublocality, bir yerin altında birinci taraf sivil tüzel kişiliği gösterir. Bazı konumlar için ek türlerden biri alınabilir: sublocality_level_1 - sublocality_level_5. Her alt konum düzeyi 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, genellikle ortak bir ada sahip olan bina veya bina koleksiyonu olmak üzere adlandırılmış bir konumu belirtir
    • subpremise, adlandırılmış bir konumun altındaki birinci taraf varlığını (genellikle ortak bir ada sahip bina koleksiyonundaki tek bir bina) belirtir
    • plus_code, enlem ve boylamdan türetilen kodlanmış bir konum referansını belirtir. Artı kodları, mevcut olmayan (binaların numaralandırılmadığı veya sokakların adlandırılmamış olduğu) açık adreslerin yerine kullanılabilir. Ayrıntılar için https://plus.codes sayfasına göz atın.
    • postal_code, ülke içindeki posta posta adreslerinde kullanılan posta kodunu belirtir.
    • natural_feature belirgin bir doğal özellik gösterir.
    • airport bir havaalanını gösteriyor.
    • park, adlandırılmış bir parkı belirtir.
    • point_of_interest, önemli bir önemli nokta olduğunu gösterir. Bu "ÖY'ler" genellikle "Empire State Binası" veya "Eyfel Kulesi" gibi diğer kategorilere kolayca sığmayan önemli yerel varlıklardır.
  • location_type: Bir çizgiyle (|) ayrılmış bir veya daha fazla konum türünün filtresidir. Parametre birden fazla konum türü içeriyorsa 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, arama sonrası bir filtre olarak çalışır: API, belirtilen latlng için tüm sonuçları getirir, ardından belirtilen konum türleriyle eşleşmeyen sonuçları siler. Aşağıdaki değerler desteklenir:
    • "ROOFTOP" yalnızca, Google'ın adres bilgilerini doğru ve açık adres kesinliğine kadar olan adreslerini döndürür.
    • "RANGE_INTERPOLATED" yalnızca yaklaşık iki nokta (ör. kesişimler) arasındaki tahmini bir değeri (genellikle bir yolda) yansıtan adresleri döndürür. Etkileşimli aralık, genellikle açık adres için çatıdaki coğrafi kodlamanın kullanılamadığını gösterir.
    • "GEOMETRIC_CENTER" yalnızca bir çoklu çizgi (ör. sokak) veya poligon (bölge) gibi bir yerin geometrik merkezlerini döndürür.
    • "APPROXIMATE", yalnızca yaklaşık olarak tanımlanmış adresleri döndürür.

Hem result_type hem de location_type filtreleri 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 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 herhangi bir yoludur. Örneğin, Chicago şehrinde bir noktanın coğrafi kodlamasını yaparken coğrafi kodlama noktası, şehir (Chicago), eyaleti (Illinois) veya ülke (Amerika Birleşik Devletleri) olarak açık adres olarak gösterilebilir. Bunların tümü, coğrafi kodlamanın "adresleridir". Ters coğrafi kodlayıcı, bu türlerden herhangi birini geçerli sonuçlar olarak döndürür.

Ters coğrafi kod, 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 verilmiştir.

"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",

Genelde adresler en spesifik olandan en az spesifik olana döndürülür; bu durumda olduğu gibi en belirgin sonuç daha belirgin olan sonuçtur. En spesifik sokak adresinden, mahalleler, şehirler, ilçeler, eyaletler gibi daha dar kapsamlı siyasi kuruluşlara kadar farklı türlerde adresler döndürdüğümüzü unutmayın. Belirli bir adres türünü eşleştirmek istiyorsanız aşağıdaki sonuçları türe göre kısıtlama ile ilgili bölüme bakın.

Türe göre filtrelenen ters coğrafi kodlama

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

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ını aşağıda görebilirsiniz.

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ı öğrenmenize yardımcı olmak için hata ayıklama bilgileri 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ü gösterir.
  • "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 konumdaki bir latlng içinde iletilmesi durumunda ortaya çıkabilir.
  • "OVER_QUERY_LIMIT", kotanızı aştığınızı belirtir.
  • "REQUEST_DENIED", isteğin reddedildiğini belirtir. Bunun nedeni muhtemelen isteğin bir result_type veya location_type parametresi içermesi, ancak API anahtarı içermemesidir.
  • "INVALID_REQUEST" genellikle aşağıdakilerden birini gösterir:
    • Sorgu (address, components veya latlng) eksik.
    • Geçersiz bir result_type veya location_type belirtildi.
  • "UNKNOWN_ERROR", isteğin sunucu hatası nedeniyle işlenemediğini gösterir. Tekrar denediğinizde 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üne sahip tam coğrafi kodlama sonucu ve artı kodu içeren bir adres içerir. Kodu çözülmüş artı kodu ve istek noktası arasındaki mesafe 10 metreden az olmalıdır.