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

İ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 (önerilen), JavaScript Nesne Gösterimi (JSON) biçiminde çıkışı gösterir; veya
  • xml, XML biçimindeki çıkışı belirtir.

HTTPS gereklidir.

Bazı parametreler gereklidir, bazıları ise isteğe bağlıdır. URL'lerde standart olarak 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 araması) 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 edinme hakkında bilgi edinin.
  • Bir istekte address veya components ya da ikisini birden belirtmeniz gerekir:

    • address: Coğrafi kodlamak istediğiniz posta adresi veya plus kodu. Adresleri, ilgili ülkenin ulusal posta hizmeti tarafından kullanılan biçime uygun şekilde belirtin. İşletme adları ve daire, apartman veya kat numaraları gibi ek adres öğelerinden kaçınılmalıdır. Açık adres öğeleri boşluklarla ayrılmalıdır (burada %20 olarak URL'den kaçan olarak gösterilmiştir):
      address=24%20Sussex%20Drive%20Ottawa%20ON
      Artı kodlarını burada gösterildiği gibi biçimlendirin (artı işaretleri URL'de %2B olarak, boşluklar ise %20 olarak kodlanır):
      • Küresel kod, 4 karakterli bir alan kodu ve 6 karakter veya daha uzun bir yerel koddur (849VCWC8+R9, 849VCWC8%2BR9'dir).
      • Karma 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'dir).
    • components: Bir boru (|) ile ayrılmış öğeleri içeren bir bileşen filtresi. address sağlanırsa bileşen filtresi isteğe bağlı parametre olarak da kabul edilir. Bileşenler filtresindeki her öğe bir component:value çiftinden oluşur ve coğrafi kodlayıcıdan gelen sonuçları tamamen kısıtlar. Bileşen filtreleme hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

Daha fazla bilgi için SSS sayfasına bakın.

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

  • bounds: Coğrafi kodlama sonuçlarını daha belirgin hale getirmek için kullanılacak görüntü alanının sınır kutusu. Bu parametre, coğrafi kodlayıcıdan gelen sonuçları yalnızca etkiler, tamamen kısıtlamaz. (Daha fazla bilgi için aşağıdaki Görüntüleme 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 tam olmayabilir.
    • language sağlanmazsa coğrafi kodlayıcı, 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 tarafından okunabilen bir açık adres sağlamak için elinden geleni yapar. Bu amaca ulaşmak için, tercih edilen dile göre sokak adreslerini yerel dilde, gerekirse kullanıcı tarafından okunabilen bir yazım sistemine dönüştürülmüş şekilde döndü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 aynı dilde döndürülür.
    • Bir ad tercih edilen dilde mevcut değilse coğrafi kodlayıcı en yakın eşlemeyi kullanır.
    • Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç grubu ve bu sonuçları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ılar. Örneğin, Macarcada utca ve tér sırasıyla cadde ve meydanın eş anlamlısıdır.
  • region: ccTLD ("üst düzey alan") iki karakterli değer olarak belirtilen bölge kodu. Bu parametre, coğrafi kodlayıcıdan elde edilen sonuçları yalnızca etkiler, tamamen kısıtlamaz. (Daha fazla bilgi için aşağıdaki Bölge Eğilimi bölümüne bakın.) Bu parametre, geçerli yasaya göre sonuçları da etkileyebilir.
  • components: Bir boru (|) ile ayrılmış öğeleri içeren 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ıdan gelen sonuçları tamamen kısıtlar. Bileşen filtreleme hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.
  • extra_computations: Yanıtta aşağıdaki ek özellikleri belirtmek için bu parametreyi kullanın: Aynı API isteği için bu özelliklerin birden fazlasını etkinleştirmek isterseniz her bir özellik için isteğe extra_computations parametresini ekleyin. Örneğin:
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Yanıtlar

Coğrafi kodlama yanıtları, URL isteğinde 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 "1600 Amphitheatre Parkway, Mountain View, CA" adresiyle ilgili bir sorgu için json yanıtı ister.

Bu istek, JSON output işaretinin kullanılmasını göstermektedir:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

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

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

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

JSON

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

JSON yanıtının iki kök öğe içerdiğini unutmayın:

  • "status", istekle ilgili meta verileri içerir. Aşağıdaki durum kodlarına bakın.
  • "results", coğrafi kodlanmış adres bilgileri ve geometri bilgileri dizisi içerir.

Adres aramaları için genellikle "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ına bakın.
  • Her biri tek bir coğrafi kodlanmış adres bilgisi ve geometri bilgisi grubu içeren sıfır veya daha fazla <result> öğesi.

XML yanıtı, JSON yanıtından çok daha uzundur. Bu nedenle, hizmetiniz bir nedenle xml gerektirmediği sürece tercih edilen çıkış işareti olarak json kullanmanızı öneririz. Ayrıca, XML ağaçları işlenirken doğru düğümlere ve öğelere referans vermeniz için biraz dikkatli olmanız gerekir. Çıkış işleme için önerilen bazı tasarım kalıpları için XPath ile XML'i ayrıştırma başlıklı makaleyi inceleyin.

  • XML sonuçları bir kök <GeocodeResponse> öğesine sarmalanır.
  • JSON, birden fazla öğe içeren girişleri çoğul dizilerle (types) gösterirken XML bunları birden fazla tekil öğeyle (<type>) gösterir.
  • Boş öğeler JSON'da boş dizilerle, XML'de ise bu tür bir öğenin yokluğuyla belirtilir. Sonuç üretmeyen bir yanıt, JSON'da boş bir results dizisi döndürür ancak XML'de <result> öğesi döndürmez.

Durum kodları

Coğrafi kodlama yanıt nesnesinin "status" alanı, isteğin durumunu içerir ve coğrafi kodlamanın neden çalışmadığını belirlemenize 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 kod döndürüldüğünü gösterir.
  • "ZERO_RESULTS", coğrafi kodlamanın başarılı olduğunu ancak sonuç döndürmediğini gösterir. Bu durum, coğrafi kodlayıcıya var olmayan bir address iletilmesi durumunda ortaya çıkabilir.
  • OVER_DAILY_LIMIT aşağıdakilerden herhangi birini gösterir:
    • API anahtarı eksik veya geçersiz.
    • Hesabınızda faturalandırma etkinleştirilmedi.
    • Kendi belirlediğiniz kullanım sınırı aşıldı.
    • Sağlanan ödeme yöntemi artık geçerli değil (ör. kredi kartının süresi dolmuş).

    Bu sorunu nasıl düzelteceğinizi öğrenmek için Haritalar ile ilgili SSS sayfasına 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, components veya latlng) eksik olduğunu gösterir.
  • "UNKNOWN_ERROR", isteğinin 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, belirtilen durum kodunun nedenleri hakkında daha ayrıntılı bilgi içerir.

Sonuçlar

Coğrafi kodlayıcı, sonuçları (JSON) results dizisine yerleştirir. Coğrafi kodlayıcı hiçbir sonuç döndürmezse 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ü belirtir. Bu dizi, sonuçta döndürülen özellik türünü tanımlayan sıfır veya daha fazla etiket içerir. Örneğin, "Chicago" için bir coğrafi kod, "Chicago"nun bir şehir olduğunu belirten "locality" değerini ve siyasi bir varlık olduğunu belirten "political" değerini döndürür. İlgili adres bileşeni için bilinen tür olmadığında bileşenlerin 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şenleri başlıklı makaleyi inceleyin.
  • formatted_address, bu konumun kullanıcıların okuyabileceği adresini içeren bir dizedir.

    Bu adres genellikle posta adresiyle aynıdır. Birleşik Krallık gibi bazı ülkelerde, lisanslama kısıtlamaları nedeniyle gerçek posta adreslerinin dağıtılmasına izin verilmediğini unutmayın.

    Biçimlendirilmiş adres mantıksal olarak bir veya daha fazla adres bileşeninden oluşur. Örneğin, "111 8. Cadde, New York, NY" adresi şu bileşenlerden oluşur: "111" (bina numarası), "8. Cadde" (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, Coğrafi Kodlayıcı tarafından döndürülen adres bileşeninin tam metin açıklaması veya adıdır.
    • short_name, varsa adres bileşeninin kısaltılmış metinsel adıdır. Örneğin, Alaska eyaletinin bir adres bileşeninde long_name olarak "Alaska" ve short_name olarak 2 harfli posta kısaltması olan "AK" bulunabilir.

    address_components[] dizisiyle ilgili aşağıdaki noktalara dikkat edin:

    • Adres bileşenleri dizisi, formatted_address'ten daha fazla bileşen içerebilir.
    • Dizi, formatted_address'e dahil olanlar 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 ters coğrafi kodlamayı kullanmalı ve isteğe parametre olarak adresin enlem/boylamını göndermelisiniz.
    • Yanıtın biçiminin istekler arasında aynı kalacağı garanti edilmez. Özellikle address_components sayısı, istenen adrese göre değişir ve aynı adres için zaman içinde değişebilir. Bir bileşen, dizindeki konumunu değiştirebilir. Bileşenin türü değişebilir. Belirli bir bileşen, daha 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. Bir yanıtı ayrıştırma kılavuzuna bakın.

  • postcode_localities[], bir posta kodunda yer alan en fazla 100 yerelliği belirten bir dizidir. Bu, yalnızca sonuç birden fazla yerleşim yeri içeren bir posta kodu olduğunda gösterilir.
  • geometry aşağıdaki bilgileri içerir:
    • location, coğrafi kodlanmış enlem ve boylam değerini içerir. Normal adres aramalarında bu alan genellikle en önemlisidir.
    • location_type, belirtilen konumla ilgili ek verileri depolar. Şu anda aşağıdaki değerler desteklenmektedir:

      • "ROOFTOP", döndürülen sonucun tam bir coğrafi kod olduğunu ve bu kod için sokak adresi doğruluğuna kadar doğru konum bilgilerine sahip olduğumuzu gösterir.
      • "RANGE_INTERPOLATED", döndürülen sonucun iki kesin nokta (ör. kavşaklar) arasında interpolasyon uygulanmış bir yaklaşık değeri (genellikle bir yolda) yansıttığını gösterir. Düzenlenmiş sonuçlar genellikle bir sokak adresi için çatı jeokodları kullanılamadığında döndürülür.
      • "GEOMETRIC_CENTER", döndürülen sonucun bir poli ç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. Bu alan, görüntü alanı sınır kutusundaki southwest ve northeast köşelerini tanımlayan iki enlem, boylam değeri olarak belirtilir. Genellikle bir sonucu kullanıcıya gösterirken çerçevelemek için görüntü alanı kullanılır.
    • bounds (isteğe bağlı olarak döndürülür), döndürülen sonucu tamamen içerebilen sınır kutusuna sahiptir. Bu sınırların önerilen görüntü alanı ile eşleşmeyebileceğini unutmayın. (Örneğin, San Francisco teknik olarak şehrin bir parçası olan ancak görüntü alanında döndürülmemesi muhtemel Farallon adalarını içerir.)
  • plus_code (Açık Konum Kodu ve artı kodları bölümüne bakın), enlem ve boylam koordinatlarından türetilen, 1 derecenin 8.000'de 1'i ile 1 derecenin 8.000'de 1'i (ekvatorda yaklaşık 14 m x 14 m) veya daha küçük bir alanı temsil eden kodlanmış bir konum referansı. Plus code'lar, adreslerin bulunmadığı yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı yerlerde) açık adreslerin yerine kullanılabilir. API her zaman artı kod döndürmez.

    Hizmet bir artı kodu döndürdüğünde bu kod, genel kod ve bileşik kod olarak biçimlendirilir:

    • global_code, 4 karakterli bir alan kodu ve 6 karakter veya daha uzun bir yerel koddur (849VCWC8+R9).
    • 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.
    API, mümkün olduğunda hem genel kodu hem de birleşik kodu döndürür. Ancak sonuç uzak bir konumdaysa (ör. okyanus veya çöl) yalnızca küresel kod döndürülebilir.
  • partial_match, coğrafi kodlayıcının istenen adresin bir kısmını eşleştirebilmesine rağmen orijinal istek için tam eşleşme döndürmediğini gösterir. Orijinal isteği inceleyerek yazım hatası ve/veya eksik adres olup olmadığını kontrol edebilirsiniz.

    Kısmi eşleşmeler genellikle, istekte belirttiğiniz yerleşim biriminde bulunmayan sokak adresleri 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" ifadesi hem Henry Street hem de Henrietta Street için kısmi eşleşme döndürür. Bir istek yanlış yazılmış bir adres bileşeni içeriyorsa coğrafi kodlama hizmetinin alternatif bir adres önerebileceğini unutmayın. Bu şekilde tetiklenen öneriler de kısmi eşleşme olarak işaretlenir.

  • place_id, diğer Google API'leriyle kullanılabilen benzersiz bir tanımlayıcıdır. Örneğin, yerel bir işletmenin telefon numarası, çalışma saatleri, kullanıcı yorumları gibi ayrıntılarını almak için Places API isteğinde place_id parametresini kullanabilirsiniz. Yer kimliğine genel bakış başlıklı makaleyi 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 tüzel kişi verilebilir. address_component alanındaki types dizisi, adresin her bir bölümünün türünü belirtir. Bina numarası veya ülke bu bilgilere örnek olarak verilebilir.

Adreslerin birden çok 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 hem adres türü hem de adres bileşeni türü dizilerinde desteklenir ve döndürülür:

Adres Türü Açıklama
street_address Açık adres.
route Adlandırılmış bir rota ("US 101" gibi).
intersection Genellikle iki ana yolun kesiştiği önemli bir kavşak.
political Siyasi bir varlık. Bu tür genellikle bir sivil idarenin poligonunu belirtir.
country Ulusal siyasi varlıktır ve genellikle Coğrafi Kodlayıcı tarafından döndürülen en yüksek düzey türdür.
administrative_area_level_1 Ülke düzeyinin altındaki birinci dereceden sivil varlık. Amerika Birleşik Devletleri'nde bu idari düzeyler eyaletlerdir. Tüm ülkelerde bu idari düzeyler bulunmaz. Çoğu durumda administrative_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 sinyallere ve konum verilerine dayandığı için bu eşleşme her zaman garanti edilmez.
administrative_area_level_2 Ülke düzeyinin altındaki ikinci düzey sivil tüzel kişi. Amerika Birleşik Devletleri'nde bu idari düzeyler ilçelerdir. Tüm ülkelerde bu idari düzeyler bulunmaz.
administrative_area_level_3 Ülke düzeyinin altındaki üçüncü düzey sivil tüzel kişi. Bu tür, küçük bir idari bölümü belirtir. Tüm ülkelerde bu idari düzeyler bulunmaz.
administrative_area_level_4 Ülke düzeyinin altında dördüncü düzey sivil varlık. Bu tür, küçük bir idari bölümü belirtir. Tüm ülkelerde bu idari düzeyler bulunmaz.
administrative_area_level_5 Ülke düzeyinin altındaki beşinci düzey sivil tüzel kişi. Bu tür, küçük bir idari bölümü belirtir. Tüm ülkelerde bu idari düzeyler bulunmaz.
administrative_area_level_6 Ülke düzeyinin altındaki altıncı düzey sivil varlık. Bu tür, küçük bir idari bölümü belirtir. Tüm ülkelerde bu idari düzeyler bulunmaz.
administrative_area_level_7 Ülke düzeyinin altındaki yedinci düzey sivil tüzel kişi. Bu tür, küçük bir idari bölümü belirtir. Tüm ülkelerde bu idari düzeyler bulunmaz.
colloquial_area Varlık için yaygın olarak kullanılan alternatif bir ad.
locality Tüzel kişiliğe sahip bir şehir veya kasaba.
sublocality Bir yerleşim biriminin altındaki birinci dereceden sivil varlık. Bazı konumlar için sublocality_level_1 ile sublocality_level_5 arasından bir ek tür alabilirsiniz. Her alt yerleşim birimi düzeyi yasal bir varlıktır. Daha büyük sayılar daha küçük bir coğrafi alanı gösterir.
neighborhood Adlandırılmış bir mahalle.
premise Genellikle ortak bir ada sahip bir bina veya bina grubu olan adlandırılmış bir konum.
subpremise Tesis düzeyinin altındaki adreslenebilir bir varlık (ör. daire, birim veya süit).
plus_code Enlem ve boylamdan türetilen kodlanmış bir konum referansı. Plus code'lar, açık adreslerin bulunmadığı yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı yerlerde) açık adreslerin yerine kullanılabilir. Ayrıntılar için https://plus.codes adresine bakın.
postal_code Ülke içinde posta göndermek için kullanılan posta kodu.
natural_feature Belirgin bir doğal özellik.
airport Havalimanı.
park Adlandırılmış bir park.
point_of_interest Adlandırılmış önemli yer. Bu "ÖY"ler genellikle "Empire State Binası" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca sığmayan belirgin yerel varlıklardır.

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

Adres bileşenleri, yukarıdakilere ek olarak aşağıda listelenen türleri de içerebilir.

Adres Bileşeni Türü Açıklama
floor Bir binanın adresindeki 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ı ülkelerdeki posta adresleri için kullanılan locality ve sublocality gibi coğrafi alanların gruplandırılmasıdır.
room Bir binanın adresindeki oda.
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ını etkileme

Coğrafi Kodlama isteğinde, Coğrafi Kodlama hizmetine belirli bir görüntü alanındaki (kenarlık kutusu olarak ifade edilir) sonuçları tercih etmesini bildirebilirsiniz. Bunu, istek URL'sinde bounds parametresini ayarlayarak yaparsınız.

bounds parametresi, koordinatları ayırmak için dikey ç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 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 kesimi etrafında bir sınır kutusu tanımlayan bir bounds bağımsız değişkeni eklemek, bu coğrafi kodda Washington, D.C. şehrinin döndürülmesine 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 yönelik sonuçlar döndürmesi için talimat verebilirsiniz. Bu parametre, bölge önyargısını belirten bir ccTLD (ülke kodu üst düzey alanı) bağımsız değişkeni alır. ccTLD kodlarının çoğu, 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. Eğilimlendirmenin yalnızca belirli bir alanla ilgili sonuçları tercih ettiğini unutmayın. Bu alanın dışında daha alakalı sonuçlar varsa bunlar da dahil edilebilir.

Örneğin, Geocoding API'nin varsayılan alanı 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 bir Coğrafi Kodlama isteği, İspanya'daki şehri döndürür.

İ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 API'si, coğrafi kodlama yanıtında belirli bir alanla sınırlı adres sonuçları döndürebilir. components filtresini kullanarak kısıtlamayı belirtebilirsiniz. Filtre, boru (|) ile ayrılmış component:value çiftlerinden oluşan bir listeden 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.

Filtrelenebilir components şunları içerir:

  • postal_code, postal_code ile eşleşir ve postal_code_prefix.
  • country, bir ülke adıyla veya iki harfli ISO 3166-1 ülke koduyla eşleşiyor. 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 kılınmaz:

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

Bileşen filtreleme hakkında notlar:

  • İsteklere bu bileşen filtrelerini tekrar eklemeyin. Aksi takdirde API şu değerleri döndürür: Invalid_request: country, postal_code, route
  • İstek yinelenen bileşen filtreleri içeriyorsa API bu filtreleri VE değil VEYA olarak değerlendirir.
  • Sonuçlar Google Haritalar ile tutarlıdır ve bazen beklenmedik ZERO_RESULTS yanıtlar verir. Yer otomatik tamamlama özelliğini kullanmak bazı kullanım alanlarında daha iyi sonuçlar sağlayabilir. Daha fazla bilgi edinmek için bu SSS bölümünü inceleyin.
  • Her adres bileşenini address parametresinde veya bir components filtresinde belirtin; ikisini birden belirtmeyin. Her ikisinde de aynı değerleri belirtmek ZERO_RESULTS ile sonuçlanabilir.

components=country:GB ile "High St, Hastings" için bir coğrafi kod, ABD'deki Hastings-On-Hudson yerine İngiltere'deki Hastings'te 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" bölgesi için 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, istek binaların adlarını ve numaralarını içeriyorsa 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"
}