İstek
Coğrafi Kodlama API'si isteği aşağıdaki biçimde olur:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
outputFormat
aşağıdaki değerlerden biri olabilir:
json
(önerilen), JavaScript Object Notation (JSON) çıktısını belirtir veyaxml
, çıkışı XML olarak belirtir
API anahtarı kullanan istekler için HTTPS gerekir.
Bazı parametreler zorunlu, bazıları ise isteğe bağlıdır. URL'lerde olduğu gibi, parametreler "ve" (&
) karakteri kullanılarak ayrılır.
Bu isteğin geri kalanında, her istek türü için farklı parametreler bulunduğundan, coğrafi kodlama ve ters coğrafi kodlama ayrı olarak açıklanmaktadır.
Coğrafi kodlama (enlem/boylam arama) parametreleri
Coğrafi kodlama isteğinde gerekli parametreler:
address
- Ticari kodlamayı yapmak istediğiniz açık adres veya artı kodu. Adresleri, ilgili ülkenin ulusal posta hizmeti tarafından kullanılan biçime göre belirtin. İşletme adları ve daire, daire veya kat numaraları gibi ek adres öğelerinden kaçınılmalıdır. Açık adres öğeleri, boşlukla sınırlandırılmalıdır (burada URL çıkışlı olarak%20
ile gösterilir):address=24%20Sussex%20Drive%20Ottawa%20ON
Plus code'ları burada gösterildiği gibi biçimlendirin (artı işaretleri URL'den çıkış karakterli%2B
, boşluklar URL'ye çıkış karakterli%20
şeklindedir):- Global kod, 4 karakterden oluşan bir alan kodu ve 6 veya daha uzun yerel koddur (849VCWC8+R9
849VCWC8%2BR9
). - Bileşik kod, açık bir konuma sahip 6 karakter veya daha uzun bir yerel koddur (CWC8+R9 Mountain View, CA, ABD
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
--OR--
components
— Öğelerin bir dikey çizgiyle (|
) ayrıldığı bir bileşen filtresi. Bileşenler,address
sağlanırsa isteğe bağlı bir parametre olarak da kabul edilir. Bileşenler filtresindeki her öğe, bircomponent:value
çiftinden oluşur ve coğrafi kodlayıcının sonuçlarını tamamen kısıtlar. Aşağıda bileşen filtreleme hakkında daha fazla bilgi bulabilirsiniz.- Global kod, 4 karakterden oluşan bir alan kodu ve 6 veya daha uzun yerel koddur (849VCWC8+R9
key
: Uygulamanızın API anahtarı. Bu anahtar, kota yönetimi için uygulamanızı tanımlar. Anahtar alma hakkında bilgi edinin.
Daha fazla bilgi için lütfen SSS bölümünü inceleyin.
Coğrafi kodlama isteğinde isteğe bağlı parametreler:
bounds
: Coğrafi kodlamanın sonuçları daha belirgin bir şekilde sapmasına neden olacak şekilde görüntü alanının sınırlayıcı kutusu. Bu parametre yalnızca coğrafi kodlamaya ait sonuçları kısıtlamaz, tamamen etkilemez. (Daha fazla bilgi için aşağıdaki Görüş Alanına Ağırlık Verme bölümünü inceleyin.)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.
- Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç kümesi ve döndürülme sırası üzerinde küçük bir etkiye sahiptir. Coğrafi kodlama, kısaltmaları dile bağlı olarak farklı şekilde yorumlar. Örneğin, sokak türleri için kısaltmalar veya bir dilde geçerli olsa bile başka bir dilde geçerli olmayan eş anlamlılar. Örneğin utca ve tér kelimeleri, Macarcada sırasıyla sokak ve kare ile eş anlamlıdır.
region
: ccTLD ("üst düzey alan") iki karakterli değer olarak belirtilen bölge kodudur. Bu parametre yalnızca coğrafi kodlamaya ait sonuçları etkilemez, tam olarak kısıtlamaz. (Daha fazla bilgi için aşağıdaki Bölgeye Ağırlık Verme bölümünü inceleyin.)components
: Öğelerin dikey çizgiyle (|
) ayrıldığı bir bileşen filtresi. İstek biraddress
içermiyorsa bileşen filtresi zorunludur. Bileşenler filtresindeki her öğe, bircomponent:value
çiftinden oluşur ve coğrafi kodlayıcının sonuçlarını tamamen kısıtlar. Aşağıda bileşen filtreleme hakkında daha fazla bilgi bulabilirsiniz.
Yanıtlar
Coğrafi kodlama yanıtları, URL isteğindeki output
işaretiyle belirtilen biçimde veya varsayılan olarak JSON biçiminde döndürülür.
Bu örnekte Coğrafi Kodlama API'si, "ChIJeRpOeF67j4AR9ydy_PIzPuM" yer kimliğindeki bir sorgu için json
yanıtı istemektedir. Bu yerin kimliği
1600 Amphitheatre Parkway, Mountain View, CA adresindeki binadır.
Bu istek, JSON output
işaretinin kullanıldığını gösterir:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
Bu istek, XML output
işaretinin kullanımını gösterir:
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
Örnek JSON ve XML yanıtlarını görmek için aşağıdaki sekmeleri seçin.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ] }, { "long_name": "California", "short_name": "CA", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4224428, "lng": -122.0842467 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4239627802915, "lng": -122.0829089197085 }, "southwest": { "lat": 37.4212648197085, "lng": -122.0856068802915 } } }, "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM", "plus_code": { "compound_code": "CWC8+X8 Mountain View, CA", "global_code": "849VCWC8+X8" }, "types": [ "street_address" ] } ], "status": "OK" }
JSON yanıtının iki kök öğe içerdiğini unutmayın:
"status"
, istekle ilgili meta verileri içeriyor. Aşağıdaki Durum kodları bölümüne bakın."results"
, coğrafi kodlamalı bir dizi adres ve geometri bilgisi içerir.
Genellikle, adres dizisi için "results"
dizisinde yalnızca bir giriş döndürülürken,coğrafi kodlamayı yapan adres adresi belirsiz olduğunda birkaç sonuç döndürebilir.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
XML yanıtının tek bir <GeocodeResponse>
ve iki üst düzey öğeden oluştuğunu unutmayın:
<status>
, istekle ilgili meta verileri içeriyor. Aşağıdaki Durum kodları bölümüne bakın.- Her biri coğrafi kodlamalı tek bir adres ve geometri bilgisi içeren sıfır veya daha fazla
<result>
öğesi.
XML yanıtı, JSON yanıtından çok daha uzundur. Bu nedenle, hizmetiniz herhangi bir nedenle xml
gerektirmediği sürece json
çıkışını tercih edilen çıkış işareti olarak kullanmanızı öneririz.
Ayrıca, uygun düğüm ve öğelere referans verebilmeniz için XML ağaçlarının işlenmesi biraz dikkat gerektirir. Çıktı işleme için önerilen bazı tasarım kalıpları için XML'i XPath ile ayrıştırma bölümüne bakın.
- XML sonuçları bir kök
<GeocodeResponse>
öğesine sarmalanmış. - JSON, birden fazla dizisi olan girişleri belirtirken (
types
), XML ise bunları birden çok tekil öğe (<type>
) kullanarak belirtir. - Boş öğeler, JSON'de boş diziler aracılığıyla belirtilirken, XML'de bu tür öğelerin olmamasıyla belirtilir. Sonuç vermeyen bir yanıt, JSON içinde boş bir
results
dizisi döndürürken XML gibi<result>
öğeleri döndürmez.
Durum kodları
Coğrafi kodlama yanıtı nesnesindeki "status"
alanı, isteğin durumunu içerir ve 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"
hata olmadığını, adresin başarıyla ayrıştırıldığını ve en az bir coğrafi kodlamanın döndürüldüğünü gösterir."ZERO_RESULTS"
, coğrafi kodlamanın başarılı olduğunu ancak hiçbir sonuç döndürmediğini belirtir. Bu durum, coğrafi kodlamanın mevcut olmayan biraddress
'dan geçirilmesi durumunda gerçekleşebilir.OVER_DAILY_LIMIT
aşağıdakilerden herhangi birini belirtir:- API anahtarı eksik veya geçersiz.
- Hesabınızda faturalandırma etkinleştirilmedi.
- Kendi kendini sınırlayan bir kullanım sınırı aşıldı.
- Sağlanan ödeme yöntemi artık geçerli değil (örneğin, kredi kartının geçerlilik süresi dolmuş).
Bu sorunu nasıl düzelteceğinizi öğrenmek için Haritalar hakkında SSS bölümüne bakın.
"OVER_QUERY_LIMIT"
, kotanızı aştığınızı belirtir."REQUEST_DENIED"
, isteğinizin reddedildiğini belirtir."INVALID_REQUEST"
genellikle sorgunun (address
,components
veyalatlng
) eksik olduğunu gösterir."UNKNOWN_ERROR"
, isteğin sunucu hatası nedeniyle işlenemediğini gösterir. Tekrar denediğinizde istek başarılı olabilir.
Hata mesajları
Kodlayıcı, OK
dışında bir durum kodu döndürdüğünde Geocode yanıt nesnesinin içinde ek bir error_message
alanı olabilir. Bu alan, belirtilen durum kodunun arkasındaki nedenler hakkında daha ayrıntılı bilgi içerir.
Sonuçlar
Kodlayıcı, sonuçları döndürdüğünde (JSON) results
dizisine yerleştirir. Kodlayıcı sonuç döndürmese de (ör. adres yoksa) boş results
dizisi döndürür. (XML yanıtları sıfır veya daha fazla <result>
öğeden oluşur.)
Tipik bir sonuç aşağıdaki alanları içerir:
types[]
dizisi, döndürülen sonucun türünü belirtir. Bu dizi, sonuçta döndürülen özelliğin türünü tanımlayan sıfır veya daha fazla etiket kümesi içerir. Örneğin, "Chicago"nun coğrafi kodlama kodu, "Chicago"nun bir şehir olduğunu belirten "locality", aynı zamanda da siyasi bir tüzel kişi olduğunu belirten "politik" ifadesini döndürür. Söz konusu adres bileşeni için bilinen bir tür yoksa bileşenlerde boş türler bulunabilir. API, gerektiğinde yeni tür değerleri ekleyebilir. Daha fazla bilgi edinmek için Adres türleri ve adres bileşenleri başlıklı makaleye göz atın.formatted_address
, bu konumun kullanıcılar tarafından okunabilir adresini içeren bir dizedir.Bu adres genellikle posta adresiyle eşdeğerdir. Birleşik Krallık gibi bazı ülkelerde lisanslama kısıtlamaları nedeniyle gerçek posta adreslerinin dağıtımına izin verilmediğini hatırlatmak isteriz.
Biçimlendirilmiş adres, mantıksal olarak bir veya daha fazla adres bileşeninden oluşur. Örneğin, "111 8th Avenue, New York, NY" adresi şu bileşenlerden oluşur: "111" (sokak numarası), "8th Avenue" (rota), "New York" (şehir) ve "NY" (ABD eyaleti).
Biçimlendirilmiş adresi programatik olarak ayrıştırmayın. Bunun yerine, API yanıtının biçimlendirilmiş adres alanına ek olarak içerdiği bağımsız adres bileşenlerini kullanmanız gerekir.
address_components[]
, bu adres için geçerli olan ayrı bileşenleri içeren bir dizidir.Her adres bileşeni genellikle aşağıdaki alanları içerir:
types[]
, adres bileşeninin türünü belirten bir dizidir. Desteklenen türlerin listesine bakın.long_name
, Geocoder tarafından döndürülen adres bileşeninin tam metin açıklaması veya adıdır.short_name
, adres bileşeninin (varsa) kısaltılmış metin adıdır. Örneğin, Alaska eyaletindeki bir adres bileşeninde, 2 harfli posta kısaltması kullanılaraklong_name
"Alaska" veshort_name
değeri "AK" bulunabilir.
address_components[]
dizisiyle ilgili aşağıdaki noktaları göz önünde bulundurun:- Adres bileşenleri dizisi,
formatted_address
değerinden daha fazla bileşen içerebilir. - Dizide,
formatted_address
içinde bulunanlar dışında adres içeren tüm siyasi kuruluşlar bulunmayabilir. Belirli bir adres içeren tüm siyasi varlıkları almak için, isteğin enlem veya boylamını parametre olarak ileterek tersine coğrafi kodlama kullanmanız gerekir. - İsteğin biçiminin istekler arasında aynı kalacağı garanti edilmez. Özellikle
address_components
sayısı, talep edilen adrese göre değişir ve aynı adres için zaman içinde değişebilir. Bir bileşen, dizideki konumu değiştirebilir. Bileşenin türü değişebilir. Daha sonraki bir yanıtta belirli bir bileşen eksik olabilir.
Bileşen dizisini işlemek için yanıtı ayrıştırıp ifadeler aracılığıyla uygun değerleri seçmeniz gerekir. Yanıtı ayrıştırma kılavuzuna bakın.
postcode_localities[]
, posta kodundaki tüm şehirleri belirten bir dizidir. Bu yalnızca, sonuç birden fazla konum içeren bir posta kodu olduğunda geçerlidir.geometry
aşağıdaki bilgileri içerir:location
, coğrafi kodlamalı enlemi ve boylam değerini içerir. Normal adres aramalarında bu alan genellikle en önemli olandır.location_type
, belirtilen konumla ilgili ek verileri depolar. Şu anda aşağıdaki değerler desteklenmektedir:"ROOFTOP"
, döndürülen sonucun, açık adres doğruluğuna kadar doğru konum bilgilerine sahip olduğumuz kesin bir coğrafi kodlama olduğunu belirtir."RANGE_INTERPOLATED"
, döndürülen sonucun iki kesin nokta (ör. kavşaklar) arasındaki tahmini bir değeri (genellikle yol üzerinde) gösterdiğini belirtir. Etkileşimli sonuçlar genellikle bir açık adres için çatı coğrafi kodlamaları kullanılamadığında döndürülür."GEOMETRIC_CENTER"
, döndürülen sonucun bir çoklu çizgi (ör. sokak) veya poligon (bölge) gibi bir sonucun geometrik merkezi olduğunu gösterir."APPROXIMATE"
, döndürülen sonucun yaklaşık olduğunu gösterir.
viewport
, döndürülen sonucu görüntülemek için önerilen görüntü alanını içerir. Görüntü alanı sınırlayıcı kutusununsouthwest
venortheast
köşesini tanımlayan iki enlem ve boylam değeri olarak belirtilir. Görüntü alanı, genellikle sonucu kullanıcıya gösterirken çerçevelemek için kullanılır.bounds
(isteğe bağlı olarak döndürülür) döndürülen sonucu tam olarak içerebilen sınırlayıcı kutuyu depolar. Bu sınırların, önerilen görüntü alanıyla eşleşmeyebileceğini unutmayın. (Örneğin, San Francisco, teknik olarak şehrin bir parçası olan ancak büyük olasılıkla görüntü alanında döndürülmemesi gereken Farallon adalarını içerir.)
-
plus_code
(Açık Konum Kodu ve artı kodları), enlem ve boylam koordinatlarından türetilen ve bir alanı temsil eden kodlanmış konum referansıdır: dereceyi 1/8000 ile derecenin 1/8000'i oranında (ekvatorda yaklaşık 14m x 14m) veya daha küçük bir alanı ifade eder. Adres kodları, adreslerin bulunmadığı yerlerde (binaların numaralandırılmadığı veya sokakların belirtilmediği) açık adresler için kullanılabilir. API her zaman artı kodlarını döndürmez.Hizmet artı kodu döndürdüğünde global kod ve birleşik kod olarak biçimlendirilir:
global_code
, 4 karakter uzunluğunda bir alan kodu ve 6 veya daha uzun yerel koddur (849VCWC8+R9).compound_code
, açık bir konuma (CWC8+R9, Mountain View, CA, ABD) sahip 6 karakter veya daha uzun bir yerel koddur. Bu içeriği programla ayrıştırmayın.
-
partial_match
, coğrafi kodlamanın orijinal istek için tam eşleşme döndürmediğini, ancak istenen adresin bir kısmıyla eşleşebildiğini belirtir. Yazım yanlışları ve/veya eksik adresle ilgili orijinal isteği inceleyebilirsiniz.Kısmi eşleşmeler çoğunlukla istekte ilettiğiniz bölgede bulunmayan sokak adresleri için gerçekleşir. Bir istek aynı yerleşimdeki iki veya daha fazla konumla eşleştiğinde de kısmi eşleşmeler döndürülebilir. Örneğin, "Hillpar St, Bristol, UK" hem Henry Street hem de Henrietta Street için kısmi bir eşleşme döndürecektir. Bir istekte yanlış yazılmış adres bileşeni varsa, coğrafi kodlama hizmetinin alternatif bir adres önerebileceğini unutmayın. Bu şekilde tetiklenen öneriler de kısmi eşleşme olarak işaretlenir.
place_id
, diğer Google API'leriyle kullanılabilecek benzersiz bir tanımlayıcıdır. Örneğin, bir Rehber API isteğindekiplace_id
özelliğini kullanarak yerel bir işletmenin telefon numarası, çalışma saatleri, kullanıcı yorumları gibi ayrıntılarını öğrenebilirsiniz. Yer kimliğine genel bakış bölümünü inceleyin.
Adres türleri ve adres bileşeni türleri
Sonuçtaki types[]
dizisi adres türünü belirtir. Açık adres, ülke veya siyasi kuruluş gibi adres türlerine örnek gösterilebilir. Ayrıca address_components[]
içerisinde, adresin her bir bölümünün türünü belirten bir types[]
dizisi vardır. Buna örnek olarak sokak numarası veya ülke gösterilebilir. (Türlerin tam listesini aşağıda bulabilirsiniz.) Adreslerin birden fazla türü olabilir. Türler "etiket" olarak kabul edilebilir.
Örneğin, birçok şehir political
ve locality
türüyle etiketlenir.
Aşağıdaki türler, coğrafi kodlama tarafından hem adres türü hem de adres bileşeni türü dizilerinde desteklenir ve döndürülür:
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österiyorpremise
, genellikle ortak bir ada sahip olan bina veya bina koleksiyonu olmak üzere adlandırılmış bir konumu belirtirsubpremise
, adlandırılmış bir konumun altındaki birinci taraf varlığını (genellikle ortak bir ada sahip bina koleksiyonundaki tek bir bina) belirtirplus_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.
Boş tür listesi, belirli adres bileşeni için bilinen tür olmadığını gösterir (örneğin, Fransa'da Lieu-dit).
Yukarıdakilere ek olarak, adres bileşenleri burada listelenen türleri içerebilir. Bu liste tam kapsamlı değildir ve değişebilir.
floor
, bina adresinin tabanını belirtir.establishment
genellikle henüz sınıflandırılmamış bir yeri belirtir.landmark
, gezinmeye yardımcı olmak için referans olarak kullanılan yakındaki bir yeri belirtir.point_of_interest
, önemli bir önemli nokta olduğunu gösterir.parking
, bir park yerini veya otopark yapısını belirtir.post_box
belirli bir posta kutusunu belirtir.postal_town
, bazı ülkelerde posta adresleri için kullanılanlocality
vesublocality
gibi coğrafi bölgelerin grubunu gösterir.room
, bina adresinin bulunduğu odayı belirtir.street_number
tam sokak numarasını belirtir.bus_station
,train_station
vetransit_station
; otobüs, tren veya toplu taşıma durağının konumunu belirtir.
Görüntü alanına ağırlık verme
Coğrafi kodlama isteğinde, Coğrafi Kodlama hizmetine belirli bir görüntü alanındaki (sınırlayıcı kutu olarak ifade edilir) sonuçları tercih etmesini söyleyebilirsiniz. Bunu, bounds
parametresini ayarlayarak istek URL'sinde yapabilirsiniz.
bounds
parametresi, koordinatları ayırmak için bir dik çizgi (|
) karakteri kullanarak bu sınırlayıcı kutunun güneybatı ve kuzeydoğu köşelerinin enlem/boylam koordinatlarını tanımlar.
Örneğin, "Washington"un coğrafi kodlama türü genellikle ABD'nin Washington eyaletini döndürür:
İstek:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Yanıt:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
Ancak, ABD'nin kuzeydoğusunda sınırlayıcı bir kutu tanımlayan bounds
bağımsız değişkeni eklemek, bu coğrafi kodlamanın Washington, D.C. şehrini döndürmesine neden olur:
İstek:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Yanıt:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Bölgeye ağırlık verme
Coğrafi Kodlama isteğinde, region
parametresini kullanarak Coğrafi Kodlama hizmetine belirli bir bölgeye ağırlık veren sonuçları döndürmesi için talimat verebilirsiniz. Bu parametre, bölge sapmasını belirten bir ccTLD (ülke kodu üst düzey alan) bağımsız değişkeni alır. Çoğu ccTLD kodu, bazı önemli istisnalar dışında ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık ccTLD'si "uk" (.co.uk
) iken ISO 3166-1 kodu "gb"dır (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallığı" için).
Coğrafi kodlama sonuçları, ana Google Haritalar uygulamasının resmi olarak kullanıma sunulduğu her alan için taraflı olabilir. ağırlık vermenin yalnızca belirli bir alan adına ait sonuçları tercih ettiğini unutmayın. bu alanın dışında daha alakalı sonuçlar varsa sonuçlar da dahil edilebilir.
Örneğin, Geocode API'nin varsayılan alanı ABD olarak ayarlandığından "Toledo" için coğrafi kodlama bu sonucu döndürür. İstek:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
Yanıt:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
"Toledo" için region=es
(İspanya) ile ilgili bir coğrafi kodlama isteği, İspanya şehri döndürecektir.
İstek:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Yanıt:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Bileşen filtreleme
Coğrafi Kodlama yanıtında, Geokodlama API'si belirli bir alanla sınırlandırılmış adres sonuçlarını döndürebilir. Kısıtlamayı components
filtresini kullanarak belirtebilirsiniz. Filtre, dikey çizgiyle (|
) ayrılmış component:value
çifti listesinden oluşur. Filtre değerleri, diğer coğrafi kodlama istekleriyle aynı yazım düzeltme ve kısmi eşleme yöntemlerini destekler. Kodlayıcı, bir bileşen filtresi için kısmi eşleşme bulursa yanıtta bir partial_match
alanı yer alır.
Filtrelenebilir components
şunlardır:
postal_code
,postal_code
vepostal_code_prefix
ile eşleşiyor.country
, bir ülke adıyla veya iki harfli ISO 3166-1 ülke koduyla eşleşir. API, ülkeleri tanımlamak için ISO standardını uygular ve filtreleme, ülkenin ilgili ISO kodunu kullanırken en iyi sonucu verir.
Sonuçları etkilemek için aşağıdaki components
kullanılabilir ancak zorunlu kılınmaz:
route
bir rotanın uzun veya kısa adıyla eşleşiyor.locality
,locality
vesublocality
türleriyle eşleşiyor.administrative_area
, tümadministrative_area
seviyeleriyle eşleşiyor.
Bileşen filtreleme hakkında notlar:
- Bu bileşen filtrelerini isteklerde tekrarlamayın. Aksi takdirde API
Invalid_request
değerini döndürür:country
,postal_code
,route
- İstek tekrarlanan bileşen filtreleri içeriyorsa API, bu filtreleri VEYA olarak değil, VE olarak değerlendirir.
- Sonuçlar, zaman zaman beklenmeyen
ZERO_RESULTS
yanıtları veren Google Haritalar ile tutarlıdır. Yer Otomatik Tamamlama özelliğini kullanmak, bazı durumlarda daha iyi sonuçlar sağlayabilir. Daha fazla bilgi edinmek için bu SSS sayfasına göz atın. - Her adres bileşenini hem
address
parametresinde hem decomponents
filtresinde belirtin, ancak ikisinde birden kullanmayın. Her ikisinde de aynı değerlerin belirtilmesiZERO_RESULTS
ile sonuçlanabilir.
"High St, Hastings" için kullanılan components=country:GB
kodu, ABD'deki Hastings-On-Hudson yerine Hastings, İngiltere'de sonuç döndürüyor.
İstek:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Yanıt:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
"Santa Cruz" (components=country:ES
ile birlikte) için coğrafi kodlama isteği, İspanya'nın Kanarya Adaları'ndaki Santa Cruz de Tenerife'yi döndürüyor.
İstek:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
Yanıt:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Bileşen filtreleme, yalnızca birbirlerini hariç tutan filtreler sağlarsanız ZERO_RESULTS
yanıtı döndürür.
İstek:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
Yanıt:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
components
filtresini kullanarak, adres parametresi olmadan geçerli sorgular oluşturabilirsiniz. (Tam adresi coğrafi olarak kodlarken istek, binaların adlarını ve numaralarını içeriyorsa address
parametresi gerekir.)
İstek:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Yanıt:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}