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 Object Notation (JSON) dosyasındaki çıkışı belirtir veya
• xml, XML'deki çıkışı gösterir

HTTPS gerekli.

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.

Her istek türü için farklı parametreler kullanılabildiğinden bu sayfanın geri kalanında, coğrafi kodlama ve ters coğrafi kodlama ayrı ayrı açıklanmaktadır.

Coğrafi kodlama (enlem/boylam araması) parametreleri

Coğrafi kodlama isteğinde gerekli parametreler:

• address: Coğrafi kodlamak istediğiniz sokak adresi veya plus kodu. Adresleri, ilgili ülkenin ulusal posta servisi tarafından kullanılan biçime göre 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 ile URL çıkışlı olarak gösterilmektedir):

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

  Artı kodlarını burada gösterildiği gibi biçimlendirin (artı işaretleri %2B için URL çıkışlı, boşluklar ise %20 için URL çıkışlıdır):
  • global kod, 4 karakterli alan kodu ve 6 veya daha uzun bir yerel koddur (849VCWC8+R9, 849VCWC8%2BR9 şeklindedir).
  • Karma kod, açık bir konuma sahip 6 karakter veya daha uzun bir yerel koddur (CWC8+R9 Mountain View, CA, ABD için CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --VEYA--
  components: Bir boru (|) ile ayrılmış öğeleri içeren bileşen filtresi. address sağlanırsa bileşen filtresi isteğe bağlı parametre olarak da kabul edilir. Bileşen 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.
• key — Uygulamanızın API anahtarı. Bu anahtar, kota yönetimi amacıyla uygulamanızı tanımlar. Anahtar edinme hakkında bilgi edinin.

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 kodlamada daha belirgin sonuçlar elde edilecek görüntü alanının sınırlayıcı kutusu. Bu parametre yalnızca coğrafi kodlayıcıdan gelen sonuçları etkiler, tam olarak kısıtlamaz. (Daha fazla bilgi için aşağıdaki Görünüme Ağırlık Verme konusuna bakın.)
• language — Sonuçların döndürüleceği dil.
  • Desteklenen dillerin listesini inceleyin. Google, desteklenen dilleri sı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şleşmeyi kullanır.
  • Tercih edilen dilin, API'nin döndürmeyi seçtiği sonuç kümesi ve döndürülme sırası üzerinde küçük bir etkisi vardır. Coğrafi kodlayıcı, kısaltmaları dile bağlı olarak farklı şekilde yorumlar. Örneğin, sokak türlerinin kısaltmaları ya da bir dilde geçerli olup başka bir dilde geçerli olmayan eş anlamlı kelimeler olabilir. Örneğin, Macarcada utca ve tér sırasıyla sokak ve kare için eş anlamlıdır.
• region: ccTLD ("üst düzey alan") iki karakterli değer olarak belirtilen bölge kodu. Bu parametre yalnızca coğrafi kodlayıcıdan gelen sonuçları etkiler, tam olarak kısıtlamaz. (Daha fazla bilgi için aşağıdaki Bölgeye Ağırlık Verme bölümüne bakın.) Parametre, geçerli yasalara 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şen 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:
  • ADDRESS_DESCRIPTORS — Daha fazla bilgi için adres tanımlayıcıları bölümüne bakın.
  • BUILDING_AND_ENTRANCES — Daha fazla bilgi için girişler ve bina dış çizgileri bölümüne bakın.
  Aynı API isteğinde bu özelliklerden birden fazlasını etkinleştirmek için her özellikle ilgili 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 kullanımını gösterir:

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

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

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

<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 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", hiçbir hata oluşmadığını belirtir; adresin başarıyla ayrıştırıldığını ve en az bir coğrafi kod döndürüldüğünü gösterir.
• "ZERO_RESULTS", coğrafi kodlamanın başarılı olduğunu ancak hiçbir sonuç döndürmediğini gösterir. Bu durum, coğrafi kodlayıcıya var olmayan 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ı.
  • Belirtilen ödeme yöntemi artık geçerli değil (örneğin, bir kredi kartının geçerlilik süresi dolmuş).

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

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

Hata mesajları

Coğrafi kodlayıcı OK dışında bir durum kodu döndürdüğünde, Coğrafi Kodlama yanıt nesnesinde ek bir error_message alanı olabilir. Bu alanda, belirtilen durum kodunun nedenleri hakkında daha ayrıntılı bilgiler yer alır.

Sonuçlar

Coğrafi kodlayıcı, sonuçları döndürdüğünde bu sonuçları bir (JSON) results dizisi içine yerleştirir. Coğrafi kodlayıcı hiçbir sonuç döndürmese bile (adresin olmaması gibi) yine de boş bir results dizisi döndürür. (XML yanıtları sıfır veya daha fazla <result> öğesinden oluşur.)

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

• types[] dizisi, döndürülen sonucun türünü gösterir. Bu dizi, sonuçta döndürülen özelliğin türünü tanımlayan bir veya daha fazla etiket kümesi içerir. Örneğin, "Şikago"nun coğrafi kodu, "Chicago"nun bir şehir olduğunu belirten "locality" (yerellik) değerini ve aynı zamanda bu ülkenin politik bir varlık olduğunu belirten "politik" değerini döndürür. Adres bileşeni için bilinen bir tür olmadığında bileşenlerde boş tür dizisi olabilir. API, gerektiğinde yeni tür değerleri ekleyebilir. Daha fazla bilgi için Adres türleri ve adres bileşenleri başlıklı makaleyi inceleyin.
• formatted_address, bu konumun okunabilir adresini içeren bir dizedir.

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

  Biçimlendirilmiş adres, mantıksal olarak bir veya daha fazla adres bileşeninden oluşur. Örneğin, "111 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 programlı olarak ayrıştırmayın. Bunun yerine, biçimlendirilmiş adres alanına ek olarak API yanıtının içerdiği bağımsız adres bileşenlerini kullanmanız gerekir.

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

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

  • types[], adres bileşeninin türünü 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ış metin adıdır. Örneğin, Alaska eyaleti için bir adres bileşeninde 2 harfli posta kısaltması kullanılarak long_name "Alaska" ve short_name "AK" bulunabilir.

  address_components[] dizisiyle ilgili aşağıdaki gerçeklere dikkat edin:

  • Adres bileşenleri dizisi, formatted_address'ten daha fazla bileşen içerebilir.
  • Dizi, formatted_address içinde yer alanların dışında, bir adres içeren tüm siyasi varlıkları içermeyebilir. Belirli bir adresi içeren tüm siyasi varlıkları almak için tersine coğrafi kodlama kullanmanız ve adresin enlem/boylam değerlerini isteğe parametre olarak iletmeniz gerekir.
  • 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 yerleşimi 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 olarak kodlanmış enlem ve boylam değerini içeriyor. Normal adres aramaları için bu alan genellikle en önemlidir.

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

    • "ROOFTOP", döndürülen sonucun 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 yapılmış yaklaşık bir değeri (genellikle bir yolda) yansıttığını gösterir. İnterpole edilmiş sonuçlar genellikle bir sokak adresi için çatı coğrafi kodları kullanılamadığında döndürülür.
    • "GEOMETRIC_CENTER", döndürülen sonucun, çoklu çizgi (örneğin, sokak) veya poligon (bölge) gibi bir sonucun geometrik merkezi olduğunu belirtir.
    • "APPROXIMATE", döndürülen sonucun yaklaşık olduğunu belirtir.
  • viewport, döndürülen sonucu görüntülemek için önerilen görüntü alanını içerir. Bu alan, görüntü alanı sınırlayıcı kutusunun southwest ve northeast köşesini 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 kapsayabilecek sınır kutusuna sahiptir. Bu sınırların önerilen görüntü alanıyla eşleşmeyebileceğini unutmayın. (Örneğin, San Francisco, teknik olarak şehrin bir parçası olan ancak muhtemelen görüntü alanına döndürülmemesi gereken Farallon Adaları'nı da içerir.)
• plus_code (Açık Konum Kodu ve artı kodları bölümüne bakın), enlem ve boylam koordinatlarından türetilen, bir alanı temsil eden kodlanmış bir konum referansı: derecenin 1/8000'i ile derecenin 1/8000'i (ekvatorda yaklaşık 14 m x 14 m) veya daha küçük bir alan. 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ı kodu 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 programlı bir şekilde ayrıştırmayın.
  API, mümkün olduğunda hem genel kodu hem de birleşik kodu döndürür. Bununla birlikte, sonuç uzak bir konumda (ör. bir okyanus veya çöl) yer alıyorsa yalnızca küresel kod döndürülebilir.

• partial_match, coğrafi kodlayıcının orijinal istek için tam eşleşme döndürmediğini, ancak istenen adresin bir kısmını eşleştirebildiğini gösterir. Orijinal isteği yazım hataları ve/veya eksik adres olup olmadığını kontrol etmek isteyebilirsiniz.

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

• place_id, diğer Google API'leriyle kullanılabilecek benzersiz bir tanımlayıcıdır. Örneğin, 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ış sayfasını inceleyin.

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

Sonuçtaki types[] dizisi, adres türünü belirtir. Adres türlerine örnek olarak açık adres, ülke veya siyasi tüzel kişi verilebilir. address_components[] içinde, adresin her bir bölümünün türünü gösteren bir types[] dizisi de bulunur. Bina numarası veya ülke bilgisi örnek olarak verilebilir. (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.

Coğrafi kodlayıcı, aşağıdaki türleri hem adres türü hem de adres bileşeni türü dizilerinde destekler ve döndürür:

• street_address, tam açık adresi gösterir.
• route, adlandırılmış bir rotayı gösterir (ör. "TR 101").
• intersection, genellikle iki ana yolun kesiştiği önemli bir kavşağı gösterir.
• political, siyasi bir tüzel kişiyi gösterir. Bu tür genellikle bir sivil yönetim poligonunu gösterir.
• country, ulusal siyasi varlığı gösterir ve genellikle Coğrafi Kodlayıcı tarafından döndürülen en yüksek sipariş türüdür.
• administrative_area_level_1, ülke düzeyinin altındaki birinci sınıf sivil bir varlığı gösterir. 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ında ikinci düzey bir sivil tüzel kişiyi gösterir. Amerika Birleşik Devletleri'nde bu idari düzeyler illerdir. Tüm uluslar bu idari seviyelerde değildir.
• administrative_area_level_3, ülke düzeyinin altındaki üçüncü düzey sivil bir varlığı gösterir. Bu tür, küçük bir idari bölümü belirtir. Tüm uluslar bu idari düzeylerde değildir.
• administrative_area_level_4, ülke düzeyinin altında dördüncü dereceden bir sivil tüzel kişiyi gösterir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.
• administrative_area_level_5, ülke düzeyinin altında beşinci düzey bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.
• administrative_area_level_6, ülke düzeyinin altında altıncı dereceden bir sivil tüzel kişiyi gösterir. 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ında yedinci düzey sivil tüzel kişiyi gösterir. Bu tür, küçük bir sivil toplum bölmesini belirtir. Tüm uluslar bu idari düzeylerde değildir.
• colloquial_area, öğe için yaygın olarak kullanılan alternatif bir adı gösterir.
• locality, anonim bir şehir veya kasaba siyasi tüzel kişiliğini belirtir.
• sublocality, bir yerin altındaki birinci sınıf sivil bir varlığı gösterir. Bazı konumlar için ek türlerden birini alabilirsiniz: sublocality_level_1 ila sublocality_level_5. Her alt konum düzeyi bir sivil tüzel kişidir. Daha büyük sayılar daha küçük bir coğrafi alanı gösterir.
• neighborhood, adlandırılmış bir mahalleyi gösterir.
• premise, genellikle ortak bir ada sahip bir bina veya bina topluluğu olan adlandırılmış bir konumu gösterir.
• subpremise, tesis düzeyinin altında adreslenebilir bir varlığı (ör. apartman, daire veya daire) belirtir.
• plus_code, enlem ve boylamdan türetilen kodlanmış bir konum referansını gösterir. 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çindeki posta postaları için kullanılan posta kodunu belirtir.
• natural_feature belirgin bir doğal özelliği gösterir.
• airport, havaalanını gösterir.
• park, adlandırılmış bir parkı gösterir.
• point_of_interest, adlandırılmış bir önemli yeri gösterir. Bu "ÖY"ler genellikle "Empire State Building" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca sığmayan belirgin yerel varlıklardır.

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

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

• floor bir bina adresinin katını gösterir.
• establishment genellikle henüz kategorize edilmemiş bir yeri gösterir.
• landmark, navigasyona yardımcı olmak için referans olarak kullanılan yakındaki bir yeri gösterir.
• point_of_interest, adlandırılmış bir önemli yeri gösterir.
• parking, bir otopark veya otopark yapısını gösterir.
• post_box, belirli bir posta kutusunu gösterir.
• postal_town, bazı ülkelerde posta adresleri için kullanılan locality ve sublocality gibi coğrafi alanların gruplandırılmasını gösterir.
• room, bir bina adresinin odasını belirtir.
• street_number tam sokak numarasını gösterir.
• bus_station, train_station ve transit_station, bir otobüs, tren veya toplu taşıma durağının konumunu gösterir.

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

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

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

Örneğin, "Washington" için 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ğusu çevresinde bir sınırlayıcı kutu tanımlayan bounds bağımsız değişkeni eklendiğinde, bu coğrafi kod Washington, D.C. şehrini döndürür.

İstek:

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

Yanıt:

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

Bölgeye ağırlık verme

Bir Coğrafi Kodlama isteğinde, region parametresini kullanarak Coğrafi Kodlama hizmetine belirli bir bölgeye ağırlık veren sonuçları döndürmesi talimatını 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 kodu, bazı önemli istisnalar dışında ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk) iken ISO 3166-1 kodu "gb"dir (teknik olarak "Büyük Britanya ve Kuzey İrlanda Birleşik Krallığı" tüzel kişiliği için).

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

Örneğin, Geocoding API'nin varsayılan alanı 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 yanıtında, Geocoding API belirli bir alanla kısıtlanmış adres sonuçlarını döndürebilir. components filtresini kullanarak kısıtlamayı belirtebilirsiniz. Filtre, boru (|) ile ayrılmış component:value çiftlerinin bir listesinden oluşur. Filtre değerleri, diğer coğrafi kodlama istekleriyle aynı yazım düzeltme ve kısmi eşleme yöntemlerini destekler. Coğrafi kodlayıcı bir bileşen filtresi için kısmi eşleşme bulursa yanıt bir partial_match alanı içerir.

Filtrelenebilir components şunlardır:

• postal_code; postal_code ve postal_code_prefix ile eşleşir.
• country, bir ülke adıyla veya iki harfli ISO 3166-1 ülke koduyla eşleşir. API, ülkeleri tanımlamak için ISO standardını kullanır ve filtreleme, ülkenin ilgili ISO kodu kullanıldığında en iyi şekilde çalışır.

Aşağıdaki components, sonuçları etkilemek için kullanılabilir ancak zorunlu 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 tekrarlanan 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 için bu SSS sayfasına göz atın.
• Her bir adres bileşeni için bunu ya address parametresinde ya da components filtresinde belirtin ancak ikisinde birden belirtmeyin. Her ikisinde de aynı değerleri belirtmek ZERO_RESULTS ile sonuçlanabilir.

"High St, Hastings" için components=country:GB kodlu bir coğrafi kod, Hastings-On-Hudson, ABD yerine İngiltere'nin Hastings şehrinde sonuç döndürür.

İstek:

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

Yanıt:

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

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 oluşturabilirsiniz. (Tam adresin coğrafi kodlaması yapılırken istek, binaların adlarını ve numaralarını içeriyorsa address parametresi gerekir.)

İstek:

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

Yanıt:

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