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

İstek

Coğrafi Kodlama API'si isteği aşağıdaki biçimde olur:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

outputFormat aşağıdaki değerlerden biri olabilir:

• json (önerilen), JavaScript Object Notation (JSON) çıktısını belirtir veya
• xml, çıkışı XML olarak belirtir

API anahtarı kullanan istekler için HTTPS gerekir.

Bazı parametreler zorunlu, bazıları ise isteğe bağlıdır. URL'lerde olduğu gibi, parametreler "ve" (&) karakteri kullanılarak ayrılır.

Bu isteğin geri kalanında, her istek türü için farklı parametreler bulunduğundan, coğrafi kodlama ve ters coğrafi kodlama ayrı olarak açıklanmaktadır.

Coğrafi kodlama (enlem/boylam arama) parametreleri

Coğrafi kodlama isteğinde gerekli parametreler:

• address - Ticari kodlamayı yapmak istediğiniz açık adres veya artı kodu. Adresleri, ilgili ülkenin ulusal posta hizmeti tarafından kullanılan biçime göre belirtin. İşletme adları ve daire, daire veya kat numaraları gibi ek adres öğelerinden kaçınılmalıdır. Açık adres öğeleri, boşlukla sınırlandırılmalıdır (burada URL çıkışlı olarak %20 ile gösterilir):

  address=24%20Sussex%20Drive%20Ottawa%20ON

  Plus code'ları burada gösterildiği gibi biçimlendirin (artı işaretleri URL'den çıkış karakterli %2B, boşluklar URL'ye çıkış karakterli %20 şeklindedir):
  • Global kod, 4 karakterden oluşan bir alan kodu ve 6 veya daha uzun yerel koddur (849VCWC8+R9 849VCWC8%2BR9).
  • Bileşik kod, açık bir konuma sahip 6 karakter veya daha uzun bir yerel koddur (CWC8+R9 Mountain View, CA, ABD CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --OR--
  components — Öğelerin bir dikey çizgiyle (|) ayrıldığı bir bileşen filtresi. Bileşenler, address sağlanırsa isteğe bağlı bir parametre olarak da kabul edilir. Bileşenler filtresindeki her öğe, bir component:value çiftinden oluşur ve coğrafi kodlayıcının sonuçlarını tamamen kısıtlar. Aşağıda bileşen filtreleme hakkında daha fazla bilgi bulabilirsiniz.
• key: Uygulamanızın API anahtarı. Bu anahtar, kota yönetimi için uygulamanızı tanımlar. Anahtar alma hakkında bilgi edinin.

Daha fazla bilgi için lütfen SSS bölümünü inceleyin.

Coğrafi kodlama isteğinde isteğe bağlı parametreler:

• bounds: Coğrafi kodlamanın sonuçları daha belirgin bir şekilde sapmasına neden olacak şekilde görüntü alanının sınırlayıcı kutusu. Bu parametre yalnızca coğrafi kodlamaya ait sonuçları kısıtlamaz, tamamen etkilemez. (Daha fazla bilgi için aşağıdaki Görüş Alanına Ağırlık Verme bölümünü inceleyin.)
• language: Sonuçların döndürüleceği dil.
  • Desteklenen dillerin listesini inceleyin. Google, genellikle desteklenen dilleri güncellediği için bu liste tam kapsamlı olmayabilir.
  • language sağlanmazsa coğrafi kodlama, Accept-Language başlığında belirtilen tercih edilen dili veya isteğin gönderildiği alanın yerel dilini kullanmaya çalışır.
  • Coğrafi kodlayıcı, hem kullanıcı hem de yerel halkın okuyabileceği bir sokak adresi sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için yerel dilde açık adresleri döndürür. Gerekirse kullanıcının okuyabileceği bir komut dosyasına dönüştürülür ve tercih edilen dil dikkate alınır. Diğer tüm adresler, tercih edilen dilde döndürülür. Adres bileşenlerinin tümü, ilk bileşenden seçilen aynı dilde döndürülür.
  • Tercih edilen dilde bir ad yoksa coğrafi kodlama en yakın eşleşmeyi kullanır.
  • Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç kümesi ve döndürülme sırası üzerinde küçük bir etkiye sahiptir. Coğrafi kodlama, kısaltmaları dile bağlı olarak farklı şekilde yorumlar. Örneğin, sokak türleri için kısaltmalar veya bir dilde geçerli olsa bile başka bir dilde geçerli olmayan eş anlamlılar. Örneğin utca ve tér kelimeleri, Macarcada sırasıyla sokak ve kare ile eş anlamlıdır.
• region: ccTLD ("üst düzey alan") iki karakterli değer olarak belirtilen bölge kodudur. Bu parametre yalnızca coğrafi kodlamaya ait sonuçları etkilemez, tam olarak kısıtlamaz. (Daha fazla bilgi için aşağıdaki Bölgeye Ağırlık Verme bölümünü inceleyin.)
• components: Öğelerin dikey çizgiyle (|) ayrıldığı bir bileşen filtresi. İstek bir 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. Aşağıda bileşen filtreleme hakkında daha fazla bilgi bulabilirsiniz.

Yanıtlar

Coğrafi kodlama yanıtları, URL isteğindeki output işaretiyle belirtilen biçimde veya varsayılan olarak JSON biçiminde döndürülür.

Bu örnekte Coğrafi Kodlama API'si, "ChIJeRpOeF67j4AR9ydy_PIzPuM" yer kimliğindeki bir sorgu için json yanıtı istemektedir. Bu yerin kimliği 1600 Amphitheatre Parkway, Mountain View, CA adresindeki binadır.

Bu istek, JSON output işaretinin kullanıldığını gösterir:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Bu istek, XML output işaretinin kullanımını gösterir:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Örnek JSON ve XML yanıtlarını görmek için aşağıdaki sekmeleri seçin.

{
    "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" hata olmadığını, adresin başarıyla ayrıştırıldığını ve en az bir coğrafi kodlamanın döndürüldüğünü gösterir.
• "ZERO_RESULTS", coğrafi kodlamanın başarılı olduğunu ancak hiçbir sonuç döndürmediğini belirtir. Bu durum, coğrafi kodlamanın mevcut olmayan bir address'dan geçirilmesi durumunda gerçekleşebilir.
• OVER_DAILY_LIMIT aşağıdakilerden herhangi birini belirtir:
  • API anahtarı eksik veya geçersiz.
  • Hesabınızda faturalandırma etkinleştirilmedi.
  • Kendi kendini sınırlayan bir kullanım sınırı aşıldı.
  • Sağlanan ödeme yöntemi artık geçerli değil (örneğin, kredi kartının geçerlilik süresi dolmuş).

  Bu sorunu nasıl düzelteceğinizi öğrenmek için Haritalar hakkında SSS bölümüne bakın.

• "OVER_QUERY_LIMIT", kotanızı aştığınızı belirtir.
• "REQUEST_DENIED", isteğinizin reddedildiğini belirtir.
• "INVALID_REQUEST" genellikle sorgunun (address, components veya latlng) eksik olduğunu gösterir.
• "UNKNOWN_ERROR", isteğin sunucu hatası nedeniyle işlenemediğini gösterir. Tekrar denediğinizde istek başarılı olabilir.

Hata mesajları

Kodlayıcı, OK dışında bir durum kodu döndürdüğünde Geocode yanıt nesnesinin içinde ek bir error_message alanı olabilir. Bu alan, belirtilen durum kodunun arkasındaki nedenler hakkında daha ayrıntılı bilgi içerir.

Sonuçlar

Kodlayıcı, sonuçları döndürdüğünde (JSON) results dizisine yerleştirir. Kodlayıcı sonuç döndürmese de (ör. adres yoksa) boş results dizisi döndürür. (XML yanıtları sıfır veya daha fazla <result> öğeden oluşur.)

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

• types[] dizisi, döndürülen sonucun türünü belirtir. Bu dizi, sonuçta döndürülen özelliğin türünü tanımlayan sıfır veya daha fazla etiket kümesi içerir. Örneğin, "Chicago"nun coğrafi kodlama kodu, "Chicago"nun bir şehir olduğunu belirten "locality", aynı zamanda da siyasi bir tüzel kişi olduğunu belirten "politik" ifadesini döndürür. Söz konusu adres bileşeni için bilinen bir tür yoksa bileşenlerde boş türler bulunabilir. API, gerektiğinde yeni tür değerleri ekleyebilir. Daha fazla bilgi edinmek için Adres türleri ve adres bileşenleri başlıklı makaleye göz atın.
• formatted_address, bu konumun kullanıcılar tarafından okunabilir adresini içeren bir dizedir.

  Bu adres genellikle posta adresiyle eşdeğerdir. Birleşik Krallık gibi bazı ülkelerde lisanslama kısıtlamaları nedeniyle gerçek posta adreslerinin dağıtımına izin verilmediğini hatırlatmak isteriz.

  Biçimlendirilmiş adres, mantıksal olarak bir veya daha fazla adres bileşeninden oluşur. Örneğin, "111 8th Avenue, New York, NY" adresi şu bileşenlerden oluşur: "111" (sokak numarası), "8th Avenue" (rota), "New York" (şehir) ve "NY" (ABD eyaleti).

  Biçimlendirilmiş adresi programatik olarak ayrıştırmayın. Bunun yerine, API yanıtının biçimlendirilmiş adres alanına ek olarak içerdiği bağımsız adres bileşenlerini kullanmanız gerekir.

• address_components[], bu adres için geçerli olan ayrı bileşenleri içeren bir dizidir.

  Her adres bileşeni genellikle aşağıdaki alanları içerir:

  • types[], adres bileşeninin türünü belirten bir dizidir. Desteklenen türlerin listesine bakın.
  • long_name, Geocoder tarafından döndürülen adres bileşeninin tam metin açıklaması veya adıdır.
  • short_name, adres bileşeninin (varsa) kısaltılmış metin adıdır. Örneğin, Alaska eyaletindeki bir adres bileşeninde, 2 harfli posta kısaltması kullanılarak long_name "Alaska" ve short_name değeri "AK" bulunabilir.

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

  • Adres bileşenleri dizisi, formatted_address değerinden daha fazla bileşen içerebilir.
  • Dizide, formatted_address içinde bulunanlar dışında adres içeren tüm siyasi kuruluşlar bulunmayabilir. Belirli bir adres içeren tüm siyasi varlıkları almak için, isteğin enlem veya boylamını parametre olarak ileterek tersine coğrafi kodlama kullanmanız gerekir.
  • İsteğin biçiminin istekler arasında aynı kalacağı garanti edilmez. Özellikle address_components sayısı, talep edilen adrese göre değişir ve aynı adres için zaman içinde değişebilir. Bir bileşen, dizideki konumu değiştirebilir. Bileşenin türü değişebilir. Daha sonraki bir yanıtta belirli bir bileşen eksik olabilir.

  Bileşen dizisini işlemek için yanıtı ayrıştırıp ifadeler aracılığıyla uygun değerleri seçmeniz gerekir. Yanıtı ayrıştırma kılavuzuna bakın.

• postcode_localities[], posta kodundaki tüm şehirleri belirten bir dizidir. Bu yalnızca, sonuç birden fazla konum içeren bir posta kodu olduğunda geçerlidir.
• geometry aşağıdaki bilgileri içerir:
  • location, coğrafi kodlamalı enlemi ve boylam değerini içerir. Normal adres aramalarında bu alan genellikle en önemli olandır.

  • location_type, belirtilen konumla ilgili ek verileri depolar. Şu anda aşağıdaki değerler desteklenmektedir:

    • "ROOFTOP", döndürülen sonucun, açık adres doğruluğuna kadar doğru konum bilgilerine sahip olduğumuz kesin bir coğrafi kodlama olduğunu belirtir.
    • "RANGE_INTERPOLATED", döndürülen sonucun iki kesin nokta (ör. kavşaklar) arasındaki tahmini bir değeri (genellikle yol üzerinde) gösterdiğini belirtir. Etkileşimli sonuçlar genellikle bir açık adres için çatı coğrafi kodlamaları kullanılamadığında döndürülür.
    • "GEOMETRIC_CENTER", döndürülen sonucun bir çoklu çizgi (ör. sokak) veya poligon (bölge) gibi bir sonucun geometrik merkezi olduğunu gösterir.
    • "APPROXIMATE", döndürülen sonucun yaklaşık olduğunu gösterir.
  • viewport, döndürülen sonucu görüntülemek için önerilen görüntü alanını içerir. Görüntü alanı sınırlayıcı kutusunun southwest ve northeast köşesini tanımlayan iki enlem ve boylam değeri olarak belirtilir. Görüntü alanı, genellikle sonucu kullanıcıya gösterirken çerçevelemek için kullanılır.
  • bounds (isteğe bağlı olarak döndürülür) döndürülen sonucu tam olarak içerebilen sınırlayıcı kutuyu depolar. Bu sınırların, önerilen görüntü alanıyla eşleşmeyebileceğini unutmayın. (Örneğin, San Francisco, teknik olarak şehrin bir parçası olan ancak büyük olasılıkla görüntü alanında döndürülmemesi gereken Farallon adalarını içerir.)
• plus_code (Açık Konum Kodu ve artı kodları), enlem ve boylam koordinatlarından türetilen ve bir alanı temsil eden kodlanmış konum referansıdır: dereceyi 1/8000 ile derecenin 1/8000'i oranında (ekvatorda yaklaşık 14m x 14m) veya daha küçük bir alanı ifade eder. Adres kodları, adreslerin bulunmadığı yerlerde (binaların numaralandırılmadığı veya sokakların belirtilmediği) açık adresler için kullanılabilir. API her zaman artı kodlarını döndürmez.

  Hizmet artı kodu döndürdüğünde global kod ve birleşik kod olarak biçimlendirilir:

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

• partial_match, coğrafi kodlamanın orijinal istek için tam eşleşme döndürmediğini, ancak istenen adresin bir kısmıyla eşleşebildiğini belirtir. Yazım yanlışları ve/veya eksik adresle ilgili orijinal isteği inceleyebilirsiniz.

  Kısmi eşleşmeler çoğunlukla istekte ilettiğiniz bölgede bulunmayan sokak adresleri için gerçekleşir. Bir istek aynı yerleşimdeki iki veya daha fazla konumla eşleştiğinde de kısmi eşleşmeler döndürülebilir. Örneğin, "Hillpar St, Bristol, UK" hem Henry Street hem de Henrietta Street için kısmi bir eşleşme döndürecektir. Bir istekte yanlış yazılmış adres bileşeni varsa, coğrafi kodlama hizmetinin alternatif bir adres önerebileceğini unutmayın. Bu şekilde tetiklenen öneriler de kısmi eşleşme olarak işaretlenir.

• place_id, diğer Google API'leriyle kullanılabilecek benzersiz bir tanımlayıcıdır. Örneğin, bir Rehber API isteğindeki place_id özelliğini kullanarak yerel bir işletmenin telefon numarası, çalışma saatleri, kullanıcı yorumları gibi ayrıntılarını öğrenebilirsiniz. Yer kimliğine genel bakış bölümünü inceleyin.

Adres türleri ve adres bileşeni türleri

Sonuçtaki types[] dizisi adres türünü belirtir. Açık adres, ülke veya siyasi kuruluş gibi adres türlerine örnek gösterilebilir. Ayrıca address_components[] içerisinde, adresin her bir bölümünün türünü belirten bir types[] dizisi vardır. Buna örnek olarak sokak numarası veya ülke gösterilebilir. (Türlerin tam listesini aşağıda bulabilirsiniz.) Adreslerin birden fazla türü olabilir. Türler "etiket" olarak kabul edilebilir. Örneğin, birçok şehir political ve locality türüyle etiketlenir.

Aşağıdaki türler, coğrafi kodlama tarafından hem adres türü hem de adres bileşeni türü dizilerinde desteklenir ve döndürülür:

• street_address açık bir adres belirtiyor.
• route, adlandırılmış bir rotayı belirtir (ör. "US 101").
• intersection genellikle iki ana yoldan oluşan büyük bir kesişimi gösterir.
• political, siyasi bir varlığı belirtir. Genellikle bu tür, belirli bir idari yönetimin poligonunu belirtir.
• country, ulusal siyasi varlığı belirtir ve genellikle Geocoder tarafından döndürülen en yüksek sipariş türüdür.
• administrative_area_level_1, ülke düzeyinin altındaki birinci taraf sivil varlığı gösterir. ABD'de bu idari düzeyler eyalettir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir. Çoğu durumda, admin_area_level_1 kısa adları ISO 3166-2 alt bölümleri ve yaygın şekilde dolaşım sağlayan diğer listelerle yakından eşleşir. Ancak, coğrafi kodlama sonuçlarımız çeşitli sinyallere ve konum verilerine dayalı olduğundan bu garanti edilmez.
• administrative_area_level_2, ülke düzeyinin altındaki ikinci düzey bir tüzel kişiyi gösterir. Amerika Birleşik Devletleri'nde bu idari bölgeler ilçelerdir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
• administrative_area_level_3, ülke düzeyinin altındaki üçüncü taraf sivil tüzel kişiliğini gösterir. Bu tür, küçük bir sivil bölümü gösterir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
• administrative_area_level_4, ülke düzeyinin altındaki dördüncü taraf bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil bölümü gösterir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
• administrative_area_level_5, ülke düzeyinin altındaki beşinci sırada yer alan bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil bölümü gösterir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
• administrative_area_level_6, ülke düzeyinin altındaki bir altıncı sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil bölümü gösterir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
• administrative_area_level_7, ülke düzeyinin altındaki yedinci bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil bölümü gösterir. Bu yönetim seviyeleri her ülke tarafından sergilenmemektedir.
• colloquial_area, varlık için yaygın olarak kullanılan bir alternatif ad belirtir.
• locality, birleşik bir şehir veya ilçe siyasi varlığını belirtir.
• sublocality, bir yerin altında birinci taraf sivil tüzel kişiliği gösterir. Bazı konumlar için ek türlerden biri alınabilir: sublocality_level_1 - sublocality_level_5. Her alt konum düzeyi bir tüzel kişidir. Daha büyük sayılar daha küçük bir coğrafi alanı belirtir.
• neighborhood, adlandırılmış bir mahalleyi gösteriyor
• premise, genellikle ortak bir ada sahip olan bina veya bina koleksiyonu olmak üzere adlandırılmış bir konumu belirtir
• subpremise, adlandırılmış bir konumun altındaki birinci taraf varlığını (genellikle ortak bir ada sahip bina koleksiyonundaki tek bir bina) belirtir
• plus_code, enlem ve boylamdan türetilen kodlanmış bir konum referansını belirtir. Artı kodları, mevcut olmayan (binaların numaralandırılmadığı veya sokakların adlandırılmamış olduğu) açık adreslerin yerine kullanılabilir. Ayrıntılar için https://plus.codes sayfasına göz atın.
• postal_code, ülke içindeki posta posta adreslerinde kullanılan posta kodunu belirtir.
• natural_feature belirgin bir doğal özellik gösterir.
• airport bir havaalanını gösteriyor.
• park, adlandırılmış bir parkı belirtir.
• point_of_interest, önemli bir önemli nokta olduğunu gösterir. Bu "ÖY'ler" genellikle "Empire State Binası" veya "Eyfel Kulesi" gibi diğer kategorilere kolayca sığmayan önemli yerel varlıklardır.

Boş tür listesi, belirli adres bileşeni için bilinen tür olmadığını gösterir (örneğin, Fransa'da Lieu-dit).

Yukarıdakilere ek olarak, adres bileşenleri burada listelenen türleri içerebilir. Bu liste tam kapsamlı değildir ve değişebilir.

• floor, bina adresinin tabanını belirtir.
• establishment genellikle henüz sınıflandırılmamış bir yeri belirtir.
• landmark, gezinmeye yardımcı olmak için referans olarak kullanılan yakındaki bir yeri belirtir.
• point_of_interest, önemli bir önemli nokta olduğunu gösterir.
• parking, bir park yerini veya otopark yapısını belirtir.
• post_box belirli bir posta kutusunu belirtir.
• postal_town, bazı ülkelerde posta adresleri için kullanılan locality ve sublocality gibi coğrafi bölgelerin grubunu gösterir.
• room, bina adresinin bulunduğu odayı belirtir.
• street_number tam sokak numarasını belirtir.
• bus_station, train_station ve transit_station; otobüs, tren veya toplu taşıma durağının konumunu belirtir.

Görüntü alanına ağırlık verme

Coğrafi kodlama isteğinde, Coğrafi Kodlama hizmetine belirli bir görüntü alanındaki (sınırlayıcı kutu olarak ifade edilir) sonuçları tercih etmesini söyleyebilirsiniz. Bunu, bounds parametresini ayarlayarak istek URL'sinde yapabilirsiniz.

bounds parametresi, koordinatları ayırmak için bir dik çizgi (|) karakteri kullanarak bu sınırlayıcı kutunun güneybatı ve kuzeydoğu köşelerinin enlem/boylam koordinatlarını tanımlar.

Örneğin, "Washington"un coğrafi kodlama türü genellikle ABD'nin Washington eyaletini döndürür:

İstek:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY

Yanıt:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            },
            "location" : {
               "lat" : 47.7510741,
               "lng" : -120.7401385
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            }
         },
         "place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

Ancak, ABD'nin kuzeydoğusunda sınırlayıcı bir kutu tanımlayan bounds bağımsız değişkeni eklemek, bu coğrafi kodlamanın Washington, D.C. şehrini döndürmesine neden olur:

İstek:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

Yanıt:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Bölgeye ağırlık verme

Coğrafi Kodlama isteğinde, region parametresini kullanarak Coğrafi Kodlama hizmetine belirli bir bölgeye ağırlık veren sonuçları döndürmesi için talimat verebilirsiniz. Bu parametre, bölge sapmasını belirten bir ccTLD (ülke kodu üst düzey alan) bağımsız değişkeni alır. Çoğu ccTLD kodu, bazı önemli istisnalar dışında ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık ccTLD'si "uk" (.co.uk) iken ISO 3166-1 kodu "gb"dır (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallığı" için).

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

Örneğin, Geocode API'nin varsayılan alanı ABD olarak ayarlandığından "Toledo" için coğrafi kodlama bu sonucu döndürür. İstek:

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

Yanıt:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

"Toledo" için region=es (İspanya) ile ilgili bir coğrafi kodlama isteği, İspanya şehri döndürecektir.

İstek:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&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, Geokodlama API'si belirli bir alanla sınırlandırılmış adres sonuçlarını döndürebilir. Kısıtlamayı components filtresini kullanarak belirtebilirsiniz. Filtre, dikey çizgiyle (|) ayrılmış component:value çifti listesinden oluşur. Filtre değerleri, diğer coğrafi kodlama istekleriyle aynı yazım düzeltme ve kısmi eşleme yöntemlerini destekler. Kodlayıcı, bir bileşen filtresi için kısmi eşleşme bulursa yanıtta bir partial_match alanı yer alır.

Filtrelenebilir components şunlardır:

• postal_code, postal_code 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ını uygular ve filtreleme, ülkenin ilgili ISO kodunu kullanırken en iyi sonucu verir.

Sonuçları etkilemek için aşağıdaki components kullanılabilir ancak zorunlu kılınmaz:

• route bir rotanın uzun veya kısa adıyla eşleşiyor.
• locality, locality ve sublocality türleriyle eşleşiyor.
• administrative_area, tüm administrative_area seviyeleriyle eşleşiyor.

Bileşen filtreleme hakkında notlar:

• Bu bileşen filtrelerini isteklerde tekrarlamayın. Aksi takdirde API Invalid_request değerini döndürür: country, postal_code, route
• İstek tekrarlanan bileşen filtreleri içeriyorsa API, bu filtreleri VEYA olarak değil, VE olarak değerlendirir.
• Sonuçlar, zaman zaman beklenmeyen ZERO_RESULTS yanıtları veren Google Haritalar ile tutarlıdır. Yer Otomatik Tamamlama özelliğini kullanmak, bazı durumlarda daha iyi sonuçlar sağlayabilir. Daha fazla bilgi edinmek için bu SSS sayfasına göz atın.
• Her adres bileşenini hem address parametresinde hem de components filtresinde belirtin, ancak ikisinde birden kullanmayın. Her ikisinde de aynı değerlerin belirtilmesi ZERO_RESULTS ile sonuçlanabilir.

"High St, Hastings" için kullanılan components=country:GB kodu, ABD'deki Hastings-On-Hudson yerine Hastings, İngiltere'de sonuç döndürüyor.

İstek:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

Yanıt:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

"Santa Cruz" (components=country:ES ile birlikte) için coğrafi kodlama isteği, İspanya'nın Kanarya Adaları'ndaki Santa Cruz de Tenerife'yi döndürüyor.

İstek:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

Yanıt:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Bileşen filtreleme, yalnızca birbirlerini hariç tutan filtreler sağlarsanız ZERO_RESULTS yanıtı döndürür.

İstek:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Yanıt:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

components filtresini kullanarak, adres parametresi olmadan geçerli sorgular oluşturabilirsiniz. (Tam adresi coğrafi olarak kodlarken istek, binaların adlarını ve numaralarını içeriyorsa address parametresi gerekir.)

İstek:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

Yanıt:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annankatu",
               "short_name" : "Annankatu",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "HKI",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00101",
               "short_name" : "00101",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annankatu, 00101 Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}