İstek
Coğrafi Kodlama API'si isteği aşağıdaki biçimdedir:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
Bu örnekte outputFormat, aşağıdaki değerlerden biri olabilir:
json(önerilen), JavaScript Object Notation'daki (JSON) çıkışı belirtir veyaxml, XML'deki çıkışı gösterir
HTTPS gerekli.
Bazı parametreler zorunlu, bazıları ise isteğe bağlıdır. URL'lerde standart olduğu gibi parametreler, "ve" (&) karakteri kullanılarak ayrılır.
Her istek türü için farklı parametreler kullanılabildiğinden bu sayfanın geri kalanında, coğrafi kodlama ve ters coğrafi kodlama ayrı ayrı açıklanmaktadır.
Coğrafi kodlama (enlem/boylam arama) parametreleri
Coğrafi kodlama isteğindeki gerekli parametreler:
address— Coğrafi kodlamak istediğiniz açık adres veya artı kodu. Adresleri, ilgili ülkenin ulusal posta servisi tarafından kullanılan biçime göre belirtin. İşletme adları ve birim, daire veya kat numaraları gibi ek adres öğelerinden kaçınılmalıdır. Açık adres öğeleri boşluklarla ayrılmalıdır (burada%20öğesine çıkışlı URL şeklinde gösterilmektedir):address=24%20Sussex%20Drive%20Ottawa%20ON
Artı kodlarını burada gösterildiği gibi biçimlendirin (artı işaretler%2Biçin URL çıkışlı, boşluklar ise%20için URL çıkışlıdır):- global kod, 4 karakterli alan kodu ve 6 veya daha uzun bir yerel koddur (849VCWC8+R9,
849VCWC8%2BR9şeklindedir). - bileşik kod, açık bir konumu olan 6 karakter veya daha uzun bir yerel koddur (CWC8+R9 Mountain View, CA, ABD,
CWC8%2BR9%20Mountain%20View%20CA%20USAşeklindedir).
--OR--
components— Dikey çizgiyle (|) ayrılmış öğelerin yer aldığı bir bileşen filtresi. Bileşen filtresi,addresssağlanırsa isteğe bağlı bir parametre olarak da kabul edilir. Bileşen filtresindeki her öğe, bircomponent:valueçiftinden oluşur ve coğrafi kodlayıcıdan gelen sonuçları tamamen kısıtlar. Bileşen filtreleme hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.- global kod, 4 karakterli alan kodu ve 6 veya daha uzun bir yerel koddur (849VCWC8+R9,
key— Uygulamanızın API anahtarı. Bu anahtar, kota yönetimi amacıyla uygulamanızı tanımlar. Nasıl anahtar alacağınızı öğrenin.
Daha fazla bilgi için lütfen SSS bölümüne bakın.
Coğrafi Kodlama isteğindeki isteğe bağlı parametreler:
bounds— Coğrafi kodlamada daha belirgin sonuçlar elde edilecek görüntü alanının sınırlayıcı kutusu. Bu parametre yalnızca coğrafi kodlayıcıdan gelen sonuçları etkiler, tam olarak kısıtlamaz. (Daha fazla bilgi için aşağıdaki Görünüme Ağırlık Verme konusuna bakın.)language— Sonuçların döndürüleceği dil.- Desteklenen dillerin listesini inceleyin. Google, desteklenen dilleri sıklıkla güncellediğinden bu liste tam kapsamlı olmayabilir.
languagesağlanmazsa coğrafi kodlayıcı,Accept-Languagebaşlığında belirtilen tercih edilen dili veya isteğin gönderildiği alanın ana dilini kullanmaya çalışır.- Coğrafi kodlayıcı, hem kullanıcı hem de bölge sakinlerinin okuyabileceği bir açık adres sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için yerel dildeki açık adresleri, gerekirse kullanıcı tarafından okunabilecek bir alfabeye dönüştürülerek tercih edilen dile uyarlar. 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şleşmeyi kullanır.
- Tercih edilen dilin, API'nin döndürmeyi seçtiği sonuç kümesi ve döndürülme sırası üzerinde küçük bir etkisi vardır. Coğrafi kodlayıcı, kısaltmaları dile bağlı olarak farklı şekillerde yorumlar. Örneğin, sokak türlerinin kısaltmaları ya da bir dilde geçerli olup başka bir dilde geçerli olmayan eş anlamlı kelimeler olabilir. Örneğin, Macarcada utca ve tér sırasıyla sokak ve kare için eş anlamlıdır.
region— ccTLD ("üst düzey alan") olarak iki karakterlik değer olarak belirtilen bölge kodu. Bu parametre yalnızca coğrafi kodlayıcıdan gelen sonuçları etkiler, tam olarak kısıtlamaz. (Daha fazla bilgi için aşağıdaki Bölgeye Ağırlık Verme bölümüne bakın.) Bu parametre, geçerli yasalara göre sonuçları da etkileyebilir.components: Öğelerin dikey çizgiyle (|) ayrılmış olduğu bir bileşen filtresi. İstekaddressiçermiyorsa bileşen filtresi gereklidir. Bileşen filtresindeki her öğe, bircomponent:valueçiftinden oluşur ve coğrafi kodlayıcıdan gelen sonuçları tamamen kısıtlar. Bileşen filtreleme hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.extra_computations: Bu parametre için izin verilen tek değerADDRESS_DESCRIPTORSdeğeridir. Daha fazla bilgi için adres tanımlayıcıları bölümüne bakın.
Yanıtlar
Coğrafi kodlama yanıtları, URL isteği içinde output işareti ile belirtilen biçimde veya varsayılan olarak JSON biçiminde döndürülür.
Bu örnekte Geocoding API, "1600 Amphitheatre Parkway, Mountain View, CA" adresiyle ilgili bir sorgu için json yanıtı istiyor.
Bu istek, JSON output işaretinin kullanımını gösterir:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Bu istek, XML output işaretinin kullanımını gösterir:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&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"
]
},
{
"long_name": "1351",
"short_name": "1351",
"types": [
"postal_code_suffix"
]
}
],
"formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry": {
"location": {
"lat": 37.4222804,
"lng": -122.0843428
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 37.4237349802915,
"lng": -122.083183169709
},
"southwest": {
"lat": 37.4210370197085,
"lng": -122.085881130292
}
}
},
"place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
"plus_code": {
"compound_code": "CWC8+W7 Mountain View, CA",
"global_code": "849VCWC8+W7"
},
"types": [
"street_address"
]
}
],
"status": "OK"
}
JSON yanıtının iki kök öğe içerdiğini unutmayın:
"status", istekte meta verileri içeriyor. Aşağıdaki Durum kodları bölümüne bakın."results", coğrafi olarak kodlanmış adres bilgileri ve geometri bilgilerinden oluşan bir dizi içerir.
Adres aramaları için genellikle "results" dizisinde yalnızca bir giriş döndürülür. Bununla birlikte, adres sorguları belirsiz olduğunda coğrafi kodlayıcı 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>, istekte meta verileri içeriyor. Aşağıdaki Durum kodları bölümüne bakın.- Sıfır veya daha fazla
<result>öğesi. Her biri coğrafi olarak kodlanmış adres bilgileri ve geometri bilgilerinden oluşan tek bir küme içerir.
XML yanıtı, JSON yanıtından oldukça uzundur. Bu nedenle, hizmetiniz herhangi bir nedenle xml gerektirmediği sürece tercih edilen çıkış işareti olarak json kullanmanızı öneririz.
Ayrıca, XML ağaçlarını işlemek için uygun düğüm ve öğelere referans verebilmeniz için biraz özen gerekir. Çıkış işlemeyle ilgili önerilen bazı tasarım kalıpları için
XPath ile XML ayrıştırma bölümüne bakın.
- XML sonuçları bir kök
<GeocodeResponse>öğesinde sarmalanır. - JSON, birden çok öğe içeren girişleri çoğul diziler (
types) ile belirtirken XML ise bunları birden çok tekil öğe (<type>) kullanarak belirtir. - Boş öğeler, JSON'da boş diziler aracılığıyla ancak XML'de böyle bir öğenin bulunmamasıyla belirtilir. Sonuç üretmeyen bir yanıt, JSON'de boş bir
resultsdizisi döndürmez ancak XML'de<result>öğesi 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ı öğrenmenize yardımcı olacak hata ayıklama bilgilerini içerebilir. "status" alanı şu değerleri içerebilir:
"OK", hiçbir hata oluşmadığını belirtir; adresin başarıyla ayrıştırıldığını ve en az bir coğrafi kod 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 gösterir. Bu durum, coğrafi kodlayıcıya var olmayan biraddresskodundan geçilmesi durumunda ortaya çıkabilir.OVER_DAILY_LIMITaşağıdakilerden herhangi birini gösterir:- API anahtarı eksik veya geçersiz.
- Hesabınızda faturalandırma etkinleştirilmedi.
- Kendi kendine belirlenen kullanım sınırı aşıldı.
- Belirtilen ödeme yöntemi artık geçerli değil (örneğin, bir kredi kartının süresi dolmuş).
Bu sorunu nasıl düzelteceğinizi öğrenmek için Haritalar hakkında SSS sayfasına bakın.
"OVER_QUERY_LIMIT", kotanızı aştığınızı gösteriyor."REQUEST_DENIED", isteğinizin reddedildiğini gösterir."INVALID_REQUEST"genellikle sorgunun (address,componentsveyalatlng) eksik olduğunu gösterir."UNKNOWN_ERROR", isteğin bir sunucu hatası nedeniyle işlenemediğini gösterir. Tekrar denerseniz istek başarılı olabilir.
Hata mesajları
Coğrafi kodlayıcı, OK dışında bir durum kodu döndürdüğünde, Coğrafi Kodlama yanıt nesnesi içinde ek bir error_message alanı olabilir. Bu alanda, belirtilen durum kodunun nedenleri hakkında daha ayrıntılı bilgiler yer alır.
Sonuçlar
Coğrafi kodlayıcı, sonuçları döndürdüğünde bunları bir (JSON) results dizisi içine yerleştirir. Coğrafi kodlayıcı hiçbir sonuç döndürmese bile (adresin olmaması gibi) yine de boş bir results dizisi döndürür. (XML yanıtları sıfır veya daha fazla <result> öğesinden oluşur.)
Normal bir sonuç aşağıdaki alanları içerir:
types[]dizisi, döndürülen sonucun türünü gösterir. Bu dizi, sonuçta döndürülen özelliğin türünü tanımlayan bir veya daha fazla etiket kümesi içerir. Örneğin, "Şikago"nun coğrafi kodu, "Chicago"nun bir şehir olduğunu belirten "locality" (yerellik) değerini ve aynı zamanda bu ülkenin politik bir varlık olduğunu belirten "politik" değerini döndürür. Adres bileşeni için bilinen bir tür olmadığında bileşenlerde boş tür dizisi olabilir. API, gerektiğinde yeni tür değerleri ekleyebilir. Daha fazla bilgi için Adres türleri ve adres bileşenleri başlıklı makaleye bakın.formatted_address, bu konumun kullanıcılar tarafından okunabilen adresini içeren bir dizedir.Bu adres genellikle posta adresine 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 unutmayın.
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 programlı olarak ayrıştırmayın. Bunun yerine, biçimlendirilmiş adres alanına ek olarak API yanıtının 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ü gösteren bir dizidir. Desteklenen türler listesine bakın.long_name, Coğrafi Kodlayıcı tarafından döndürülen adres bileşeninin tam metin açıklaması veya adıdır.short_name, varsa adres bileşeninin kısaltılmış metin adıdır. Örneğin, Alaska eyaleti için bir adres bileşeninde 2 harfli posta kısaltması kullanılaraklong_name"Alaska" veshort_name"AK" bulunabilir.
address_components[]dizisiyle ilgili aşağıdaki gerçeklere dikkat edin:- Adres bileşenleri dizisi,
formatted_addressöğesinden daha fazla bileşen içerebilir. - Dizi,
formatted_addressiçinde yer alanların dışında, bir adres içeren tüm siyasi varlıkları içermeyebilir. Belirli bir adres içeren tüm siyasi varlıkları almak için tersine coğrafi kodlama kullanmanız ve adresin enlem/boylam değerlerini isteğe parametre olarak iletmeniz gerekir. - Yanıt biçiminin istekler arasında aynı kalacağı garanti edilmez. Özellikle
address_componentssayısı, istenen adrese göre değişir ve aynı adres için zaman içinde değişebilir. Bir bileşen, dizideki konumunu 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ıtları ayrıştırma rehberine bakın.
postcode_localities[], bir posta kodunda yer alan en fazla 100 yerleşimi belirten bir dizidir. Bu yalnızca sonuçta birden fazla şehir içeren bir posta kodu olduğunda mevcuttur.geometryaşağıdaki bilgileri içerir:location, coğrafi olarak kodlanmış enlem ve boylam değerini içeriyor. Normal adres aramaları için bu alan genellikle en önemlidir.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 kesinliğine kadar doğru konum bilgilerine sahip olduğumuz kesin bir coğrafi kod olduğunu gösterir."RANGE_INTERPOLATED", döndürülen sonucun iki kesin nokta (ör. kavşaklar) arasında interpolasyon yapılmış yaklaşık bir değeri (genellikle bir yolda) yansıttığını gösterir. İnterpole edilmiş sonuçlar genellikle bir sokak adresi için çatı coğrafi kodları kullanılamadığında döndürülür."GEOMETRIC_CENTER", döndürülen sonucun, çoklu çizgi (örneğin, sokak) veya poligon (bölge) gibi bir sonucun geometrik merkezi olduğunu belirtir."APPROXIMATE", döndürülen sonucun yaklaşık olduğunu belirtir.
viewport, döndürülen sonucu görüntülemek için önerilen görüntü alanını içerir. Bu görünüm, görüntü alanı sınırlayıcı kutusununsouthwestvenortheastköşesini tanımlayan iki enlem,boylam değeri olarak belirtilir. Genel olarak görüntü alanı, bir sonucu kullanıcıya görüntülerken çerçevelemek için kullanılır.bounds(isteğe bağlı olarak döndürülür), döndürülen sonucun tamamını 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 muhtemelen görüntü alanına döndürülmemesi gereken Farallon Adaları'nı da içerir.)
-
plus_code(bkz. Açık Konum Kodu ve artı kodları), enlem ve boylam koordinatlarından türetilen ve bir alanı temsil eden kodlanmış konum referansıdır: derecenin 1/8.000'i x derecenin 1/8.000'i (ekvatorda yaklaşık 14m x 14m) veya daha küçük. Adreslerin bulunmadığı yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı durumlarda) açık adreslerin yerine artı kodları kullanılabilir. API her zaman artı kodu döndürmez.Hizmet bir artı kodu döndürdüğünde, genel kod ve bileşik kod olarak biçimlendirilir:
global_code, 4 karakterli alan kodu ve 6 karakter veya daha uzun bir yerel koddur (849VCWC8+R9).compound_code, açık konumu olan, 6 karakter veya daha uzun bir yerel koddur (CWC8+R9, Mountain View, CA, ABD). Bu içeriği programlı bir şekilde ayrıştırmayın.
-
partial_match, coğrafi kodlayıcının orijinal istek için tam eşleşme döndürmediğini, ancak istenen adresin bir kısmını eşleştirebildiğini gösterir. Yazım hataları ve/veya eksik adres olup olmadığını kontrol etmek için orijinal isteği inceleyebilirsiniz.Kısmi eşleşmeler en sık, istekte belirttiğiniz bölgede bulunmayan açık adresler için gerçekleşir. Bir istek aynı konumdaki iki veya daha fazla konumla eşleştiğinde kısmi eşleşmeler de 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ürür. İstek yanlış yazılmış bir adres bileşeni içeriyorsa 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 yerel işletmenin telefon numarası, çalışma saatleri, kullanıcı yorumları gibi ayrıntılarını almak için Places API isteğindeplace_idkullanabilirsiniz. Yer kimliğine genel bakış sayfasını inceleyin.
Adres türleri ve adres bileşeni türleri
Sonuçtaki types[] dizisi, adres türünü belirtir. Adres türlerine örnek olarak açık adres, ülke veya siyasi tüzel kişi verilebilir. address_components[] içinde, adresin her bir bölümünün türünü gösteren bir types[] dizisi de bulunur. Bina numarası veya ülke bilgisi örnek olarak verilebilir. (Aşağıda türlerin tam listesi verilmiştir.) Adreslerin birden fazla türü olabilir. Türler, "etiketler" olarak kabul edilebilir.
Örneğin, birçok şehir political ve locality türüyle etiketlenir.
Aşağıdaki türler, hem adres türü hem de adres bileşeni türü dizilerinde coğrafi kodlayıcı tarafından desteklenir ve döndürülür:
street_address, tam açık adresi gösterir.route, adlandırılmış bir rotayı (ör. "TR 101") gösterir.intersection, genellikle iki ana yolu kapsayan ana bir kesişimi gösterir.political, siyasi bir tüzel kişiyi belirtir. Bu tür genellikle bir sivil yönetim poligonunu gösterir.country, ulusal siyasi kuruluşu gösterir 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ında birinci dereceden bir sivil tüzel kişiyi belirtir. ABD'de bu idari düzeyler eyalettir. Tüm uluslar bu idari düzeylerde değildir. Çoğu durumda, management_area_level_1 kısa adları, ISO 3166-2 alt bölümleri ve yaygın olarak dağıtılan diğer listelerle yakından eşleşir. Ancak coğrafi kodlama sonuçlarımız çeşitli sinyallere ve konum verilerine dayandığından bu durum garanti edilmez.administrative_area_level_2, ülke düzeyinin altında ikinci düzey bir sivil tüzel kişiyi gösterir. Bu idari düzeyler ABD'de ilçelerdir. Tüm uluslar bu idari düzeylerde değildir.administrative_area_level_3, ülke düzeyinin altında üçüncü taraf bir sivil tüzel kişiyi gösterir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.administrative_area_level_4, ülke düzeyinin altında dördüncü dereceden bir sivil tüzel kişiyi gösterir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.administrative_area_level_5, ülke düzeyinin altında beşinci düzey bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.administrative_area_level_6, ülke düzeyinin altında altıncı düzey bir sivil tüzel kişiyi gösterir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.administrative_area_level_7, ülke düzeyinin altında yedinci düzey sivil tüzel kişiyi gösterir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.colloquial_area, varlık için yaygın olarak kullanılan bir alternatif adı gösterir.locality, anonim bir şehir veya kasabadaki siyasi tüzel kişiyi belirtir.sublocality, bir konum altında birinci dereceden bir sivil tüzel kişiyi belirtir. Bazı konumlar için ek türlerden biri alınabilir:sublocality_level_1-sublocality_level_5. Her alt konum düzeyi bir sivil tüzel kişidir. Büyük sayılar daha küçük bir coğrafi alanı belirtir.neighborhood, adlandırılmış bir mahalleyi gösterirpremise, genellikle ortak bir ada sahip olan bir bina veya bina topluluğu olan adlandırılmış bir konumu gösterirsubpremise, adlandırılmış bir konumun altındaki birinci derece varlığı gösterir. Bu genellikle ortak bir ada sahip binalar içinde yer alan tek bir binadırplus_code, enlem ve boylamdan türetilen kodlanmış bir konum referansını gösterir. Artı kodları, var olmadıkları yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı durumlarda) açık adreslerin yerine kullanılabilir. Ayrıntılar için https://plus.codes sayfasına bakın.postal_code, ülke içindeki posta postaları için kullanılan posta kodunu belirtir.natural_featurebelirgin bir doğal özelliği gösterir.airport, bir 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 Binası" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca uymayan önemli yerel varlıklardır.
Boş bir tür listesi, belirli adres bileşeni için bilinen bir tür olmadığını gösterir (örneğin, Fransa'daki Lieu-dit).
Yukarıdakilere ek olarak, adres bileşenleri burada listelenen türleri de içerebilir. Bu liste tam kapsamlı değildir ve değiştirilebilir.
floorbir bina adresinin katını gösterir.establishmentgenellikle henüz sınıflandırılmamış bir yeri gösterir.landmark, navigasyona yardımcı olmak için referans olarak kullanılan yakındaki bir yeri gösterir.point_of_interest, adlandırılmış bir önemli yeri gösterir.parking, bir otopark veya otopark olduğunu belirtir.post_box, belirli bir posta kutusunu belirtir.postal_town, bazı ülkelerde posta adresleri için kullanılanlocalityvesublocalitygibi coğrafi alanlardan oluşan bir gruplandırmayı belirtir.room, bina adresinin bulunduğu odayı gösterir.street_numbertam sokak numarasını gösterir.bus_station,train_stationvetransit_stationotobüs, tren veya toplu taşıma durağının konumunu belirtir.
Görüntü alanına ağırlık verme
Bir Coğrafi Kodlama isteğinde, Coğrafi Kodlama hizmetine belirli bir görüntü alanı içindeki sonuçları tercih etmesi talimatını verebilirsiniz (sınırlayıcı kutu olarak ifade edilir). Bunu, bounds parametresini ayarlayarak istek URL'sinde yapabilirsiniz.
bounds parametresi, koordinatları ayırmak için dikey çizgi (|) karakteri kullanılarak bu sınırlayıcı kutunun güneybatı ve kuzeydoğu köşelerinin enlem/boylam koordinatlarını tanımlar.
Örneğin, "Washington" için coğrafi kod genellikle ABD'deki 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ğusu çevresinde bir sınırlayıcı kutu tanımlayan bounds bağımsız değişkeni eklendiğinde, bu coğrafi kod Washington, D.C. şehrini döndürür.
İ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
Bir Coğrafi Kodlama isteğinde, region parametresini kullanarak Coğrafi Kodlama hizmetine belirli bir bölgeye göre yanlı sonuçlar döndürmesi talimatını verebilirsiniz. Bu parametre, bölge yanlılığını belirten bir ccTLD (ülke kodu üst düzey alan) bağımsız değişkenini alır. ccTLD kodu, bazı önemli istisnalar dışında
ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk), ISO 3166-1 kodu "gb"dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda'nın Birleşik Krallık'ına ait tüzel kişi" için).
Ana Google Haritalar uygulamasının resmi olarak kullanıma sunulduğu her alan adı için coğrafi kodlama sonuçları önyargılı olabilir. Ağırlık vermenin yalnızca belirli bir alan adına ilişkin sonuçları tercih ettiğini unutmayın; bu alanın dışında daha alakalı sonuçlar varsa bunlar da dahil edilebilir.
Örneğin, Geocoding API'nin varsayılan alan adı ABD olarak ayarlandığından "Toledo" için coğrafi kod 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"
}
region=es (İspanya) ile "Toledo" için yapılan Coğrafi Kodlama isteği, İspanyol şehrini döndürür.
İ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, Geocoding API belirli bir alanla kısıtlanmış adres sonuçlarını döndürebilir. components filtresini kullanarak kısıtlamayı belirtebilirsiniz. Filtre, dikey çizgi (|) ile 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. Coğrafi kodlayıcı bir bileşen filtresi için kısmi eşleşme bulursa yanıt bir partial_match alanı içerir.
Filtrelenebilecek components şunlardır:
postal_code;postal_codevepostal_code_prefixile eşleşir.countrybir ü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 kodu kullanıldığında en iyi şekilde çalışır.
Aşağıdaki components, sonuçları etkilemek için kullanılabilir ancak zorunlu kılınmaz:
route, bir rotanın uzun veya kısa adıyla eşleşiyor.locality,localityvesublocalitytürleriyle eşleşiyor.administrative_area, tümadministrative_areaseviyeleriyle eşleşir.
Bileşen filtrelemeyle ilgili notlar:
- Bu bileşen filtrelerini isteklerde tekrarlamayın. Aksi takdirde API
Invalid_request:country,postal_code,routedeğerini döndürür. - İstek yinelenen bileşen filtreleri içeriyorsa API bu filtreleri VEYA olarak değil, VE olarak değerlendirir.
- Sonuçlar, Google Haritalar ile tutarlıdır. Bu durum, zaman zaman beklenmeyen
ZERO_RESULTSyanıtları verir. Otomatik Yer Tamamlama özelliği, bazı kullanım durumlarında daha iyi sonuçlar sağlayabilir. Daha fazla bilgi için bu SSS sayfasına göz atın. - Her bir adres bileşeni için bunu ya
addressparametresinde ya dacomponentsfiltresinde belirtin ancak ikisinde birden belirtmeyin. Her ikisinde de aynı değerlerin belirtilmesiZERO_RESULTSile sonuçlanabilir.
"High St, Hastings" için components=country:GB kodlu bir coğrafi kod, Hastings-On-Hudson, ABD yerine İngiltere'nin Hastings şehrinde sonuç döndürür.
İ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" bölgesi için components=country:ES ile birlikte gönderilen bir coğrafi kod isteği, İspanya'nın Kanarya Adaları'ndaki Santa Cruz de Tenerife şehrini döndürür.
İ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 birbirini 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 bir adresin coğrafi kodlaması yapılırken 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"
}