Coğrafi kodlama isteği ve yanıtı

İstek

Geocoding API 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 (önerilir), JavaScript Object Notation (JSON) çıktısını belirtir veya
• xml, XML olarak çıkışı gösterir

API anahtarı kullanan istekler için HTTPS gerekir.

Bazı parametreler zorunluyken bazıları isteğe bağlıdır. URL'lerde standart 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ı ayrı açıklanmaktadır.

Coğrafi kodlama (enlem/boylam arama) parametreleri

Coğrafi kodlama isteğinde gerekli parametreler:

• address — Coğrafi kodlamasını 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 %20 için URL çıkışlı olarak 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 çıkışlı olarak %20 içindir):
  • Global kod, 4 karakterden oluşan bir alan kodu ve 6 veya daha fazla yerel koddur (849VCWC8+R9, 849VCWC8%2BR9 şeklindedir).
  • Bileşik kod, açık bir konuma sahip (CWC8+R9 Mountain View, CA, ABD CWC8%2BR9%20Mountain%20View%20CA%20USA) 6 karakter veya daha uzun bir yerel koddur.
  
  --VEYA--
  components — Öğelerin dikey çizgiyle (|) ayrıldığı bileşen filtresi. address sağlanırsa bileşenler filtresi de isteğe bağlı parametre olarak kabul edilir. Bileşenler filtresindeki her öğe, bir component:value çiftinden oluşur ve coğrafi kodlayıcının sonuçlarını tamamen kısıtlar. Bileşen filtreleme hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.
• key — Uygulamanızın API anahtarı. Bu anahtar, kota yönetimi için 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ğinde isteğe bağlı parametreler:

• bounds: Coğrafi kodlamanın sonuçlarını daha belirgin şekilde ön plana çıkaracak olan görüntü alanının sınırlayıcı kutusu. Bu parametre yalnızca coğrafi kodlayıcının sonuçlarını etkiler, tamamen kısıtlamaz. (Daha fazla bilgi için aşağıdaki Görüntü Alanına Ağırlık Verme konusuna bakın.)
• language: Sonuçların döndürüleceği dil.
  • Desteklenen dillerin listesine bakın. Google genellikle desteklenen dilleri güncellediğinden bu liste tam kapsamlı olmayabilir.
  • language sağlanmazsa coğrafi kodlama uzmanı, Accept-Language başlığında belirtilen tercih edilen dili veya isteğin gönderildiği alanın yerel dilini kullanmaya çalışır.
  • Coğrafi kodlama uzmanı, hem kullanıcı hem de yerel kullanıcılar için okunabilir bir açık adres 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 göz önünde bulundurulur. 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 dilin, API'nin döndürmeyi seçtiği sonuç kümesi ve bunların döndürülme sırası üzerinde küçük bir etkisi vardır. Coğrafi kodlama açıcıları, kısaltmaları dile (ör. sokak türlerine ilişkin kısaltmalar) veya bir dilde geçerli olabilecek ancak başka bir dilde geçerli olmayan eş anlamlıları farklı şekilde yorumlar. Örneğin, utca ve tér, Macarcada sırasıyla sokak ve kare ile eş anlamlıdır.
• region - ccTLD ("Üst seviye alan adı") iki karakterli değer olarak belirtilen bölge kodu. Bu parametre, yalnızca coğrafi kodlayıcının sonuçlarını etkiler, tamamen kısıtlamaz. (Daha fazla bilgi için aşağıdaki Bölgeye Ağırlık Verme konusuna bakın.)
• components - Öğelerin dikey çizgiyle (|) ayrıldığı bir bileşen filtresi. İstek address içermiyorsa bileşen filtresi zorunludur. Bileşenler filtresindeki her öğe, bir component:value çiftinden oluşur ve coğrafi kodlayıcının sonuçlarını tamamen kısıtlar. Bileşen filtreleme hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

Yanıtlar

Coğrafi kodlama yanıtları, URL isteğinin yolunda output işaretiyle belirtilen biçimde döndürülür.

Bu örnekte Coğrafi Kodlama API'si, 1600 Amphitheatre Parkway, Mountain View, CA adresinde bulunan binanın yer kimliği olan "ChIJeRpOeF67j4AR9ydy_PIzPuM"" yer kimliğiyle ilgili bir sorgu için json yanıtı istemektedir.

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ıldığı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.

{
    "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"
}

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

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", herhangi bir hata olmadığını belirtir. Adres başarıyla ayrıştırıldı ve en az bir coğrafi kod döndürüldü.
• "ZERO_RESULTS", coğrafi kodlamanın başarılı olduğunu ancak hiçbir sonuç döndürmediğini belirtir. Bu durum, coğrafi kodlayıcının var olmayan address öğesi iletilmiş olması durumunda oluşabilir.
• OVER_DAILY_LIMIT, aşağıdakilerden herhangi birini belirtir:
  • API anahtarı eksik veya geçersiz.
  • Hesabınızda faturalandırma etkinleştirilmedi.
  • Kendi kendine uygulanan 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 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 veya latlng) eksik olduğunu gösterir.
• "UNKNOWN_ERROR", bir sunucu hatası nedeniyle isteğin işlenemediğini gösterir. Tekrar denemeniz durumunda istek başarılı olabilir.

Hata mesajları

coğrafi kodlamacı, OK dışında bir durum kodu döndürdüğünde Geocoding yanıt nesnesinde ek bir error_message alanı olabilir. Bu alan, belirtilen durum kodunun ardı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. 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> öğeden oluşur.)

Tipik bir sonuç aşağıdaki alanları içerir:

• types[] dizisi, döndürülen sonucun türü belirtir. Bu dizi, sonuçta döndürülen özellik türünü tanımlayan sıfır veya daha fazla etiket kümesi içerir. Örneğin, "Chicago"nun coğrafi kodu, "Chicago"nun bir şehir olduğunu ve aynı zamanda, bir siyasi tüzel kişi olduğunu belirten "politik" değerini döndürür.
• formatted_address, bu konumun kullanıcılar tarafından okunabilen adresini içeren bir dizedir.

  Bu adres genellikle posta adresiyle eşdeğerdir. Lisanslama kısıtlamaları nedeniyle, Birleşik Krallık gibi bazı ülkelerin gerçek posta adreslerinin dağıtımına izin vermediğini unutmayın.

  Biçimlendirilmiş adres, mantıksal olarak bir veya daha fazla adres bileşeninden oluşur. ya

  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şeni için kullanılan kısaltılmış bir metin adıdır. Örneğin, Alaska eyaletindeki bir adres bileşeninde "Alaska" için long_name ve 2 harfli posta kısaltması olan short_name "AK" bulunur.

  address_components[] dizisiyle ilgili aşağıdaki noktaları göz önünde bulundurun:

  • Adres bileşenleri dizisi, formatted_address öğesinden daha fazla bileşen içerebilir.
  • Dizi, formatted_address'da yer alan tüzel kişiler dışında, adres içeren tüm siyasi tüzel kişileri kapsamaz. Belirli bir adres içeren tüm siyasi varlıkları almak için, adresin enlem/boylamını isteğe parametre olarak ileterek tersine coğrafi kodlama kullanmanız gerekir.
  • Yanıt biçiminin istekler arasında aynı olacağı garanti edilmez. Özellikle address_components sayısı, talep edilen adrese göre değişir ve aynı adres için zamanla 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 yönetmek 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[], posta kodundaki tüm konumları belirten bir dizidir. Bu, yalnızca sonuç birden fazla şehir içeren bir posta kodu olduğunda mevcuttur.
• geometry aşağıdaki bilgileri içerir:
  • location, coğrafi kodlamalı enlem 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 bilgilerine göre doğru konum bilgilerine sahip olduğumuz kesin bir coğrafya kodu olduğunu gösterir.
    • "RANGE_INTERPOLATED", döndürülen sonucun iki tam nokta (kesişim gibi) arasındaki bir yaklaşık değeri (genellikle yol üzerinde) yansıttığını belirtir. Aralıklı sonuçlar, genellikle açık adres için çatı coğrafi kodlaması 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ı kutusunun southwest ve northeast köşesini tanımlayan iki enlem ve boylam değeri olarak belirtilir. Görüntü alanı genellikle bir sonucu kullanıcıya gösterirken bir sonucu çerçevelemek için kullanılır.
  • bounds (isteğe bağlı olarak iade edilir), 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 muhtemelen görüntü alanında döndürülmemesi gereken Farallon adalarını içerir.)
• plus_code (bkz. Açık Konum Kodu ve artı kodları), enlem ve boylam koordinatlarını temel alan, bir alanı temsil eden kodlanmış konum referansıdır: 1/8000 derecenin 1/8000. derecesi (ekvatorda yaklaşık 14 m x 14 m) veya daha küçük bir alanı temsil eder. Artı kodları, var olmayan yerlerde (binaların numaralandırılmadığı veya sokakların belirtilmediği) yer adresleri için yedek olarak kullanılabilir.

  Plus code, global kod ve birleşik kod olarak biçimlendirilir:

  • global_code, 4 karakterli bir alan kodu ve 6 karakter veya daha uzun yerel koddur (849VCWC8+R9).
  • compound_code, açık konuma (CWC8+R9, Mountain View, CA, ABD) sahip 6 veya daha uzun yerel koddur. Bu içeriği programatik olarak ayrıştırmayın.
  Genellikle hem global kod hem de birleşik kod döndürülür. Ancak sonuç, uzak bir konumdaysa (örneğin, bir okyanus veya çöl) yalnızca genel kodu döndürebilir.

• partial_match, coğrafi kodlama sahibinin 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 adres için ilk isteği inceleyebilirsiniz.

  Kısmi eşleşmeler çoğunlukla, talebi ilettiğiniz konum içinde bulunmayan açık adresler 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, Birleşik Krallık" hem Henry Street hem de Henrietta Street için kısmi bir eşleşme döndürür. Bir istek yanlış yazılan 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 Places API isteğindeki place_id kullanarak yerel bir işletmenin telefon numarası, çalışma saatleri, kullanıcı yorumları ve diğer bilgileri elde edebilirsiniz. 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. Adres türlerine örnek olarak açık adres, ülke veya siyasi varlık verilebilir. Ayrıca address_components[] içinde adresin her bölümünün türünü belirten bir types[] dizisi vardır. Sokak numarası veya ülke buna örnek olarak gösterilebilir. (Aşağıda türlerin tam listesi bulunmaktadır.) Adreslerin birden fazla türü olabilir. Türler 'tags' olarak kabul edilebilir. Örneğin, birçok şehir political ve locality türüyle etiketlenir.

Aşağıdaki türler, coğrafi kodlama uzmanı 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 adresi belirtir.
• route, adlandırılmış bir rotayı belirtir ("ABD 101"gibi).
• intersection genellikle iki ana yoldan oluşan ana kesişimi belirtir.
• political, siyasi bir varlığı belirtir. Genellikle bu, bir sivil yönetimin poligonunu gösterir.
• 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 tüzel kişiyi belirtir. ABD'de bu yönetim düzeyleri eyalet düzeyindedir. Bu yönetim düzeyleri tüm ülkeler tarafından görülemez. Çoğu durumda, admin_area_level_1 kısa adları, ISO 3166-2 alt bölümleriyle ve yaygın olarak kullanılan diğer listelerle yakından eşleşir. Ancak coğrafi kodlama sonuçlarımız çeşitli sinyalleri ve konum verilerini temel aldığından bu garanti edilmez.
• administrative_area_level_2, ülke düzeyinin altında ikinci taraf sivil kuruluşu belirtir. Amerika Birleşik Devletleri'nde bu idari bölgeler ilçedir. Bu yönetim düzeyleri tüm ülkeler tarafından görülemez.
• administrative_area_level_3, ülke düzeyinin altında üçüncü taraf sivil kuruluşu belirtir. Bu tür, küçük bir hukuki bölümü gösterir. Bu idari düzey her ülke tarafından gösterilmemektedir.
• administrative_area_level_4, ülke düzeyinin altında dördüncü taraf sivil kuruluşu belirtir. Bu tür, küçük bir hukuki bölümü gösterir. Bu idari düzey her ülke tarafından gösterilmemektedir.
• administrative_area_level_5, ülke düzeyinin beşinci sırada yer alan bir tüzel kişi olduğunu belirtir. Bu tür, küçük bir hukuki bölümü gösterir. Bu idari düzey her ülke tarafından gösterilmemektedir.
• administrative_area_level_6, ülke düzeyinin altında olan altıncı bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir hukuki bölümü gösterir. Bu idari düzey her ülke tarafından gösterilmemektedir.
• administrative_area_level_7, ülke düzeyinin altında yedinci düzey medeni tüzel kişiyi belirtir. Bu tür, küçük bir hukuki bölümü gösterir. Bu idari düzey her ülke tarafından gösterilmemektedir.
• colloquial_area, varlık için yaygın olarak kullanılan bir alternatif adı belirtir.
• locality, ilişkili şehir veya ilçe siyasi varlığını belirtir.
• sublocality, bir mahallenin altındaki birinci taraf sivil tüzel kişiyi belirtir. Bazı konumlar için şu ek türlerinden birini alabilir: sublocality_level_1 - sublocality_level_5. Her semt, bir tüzel kişidir. Daha büyük sayılar, daha küçük bir coğrafi alanı belirtir.
• neighborhood, adlandırılmış bir mahalleyi gösteriyor
• premise, adlandırılmış bir konumu belirtir. Bu konum genellikle bir bina veya ortak ada sahip bir bina koleksiyonudur
• subpremise, adlandırılmış bir konumun altındaki birinci taraf varlığını belirtir (genellikle aynı ada sahip bina koleksiyonundaki tek bir bina).
• plus_code, enlem ve boylamdan türetilen kodlanmış bir konum referansını belirtir. Artı kodları, var olmayan yerlerde (binaların numaralandırılmamış veya sokakların adlandırılmamış olduğu) açık adresler yerine kullanılabilir. Ayrıntılar için https://plus.codes sayfasına bakın.
• postal_code, ülke içindeki posta kodları için kullanılan posta kodunu belirtir.
• natural_feature belirgin bir doğal özelliği belirtir.
• airport, bir havaalanını gösteriyor.
• park, park adını belirtir.
• point_of_interest, adlandırılan bir önemli noktayı belirtir. Genellikle bu ÖY'ler, "Empire State Binası" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca sığmayan önemli yerel tüzel kişilerdir.

Boş türler listesi, belirli bir adres bileşeni için bilinen tür olmadığını gösterir (örneğin, Fransa'daki 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 genel olarak henüz kategorize edilmemiş bir yeri belirtir.
• landmark, gezinme işlemine yardımcı olmak için referans olarak kullanılan yakındaki bir yeri belirtir.
• point_of_interest, adlandırılan bir önemli noktayı belirtir.
• 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ılan locality ve sublocality gibi coğrafi alanların gruplandırıldığını gösterir.
• room, bina adresinin odasını belirtir.
• street_number tam sokak numarasını gösterir.
• bus_station, train_station ve transit_station otobüs, tren veya toplu taşıma durağının konumunu belirtir.

Görüntü alanını ağırlıklandırma

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 yaparsınız.

bounds parametresi, koordinatları ayırmak için bir ç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" için kullanılan coğrafi kodlama 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ğusundaki sınırlayıcı kutuyu tanımlayan bir 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 verilmiş sonuçlar döndürmesi için talimat verebilirsiniz. Bu parametre, bölge ön yargısı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 Birleşik Krallık ccTLD'si "quot;uk" (.co.uk), ISO 3166-1 kodu ise "quot;gb"

Coğrafi kodlama sonuçları, ana Google Haritalar uygulamasının resmi olarak kullanıma sunulduğu her alan için taraf olabilir. Taraflı tutmanın yalnızca belirli bir alan adına ait sonuçları tercih ettiğini unutmayın. Bu alan dışında daha alakalı sonuçlar varsa sonuçlar dahil edilebilir.

Örneğin, Geocoding API'nin varsayılan alan adı ABD olarak ayarlandığı için &Totdo'nun coğrafi kodlama bu sonucu döndürür. İstek:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=AIzaSyCaor12zcAJ3XgISkD8zsoaQ64PAlDgBrs

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 birlikte "Toledo" için coğrafi kodlama isteği, İspanya şehri döndürecektir.

İstek:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=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 sınırlı adres sonuçlarını döndürebilir. Kısıtlamayı components filtresini kullanarak belirtebilirsiniz. Bir filtre, dikey çizgiyle (|) ayrılmış component:value 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ı bulunur.

Filtrelenebilen components şunları içerir:

• postal_code, postal_code ve postal_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ına uyar 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, rotanın uzun veya kısa adıyla eşleşiyor.
• locality, locality ve sublocality türleriyle eşleşiyor.
• administrative_area, tüm administrative_area seviyeleriyle eşleşiyor.

Bileşen filtreleme hakkında notlar:

• İsteklerde bu bileşen filtrelerini 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 Google Haritalar ile tutarlıdır ve zaman zaman beklenmedik ZERO_RESULTS yanıtlar verir. Otomatik Yer Tamamlama özelliği bazı durumlarda daha iyi sonuçlar sağlayabilir. Daha fazla bilgi edinmek için bu SSS bölümüne bakın.
• Her adres bileşeni için address parametresini veya components filtresinde belirtin, ancak ikisini birden belirtmeyin. Her ikisinde de aynı değerlerin belirtilmesi ZERO_RESULTS ile sonuçlanabilir.

components=country:GB ile High High, Hastings&quot coğrafi haritasında ABD'nin Hastings-On-Hudson eyaleti yerine Hastings, İngiltere'de sonuç elde edilir.

İ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"
}

İspanya'nın Kanarya Adaları'ndaki Santa Cruz de Tenerife,

İ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 dışlayan 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 adresi coğrafi olarak kodlarken istek, binaların adlarını ve sayısı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"
}