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 tersine 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, belirtilenlatlng
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ı ("US 101" gibi) gösterir.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
ilasublocality_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. Genellikle bu "ÖY"ler, "Empire State Binası" 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, belirtilenlatlng
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:ADDRESS_DESCRIPTORS
: Daha fazla bilgi için adres tanımlayıcılarına göz atın.BUILDING_AND_ENTRANCES
: Daha fazla bilgi için girişler ve bina dış hatları bölümüne bakın.
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ı başlıklı makaleyi inceleyin. 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 konumdalatlng
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, istekteresult_type
veyalocation_type
parametresi bulunması ancak API anahtarının bulunmaması olabilir."INVALID_REQUEST"
genellikle aşağıdakilerden birini gösterir:- Sorgu (
address
,components
veyalatlng
) eksik. - Geçersiz bir
result_type
veyalocation_type
sağlandı.
- Sorgu (
"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.