İstek
Geocoding API isteği aşağıdaki biçimdedir:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
Burada outputFormat, aşağıdaki değerlerden biri olabilir:
json(önerilir), JavaScript Object Notation (JSON) biçiminde çıkış yapılacağını belirtir. veyaxml, XML biçiminde çıkışı gösterir.
HTTPS gereklidir.
Bazı parametreler zorunlu, bazıları ise isteğe bağlıdır. URL'lerde standart olduğu gibi, parametreler ve işareti (&) karakteri kullanılarak ayrılır.
Bu sayfanın geri kalanında, her istek türü için farklı parametreler kullanılabildiğinden coğrafi kodlama ve tersine coğrafi kodlama ayrı ayrı açıklanmaktadır.
Coğrafi kodlama (enlem/boylam arama) parametreleri
Coğrafi kodlama isteğinde gerekli parametreler:
key: Uygulamanızın API anahtarı. Bu anahtar, kota yönetimi amacıyla uygulamanızı tanımlar. Anahtar almayı öğrenin.İstekte
addressveyacomponentsya da her ikisini birden belirtmeniz gerekir:address: Coğrafi kodunu almak istediğiniz açık adres veya Plus Code. Not: Adres coğrafi kodlaması, enlem ve boylam koordinatlarını veya bir adresi ya da Plus Code'u temsil etmeyen diğer yapılandırılmamış dizeleri çözümlemez. Bu tür dizeleri kullanan istekler desteklenmez ve hata yanıtlarına veya belirtilmemiş davranışlara yol açabilir. Desteklenmeyen sorgulara örnek olarak şunlar verilebilir:
Adresleri, ilgili ülkenin ulusal posta hizmeti tarafından kullanılan biçime uygun olarak 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 URL çıkışlı olarakSorgu türü Örnek Enlem ve boylam koordinatları. Bunun yerine tersine coğrafi kodlama kullanın. "37.422131,-122.084801" Tek bir sorguda birden fazla yer, yol veya şehir adı gibi çok fazla kavram ya da kısıtlama "Market Street San Francisco San Jose Airport" Google Haritalar'da gösterilmeyen posta adresi öğeleri "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"İşletme, zincir veya kategorilerin, bu varlıkların bulunmadığı konumlarla birleştirilmiş adları "Dallas, Teksas yakınlarındaki Tesco" Birden fazla yorumu olan belirsiz sorgular "Şarj cihazı bırakma" Artık kullanılmayan eski adlar "Middlesex Birleşik Krallık" Coğrafi olmayan öğeler veya niyet "Ventura Limanı'nda kaç tekne var?" Resmi olmayan veya özel adlar "Jenga"
"Helter Skelter"%20şeklinde gösterilmiştir):address=24%20Sussex%20Drive%20Ottawa%20ON
%2B, boşluklar ise URL çıkışlı olarak%20şeklinde gösterilir):- global code, 4 karakterlik bir alan kodu ve 6 karakter veya daha uzun bir yerel koddur (849VCWC8+R9,
849VCWC8%2BR9şeklindedir). - Bileşik kod, açık bir konum içeren 6 karakter veya daha uzun bir yerel koddur (CWC8+R9 Mountain View, CA, ABD,
CWC8%2BR9%20Mountain%20View%20CA%20USAşeklindedir).
- global code, 4 karakterlik bir alan kodu ve 6 karakter veya daha uzun bir yerel koddur (849VCWC8+R9,
components: Öğeleri dikey çizgiyle (|) ayrılmış bir bileşen filtresi. Bileşen filtresi,addresssağ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ıdan gelen sonuçları tamamen kısıtlar. Bileşen filtreleme hakkında daha fazla bilgi için aşağıya bakın.
Daha fazla bilgi için SSS sayfasını inceleyin.
Geocoding isteğindeki isteğe bağlı parametreler:
bounds: Coğrafi kod sonuçlarının daha belirgin bir şekilde yönlendirileceği görüntü alanının sınırlayıcı kutusu. Bu parametre, coğrafi kodlayıcıdan gelen sonuçları tamamen kısıtlamaz, yalnızca etkiler. (Daha fazla bilgi için aşağıdaki Görüntü Alanı Eğilimi bölümüne bakın.)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 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 yerel halk tarafından okunabilen bir açık adres sağlamak için elinden geleni yapar. Bu amaca ulaşmak için açık adresleri yerel dilde döndürür. Gerekirse tercih edilen dili dikkate alarak kullanıcı tarafından okunabilir bir alfabeye dönüştü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 dilde döndürülür.
- Tercih edilen dilde bir ad yoksa coğrafi kodlayıcı en yakın eşleşmeyi kullanır.
- Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç kümesi ve bunların döndürülme sırası üzerinde küçük bir etkiye sahiptir. Coğrafi kodlayıcı, kısaltmaları dile göre farklı şekilde yorumlar. Örneğin, sokak türlerinin kısaltmaları veya bir dilde geçerli olup başka bir dilde geçerli olmayan eş anlamlı kelimeler buna örnek verilebilir. Örneğin, Macarcada utca ve tér, sırasıyla sokak ve meydan kelimelerinin eş anlamlılarıdır.
region: İki karakterli bir ccTLD ("üst düzey alan") değeri olarak belirtilen bölge kodu. Bu parametre, coğrafi kodlayıcıdan gelen sonuçları tamamen kısıtlamaz, yalnızca etkiler. (Daha fazla bilgi için aşağıdaki Bölgeye Göre Önyargı bölümüne bakın.) Parametre, geçerli yasaya göre sonuçları da etkileyebilir.components: Öğeleri dikey çizgiyle (|) ayrılmış bir bileşen filtresi. İstek biraddressiçermiyorsa bileşen filtresi gerekli olur. 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 bilgi için aşağıya bakın.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ı bölümüne bakın.BUILDING_AND_ENTRANCES: Daha fazla bilgi için girişler ve bina ana hatları bölümüne bakın.
extra_computationsparametresini ekleyin. Örneğin:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
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 Geocoding API, "1600 Amphitheatre Parkway, Mountain View, CA" adresiyle ilgili bir sorgu için json yanıtı ister.
Bu istekte JSON output işaretinin kullanımı gösterilmektedir:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Bu istekte XML output işaretinin kullanımı gösterilmektedir:
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", istekle ilgili meta verileri içerir. Aşağıdaki Durum kodları bölümüne bakın."results", coğrafi kodlu adres bilgileri ve geometri bilgilerinden oluşan bir dizi içerir.
Genellikle adres aramaları için "results" dizisinde yalnızca bir giriş döndürülür ancak 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>, istekle ilgili meta verileri içerir. Aşağıdaki Durum kodları bölümüne bakın.- Her biri tek bir coğrafi kodlu adres bilgisi ve geometri bilgisi kümesi 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 tercih edilen çıkış işareti olarak json kullanmanızı öneririz.
Ayrıca, XML ağaçlarını işlerken doğru düğümlere ve öğelere referans vermek için dikkatli olmanız gerekir. Çıkış işleme için önerilen bazı tasarım kalıplarını
XPath ile XML ayrıştırma bölümünde bulabilirsiniz.
- XML sonuçları, kök
<GeocodeResponse>öğesiyle sarmalanır. - JSON, birden fazla öğe içeren girişleri çoğul dizilerle (
types) belirtirken XML, bunları birden fazla tekil öğe (<type>) kullanarak belirtir. - Boş öğeler, JSON'da boş dizilerle, XML'de ise bu tür öğelerin bulunmamasıyla belirtilir. Örneğin, sonuç üretmeyen bir yanıt, JSON'da boş bir
resultsdizisi döndürür 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ı bulmanıza yardımcı olacak hata ayıklama bilgilerini içerebilir. "status" alanı aşağıdaki değerleri içerebilir:
"OK", hata oluşmadığını, adresin başarıyla ayrıştırıldığını ve en az bir coğrafi kodun döndürüldüğünü gösterir."ZERO_RESULTS", coğrafi kodun başarılı olduğunu ancak sonuç döndürmediğini gösterir. Coğrafi kodlayıcıya mevcut olmayan biraddressiletildiğinde bu durum yaşanabilir.OVER_DAILY_LIMITaşağıdakilerden herhangi birini gösterir:- API anahtarı eksik veya geçersiz.
- Hesabınızda faturalandırma etkinleştirilmemiştir.
- Kullanıcının kendisi için belirlediği kullanım sınırı aşıldı.
- Sağlanan ödeme yöntemi artık geçerli değilse (ör. kredi kartının süresi dolmuşsa)
Bu sorunu nasıl düzelteceğinizi öğrenmek için Haritalar SSS bölümüne bakın.
"OVER_QUERY_LIMIT", kotanızı aştığınızı gösterir."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 nesnesinde ek bir error_message alanı olabilir. Bu alan, verilen durum kodunun nedenleri hakkında daha ayrıntılı bilgi içerir.
Sonuçlar
Coğrafi kodlayıcı, sonuçları döndürdüğünde bunları bir (JSON) results dizisine yerleştirir. Coğrafi kodlayıcı sonuç döndürmese bile (ör. adres mevcut değilse) boş bir results dizisi döndürür. (XML yanıtları sıfır veya daha fazla <result> öğesinden oluşur.)
Tipik 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 sıfır veya daha fazla etiket içerir. Örneğin, "Chicago" coğrafi kodu, "Chicago"nun bir şehir olduğunu belirten "locality" (yerleşim yeri) ve siyasi bir varlık olduğunu belirten "political" (siyasi) değerlerini döndürür. Daha fazla bilgi için Adres türleri ve adres bileşeni türleri başlıklı makaleyi inceleyin.formatted_address, bu konumun okunabilir adresini içeren bir dizedir.Bu adres genellikle posta adresiyle aynıdır. Birleşik Krallık gibi bazı ülkelerde, lisans 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 programatik olarak ayrıştırmayın. Bunun yerine, API yanıtının biçimlendirilmiş adres alanına ek olarak içerdiği ayrı 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. Adres bileşeni için bilinen bir tür yoksa adres bileşeninin tür dizisi boş olabilir. API, gerektiğinde yeni tür değerleri ekleyebilir. Daha fazla bilgi için Adres türleri ve adres bileşeni türleri başlıklı makaleyi inceleyin.long_name, Geocoder 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şenininlong_namedeğeri "Alaska" veshort_namedeğeri, 2 harfli posta kısaltması kullanılarak "AK" olabilir.
address_components[]dizisiyle ilgili aşağıdaki bilgileri göz önünde bulundurun:- Adres bileşenleri dizisi,
formatted_addressdeğerinden daha fazla bileşen içerebilir. - Dizi,
formatted_addressiçinde yer alanlar dışında, adres içeren tüm siyasi varlıkları içermeyebilir. Belirli bir adresi içeren tüm siyasi varlıkları almak için tersine coğrafi kodlama kullanmanız ve adresin enlem/boylamını 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. Belirli bir bileşen sonraki bir yanıtta eksik olabilir.
Bileşen dizisini işlemek için yanıtı ayrıştırmanız ve ifadeler aracılığıyla uygun değerleri seçmeniz gerekir. Yanıt ayrıştırma kılavuzuna bakın.
postcode_localities[], bir posta kodunda bulunan en fazla 100 yerleşim yerini gösteren bir dizidir. Bu, yalnızca sonuç birden fazla yerleşim yeri içeren bir posta kodu olduğunda gösterilir.geometryaşağıdaki bilgileri içerir:location, coğrafi kodlu enlem ve boylam değerini içerir. Normal adres aramaları için bu alan genellikle en önemli alandı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 düzeyine kadar doğru konum bilgisine 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 enterpolasyonla hesaplanan bir yaklaşık değeri (genellikle bir yol üzerinde) yansıttığını gösterir. Ara değer hesaplamalı sonuçlar genellikle bir açık adres için çatı coğrafi kodları kullanılamadığında döndürülür."GEOMETRIC_CENTER", döndürülen sonucun, çoklu çizgi (ör. sokak) veya çokgen (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. Bu alan, görüntü alanı sınırlayıcı kutusununsouthwestvenortheastköşesini tanımlayan iki enlem, boylam değeri olarak belirtilir. Genellikle görüntü alanı, bir 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 tamamen 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ında döndürülmemesi gereken Farallon Adaları'nı içerir.)
-
plus_code(Açık Konum Kodu ve Plus Code'lar bölümüne bakın), enlem ve boylam koordinatlarından türetilen ve bir alanı temsil eden kodlanmış bir konum referansıdır: 1/8000 dereceye 1/8000 derece (ekvatorda yaklaşık 14 m x 14 m) veya daha küçük. Plus Code'lar, adreslerin bulunmadığı yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı yerler) açık adreslerin yerine kullanılabilir. API her zaman Plus Code döndürmez.Hizmet bir Plus Code döndürdüğünde bu kod, global kod ve bileşik kod olarak biçimlendirilir:
global_code, 4 karakterlik bir alan kodu ve 6 karakter veya daha uzun bir yerel koddan (849VCWC8+R9) oluşur.compound_code, açık bir konum içeren 6 karakter veya daha uzun bir yerel koddur (CWC8+R9, Mountain View, CA, ABD). Bu içeriği programatik olarak 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. Orijinal istekte yazım hataları ve/veya eksik adres olup olmadığını inceleyebilirsiniz.Kısmi eşleşmeler genellikle istekte ilettiğiniz bölgede bulunmayan açık adresler için gerçekleşir. Bir istek aynı bölgedeki 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" araması hem Henry Street hem de Henrietta Street için kısmi eşleşme döndürür. Bir istekte yanlış yazılmış bir 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ılabilen benzersiz bir tanımlayıcıdır. Örneğin, bir yerel işletmenin telefon numarası, çalışma saatleri, kullanıcı yorumları ve diğer bilgileri almak için Places API isteğindeplace_idkullanabilirsiniz. Yer kimliğine genel bakış bölümünü inceleyin.
Adres türleri ve adres bileşeni türleri
Yanıttaki types dizisi, adres türünü belirtir. Adres türlerine örnek olarak açık adres, ülke veya siyasi bir varlık verilebilir. address_component alanındaki types dizisi, adresin her bir bölümünün türünü belirtir. Bina numarası veya ülke buna örnek olarak verilebilir.
Adreslerin birden fazla türü olabilir. Türler "etiket" olarak kabul edilebilir.
Örneğin, birçok şehir political ve locality türleriyle etiketlenir.
Aşağıdaki türler desteklenir ve hem adres türü hem de adres bileşeni türü dizilerinde döndürülür:
| Adres Türü | Açıklama |
|---|---|
street_address |
Tam açık adres. |
route |
Adlandırılmış bir rota (ör. "US 101"). |
intersection |
Genellikle iki ana yolun kesiştiği büyük bir kavşak. |
political |
Siyasi tüzel kişi Genellikle bu tür, bir sivil idarenin poligonunu gösterir. |
country |
Ulusal siyasi varlıktır ve genellikle Coğrafi Kodlayıcı tarafından döndürülen en yüksek düzeydeki türdür. |
administrative_area_level_1 |
Ülke düzeyinin altındaki birinci dereceden idari bölge. Amerika Birleşik Devletleri'nde bu idari düzeyler eyaletlerdir. Bu idari düzeyler bazı ülkelerde kullanılmaz. Çoğu durumda administrative_area_level_1 kısa adları, ISO 3166-2 alt bölümleri ve yaygın olarak kullanılan diğer listelerle büyük ölçüde 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ındaki ikinci dereceden idari bölge. Amerika Birleşik Devletleri'nde bu idari düzeyler ilçelerdir. Bu idari düzeyler bazı ülkelerde kullanılmaz. |
administrative_area_level_3 |
Ülke düzeyinin altındaki üçüncü düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz. |
administrative_area_level_4 |
Ülke düzeyinin altındaki dördüncü düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz. |
administrative_area_level_5 |
Ülke düzeyinin altındaki beşinci düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz. |
administrative_area_level_6 |
Ülke düzeyinin altındaki altıncı düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz. |
administrative_area_level_7 |
Ülke düzeyinin altındaki yedinci düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz. |
colloquial_area |
Varlığın yaygın olarak kullanılan alternatif adı. |
locality |
Tüzel kişiliğe sahip bir şehir veya kasaba siyasi kuruluşu. |
sublocality |
Bir yerleşim yerinin altındaki birinci dereceden idari bölge. Bazı konumlarda ek türlerden biri (sublocality_level_1 - sublocality_level_5) gösterilebilir. Her alt idari bölge düzeyi bir sivil tüzel kişidir. Daha büyük sayılar daha küçük bir coğrafi alanı gösterir. |
neighborhood |
Adlandırılmış bir mahalle. |
premise |
Adlandırılmış bir konum. Genellikle bir bina veya ortak adı olan bir bina grubudur. |
subpremise |
Tesis düzeyinin altında, adreslenebilir bir varlık (ör. apartman dairesi, birim veya süit). |
plus_code |
Enlem ve boylamdan türetilen, kodlanmış bir konum referansı. Plus Kodlar, açık adreslerin bulunmadığı yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı yerler) açık adreslerin yerine kullanılabilir. Ayrıntılar için https://plus.codes adresini ziyaret edin. |
postal_code |
Ülke içinde posta göndermek için kullanılan posta kodu. |
natural_feature |
Belirgin bir doğal özellik. |
airport |
Havaalanı. |
park |
Adlandırılmış bir park. |
point_of_interest |
Adlandırılmış önemli yer. Genellikle bu "ÖY"ler, "Empire State Binası" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca uymayan önemli yerel öğelerdir. |
Boş bir tür listesi, belirli adres bileşeni için bilinen bir tür olmadığını gösterir (örneğin, Fransa'da Lieu-dit).
Yukarıdakilere ek olarak, adres bileşenleri aşağıda listelenen türleri içerebilir.
| Adres Bileşeni Türü | Açıklama |
|---|---|
floor |
Bina adresinin katı. |
establishment |
Genellikle henüz kategorize edilmemiş bir yerdir. |
landmark |
Navigasyona yardımcı olmak için referans olarak kullanılan yakındaki bir yer. |
point_of_interest |
Adlandırılmış önemli yer. |
parking |
Otopark veya katlı otopark. |
post_box |
Belirli bir posta kutusu. |
postal_town |
Bazı ülkelerde posta adresleri için kullanılan, locality ve sublocality gibi coğrafi alanların gruplandırılması. |
room |
Bina adresinin oda bilgisi. |
street_number |
Tam sokak numarası. |
bus_station, train_station ve transit_station |
Otobüs, tren veya toplu taşıma durağının konumu. |
Görüntü alanı ağırlıklandırması
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, istek URL'sinde bounds parametresini ayarlayarak yaparsınız.
bounds parametresi, bu sınırlayıcı kutunun güneybatı ve kuzeydoğu köşelerinin enlem/boylam koordinatlarını tanımlar. Koordinatları ayırmak için dikey çizgi (|) karakteri kullanılır.
Örneğin, "Washington" için bir coğrafi kod 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ğu kısmını çevreleyen 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 göre ağırlıklandırma
Coğrafi kodlama isteğinde, region parametresini kullanarak coğrafi kodlama hizmetine belirli bir bölgeye göre sonuca ağırlık verme talimatını verebilirsiniz. Bu parametre, bölge tercihini 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'ın ccTLD'si "uk" (.co.uk) iken ISO 3166-1 kodu "gb"dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallığı" tüzel kişiliği 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. Yönlendirmenin yalnızca belirli bir alan için sonuçları tercih ettiğini unutmayın. Bu alanın dışında daha alakalı sonuçlar varsa bunlar dahil edilebilir.
Örneğin, Geocoding API'nin varsayılan alanı ABD olarak ayarlandığından "Toledo" için bir 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 bir coğrafi kodlama isteği, İspanya'daki şehri 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
Geocoding API, Geocoding yanıtında belirli bir alanla sınırlı adres sonuçları döndürebilir. Kısıtlamayı components filtresini kullanarak belirtebilirsiniz. Filtre, çizgi (|) ile ayrılmış component:value çiftlerinin 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ıtta bir partial_match alanı bulunur.
Filtrelenebilecek components şunlardır:
postal_code,postal_codevepostal_code_prefixile 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ı kullanır 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 tutulmaz:
route, bir rotanın uzun veya kısa adıyla eşleşir.locality,localityvesublocalitytürleriyle eşleşir.administrative_area, tümadministrative_areaseviyeleriyle eşleşir.
Bileşen filtreleme hakkında notlar:
- İsteklerde bu bileşen filtrelerini tekrarlamayın. Aksi takdirde API,
Invalid_request:country,postal_code,routedöndürür. - İstek yinelenen bileşen filtreleri içeriyorsa API bu filtreleri VEYA olarak değil, VE olarak değerlendirir.
- Sonuçlar, bazen beklenmedik
ZERO_RESULTSyanıtları veren Google Haritalar ile tutarlıdır. Yer Adı Otomatik Tamamlama'yı kullanmak, bazı kullanım alanlarında daha iyi sonuçlar verebilir. Daha fazla bilgi için bu SSS sayfasına bakın. - Her adres bileşenini
addressparametresinde veyacomponentsfiltresinde belirtin ancak ikisinde birden belirtmeyin. Her ikisinde de aynı değerlerin belirtilmesiZERO_RESULTSile sonuçlanabilir.
components=country:GB ile "High St, Hastings" için yapılan bir coğrafi kod araması, ABD'deki Hastings-On-Hudson yerine İngiltere'deki Hastings'de bir 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"
}
components=country:ES ile "Santa Cruz" yerleşim yeri için yapılan bir coğrafi kod isteği, İspanya'nın Kanarya Adaları'ndaki Santa Cruz de Tenerife'yi 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 yapabilirsiniz. (Tam bir adresin coğrafi kodlaması yapılırken istekte binaların adları ve numaraları varsa address parametresi gereklidir.)
İ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"
}