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

İstek

Geocoding API isteği aşağıdaki biçimde olur:

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

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

• json (önerilir), çıkışı JavaScript Object Notation (JSON) biçiminde belirtir veya
• xml, XML'deki çıkışı belirtir

API anahtarı kullanan istekler için HTTPS gereklidir.

Bazı parametreler zorunlu, bazıları ise isteğe bağlıdır. URL'lerde standart olduğu gibi, parametreler "ve" (&) 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 arama) parametreleri

Coğrafi kodlama isteğinde gerekli parametreler:

• address: Coğrafi kodlamasını yapmak istediğiniz açık adres veya artı kodu. Adresleri, ilgili ülkenin ulusal posta hizmeti tarafından kullanılan biçime uygun şekilde belirtin. İşletme adları ve birim, daire veya kat numaraları gibi ek adres öğelerinden kaçınılmalıdır. Açık adres öğeleri boşlukla ayrılmalıdır (burada %20 için URL çıkışlı olarak gösterilmiştir):

  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 da %20 için URL çıkışlı olarak yapılır):
  • global kod, 4 karakterden oluşan bir alan kodu, 6 veya daha uzun bir yerel koddur (849VCWC8+R9, 849VCWC8%2BR9'dir).
  • bileşik kod, konumu açıkça belirtilmiş, 6 karakterli veya daha uzun bir yerel koddur (CWC8+R9 Mountain View, CA, ABD: CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --OR--
  components — Dikey çizgiyle (|) ayrılmış öğelere sahip bir bileşen filtresidir. address sağlanırsa bileşen filtresi de isteğe bağlı bir parametre olarak kabul edilir. Bileşenler filtresindeki her bir öğ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. Nasıl anahtar edineceğinizi öğrenin.

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

Coğrafi Kodlama isteğindeki isteğe bağlı parametreler:

• bounds: Coğrafi kodlama sonuçlarını daha belirgin bir şekilde etkilemek için görüntü alanının sınırlayıcı kutusu. Bu parametre coğrafi kodlayıcıdan gelen sonuçları tamamen kısıtlamaz, yalnızca etkiler. (Daha fazla bilgi için aşağıdaki Görüntü Alanına Ağırlık Verme 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 kapsamlı 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 ana dilini kullanmaya çalışır.
  • Coğrafi kodlayıcı, hem kullanıcı hem de bölge sakinleri tarafından okunabilen bir açık adres sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için açık adresleri, gerektiğinde kullanıcı tarafından okunabilecek bir alfabeye çevrilmiş olarak yerel dilde döndürür ve tercih edilen dili gözlemler. 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 bulunmuyorsa coğrafi kodlayıcı en yakın eşleşmeyi kullanır.
  • Tercih edilen dilin, API'nin döndürmeyi seçtiği sonuç grubu ve bunların döndürülme sırası üzerinde küçük bir etkisi vardır. Coğrafi kodlayıcı, kısaltmaları dile bağlı olarak farklı şekillerde yorumlar. Örneğin, sokak türlerinin kısaltmaları veya bir dilde geçerli olup bir başkada geçerli olmayan eş anlamlılar. Örneğin utca ve tér kelimeleri, Macarcada sırasıyla sokak ve meydan kelimelerinin 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 gelen sonuçları tamamen kısıtlamaz, yalnızca etkiler. (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: Dikey çizgi (|) ile ayrılmış öğeler içeren bileşen filtresidir. İstek bir address içermiyorsa bileşen filtresi zorunludur. Bileşenler filtresindeki her bir öğ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.

Yanıtlar

Coğrafi kodlama yanıtları, URL isteği iç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ği ile ilgili bir sorgu için json yanıtı istemektedir. Bu yerin kimliği 1600 Amphitheatre Parkway, Mountain View, CA adresindeki binaya aittir.

Bu istek, JSON output işaretinin kullanımı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ı takip etmenize yardımcı olacak hata ayıklama bilgilerini içerebilir. "status" alanı şu değerleri içerebilir:

• "OK" hata oluşmadığını belirtir; adres başarıyla ayrıştırılır ve en az bir coğrafi kod döndürüldü.
• "ZERO_RESULTS", coğrafi kodun başarılı olduğunu ancak sonuç döndürmediğini belirtir. Coğrafi kodlayıcı var olmayan bir address iletildiyse bu durum ortaya çıkabilir.
• OVER_DAILY_LIMIT, aşağıdakilerden herhangi birini belirtir:
  • API anahtarı eksik veya geçersiz.
  • Hesabınızda faturalandırma etkinleştirilmemiştir.
  • Kendi kendine uygulanan kullanım sınırı aşıldı.
  • Sağlanan ödeme yöntemi artık geçerli değil (ör. kredi kartının geçerlilik süresi sona ermiş).

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

• "OVER_QUERY_LIMIT", kotanızı aştığınızı gösterir.
• "REQUEST_DENIED", isteğinizin reddedildiğini gösterir.
• "INVALID_REQUEST" genellikle sorgunun (address, components veya latlng) eksik olduğunu belirtir.
• "UNKNOWN_ERROR", sunucu hatası nedeniyle isteğin işlenemediğini belirtir. 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 nedenleriyle ilgili daha ayrıntılı bilgiler yer alır.

Sonuçlar

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

Normal 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 bir sıfır veya daha fazla etiket kümesi içerir. Örneğin, "Chicago"nun coğrafi kodu, "Chicago"nun bir şehir olduğunu belirten "konum" değerini ve aynı zamanda "politik" (politik bir varlık) değerini döndürür. Söz konusu adres bileşeni için bilinen bir tür olmadığında bileşenlerde boş bir 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ı makaleye göz atın.
• formatted_address, bu konumun okunabilir adresini içeren bir dizedir.

  Bu adres çoğu zaman 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 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 programlı bir şekilde 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ış metin adıdır. Örneğin, Alaska eyaletinin bir adres bileşeninde 2 harfli posta kısaltması kullanılarak long_name "Alaska" ve short_name olarak "AK" kullanılabilir.

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

  • Adres bileşenleri dizisi, formatted_address seçeneğinden daha fazla bileşen içerebilir.
  • Dizi, formatted_address özelliğindekiler dışında bir adres içeren tüm siyasi varlıkları içermez. Belirli bir adres içeren tüm siyasi varlıkları almak için ters coğrafi kodlamayı kullanmanız ve adresin enlemini/boylamını isteğe bir parametre olarak iletmeniz gerekir.
  • İstekler arasında yanıt biçiminin 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, 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ırmanız ve ifadeler aracılığıyla uygun değerleri seçmeniz gerekir. Yanıt ayrıştırma ile ilgili kılavuza bakın.

• postcode_localities[], bir posta kodunda bulunan en fazla 100 şehri belirten bir dizidir. Bu durum, yalnızca sonuç birden fazla şehir içeren bir posta kodu olduğunda ortaya çıkar.
• geometry aşağıdaki bilgileri içerir:
  • location, coğrafi kodlu enlem ve boylam değerini içerir. Normal adres aramaları için bu alan genellikle en önemli 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 hassasiyetine kadar doğru konum bilgilerine sahip olduğumuz kesin bir coğrafi kod olduğunu belirtir.
    • "RANGE_INTERPOLATED", döndürülen sonucun iki kesin nokta (kavşaklar gibi) arasında interpolasyon uygulanan bir yaklaşık (genellikle yol üzerinde) yansıttığını belirtir. İ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. Görüntü alanı sınırlayıcı kutusunun southwest ve northeast köşesini tanımlayan iki enlem ve boylam değeri belirtilir. Görüntü alanı genellikle bir sonucu kullanıcıya gösterirken çerçevelemek için kullanılır.
  • bounds (isteğe bağlı olarak döndürülür) döndürülen sonucu tamamen içerebilen sınırlayıcı kutuyu depolar. Bu sınırların, önerilen görüntü alanıyla eşleşmeyebileceğini unutmayın. (Örneğin San Francisco, teknik olarak şehrin bir parçası olan, ancak muhtemelen görüntü alanına döndürülmemesi gereken Farallon adalarını içerir.)
• plus_code (bkz. Açık Konum Kodu ve artı kodları), bir alanı temsil eden ve enlem ve boylam koordinatlarından türetilen kodlanmış konum referansıdır: Derecenin 1/8.000'i derecenin 1/8.000'inde (ekvatorda yaklaşık 14 m x 14 m) veya daha küçük bir alanı temsil eder. Artı kodları, adreslerin bulunmadığı yerlerde (binaların numaralandırılmamış veya caddelerin adlandırılmadığı) açık adreslerin yerine kullanılabilir. API her zaman artı kodlarını döndürmez.

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

  • global_code, 4 karakterli bir alan kodu ve 6 karakter ya da daha uzun bir yerel koddur (849VCWC8+R9).
  • compound_code, konumu açıkça belirtilmiş, 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.
  Mümkün olduğunda API, hem global kodu hem de bileşik kodu döndürür. Ancak sonuç uzak bir konumdaysa (ör. okyanus veya çöl) yalnızca global 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 belirtir. Orijinal talebi inceleyerek yazım hataları ve/veya eksik adres olup olmadığını kontrol edebilirsiniz.

  Kısmi eşleşmeler çoğunlukla istekte ilettiğiniz konum içinde bulunmayan açık adresler için ortaya çıkar. Bir istek aynı konumdaki iki veya daha fazla konumla eşleştiğinde de kısmi eşleşmeler döndürülebilir. Örneğin, "İstiklal, İstanbul, Türkiye" olsun, İstanbul Caddesi ve Üsküdar için kısmen eşleşme döndürülü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 birlikte kullanılabilecek benzersiz bir tanımlayıcıdır. Örneğin, bir yerel işletmeyle ilgili telefon numarası, çalışma saatleri, kullanıcı yorumları gibi ayrıntıları almak için bir Places API isteğinde place_id öğesini kullanabilirsiniz. Yer kimliğine genel bakış konusuna göz atın.

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. Ayrıca address_components[] içinde, adresin her bir bölümünün türünü gösteren bir types[] dizisi bulunur. Sokak numarası veya ülke buna örnek olarak verilebilir. (Aşağıda türlerin tam listesi verilmiştir.) Adreslerin birden fazla türü olabilir. Türler, "etiket" olarak kabul edilebilir. Örneğin, birçok şehir political ve locality türüyle etiketlenmiştir.

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

• street_address, tam açık adresi belirtir.
• route, adlandırılmış bir rotayı gösterir (ör. "US 101").
• intersection, genellikle iki ana yoldan oluşan ana kavşağı gösterir.
• political, siyasi bir tüzel kişiyi belirtir. Bu tür genellikle sivil yönetim poligonunu gösterir.
• country, ulusal siyasi varlığı belirtir 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ında yer alan birinci dereceden sivil tüzel kişiyi belirtir. ABD'de bu idari düzeyler eyaletlerdir. Tüm uluslar bu idari seviyeleri göstermez. Çoğu durumda idari_area_level_1 kısa adlar, ISO 3166-2 alt bölümleri ve geniş çapta dağıtılan diğer listelerle yakından eşleşir. Ancak coğrafi kodlama sonuçlarımız çeşitli sinyallere ve konum verilerine dayandığından bu garanti edilmez.
• administrative_area_level_2, ülke düzeyinin altındaki ikinci dereceden sivil tüzel kişiyi belirtir. ABD'de bu idari düzeyler ilçedir. Tüm uluslar bu idari seviyeleri göstermez.
• administrative_area_level_3, ülke düzeyinin altındaki üçüncü dereceden sivil tüzel kişiyi belirtir. Bu tür, küçük sivil toplum bölümlerini gösterir. Tüm uluslar bu idari seviyeleri göstermez.
• administrative_area_level_4, ülke düzeyinin altında dördüncü dereceden bir sivil tüzel kişiyi belirtir. Bu tür, küçük sivil toplum bölümlerini gösterir. Tüm uluslar bu idari seviyeleri göstermez.
• administrative_area_level_5, ülke düzeyinin altında olan beşinci dereceden bir sivil tüzel kişiyi belirtir. Bu tür, küçük sivil toplum bölümlerini gösterir. Tüm uluslar bu idari seviyeleri göstermez.
• administrative_area_level_6, ülke düzeyinin altında kalan altıncı dereceden bir sivil tüzel kişiyi belirtir. Bu tür, küçük sivil toplum bölümlerini gösterir. Tüm uluslar bu idari seviyeleri göstermez.
• administrative_area_level_7, ülke düzeyinin altında yedinci dereceden bir sivil tüzel kişiyi belirtir. Bu tür, küçük sivil toplum bölümlerini gösterir. Tüm uluslar bu idari seviyeleri göstermez.
• colloquial_area, varlık için yaygın olarak kullanılan alternatif adı gösterir.
• locality, anonim bir şehir veya kasaba siyasi tüzel kişiliğini belirtir.
• sublocality, bir yerel bölge altındaki birinci dereceden sivil tüzel kişiyi belirtir. Bazı konumlar için şu ek türlerden biri alınabilir: sublocality_level_1-sublocality_level_5. Her alt konum düzeyi medeni bir varlıktır. Büyük sayılar, daha küçük bir coğrafi alanı belirtir.
• neighborhood, adlandırılmış bir mahalleyi belirtir
• premise, adlandırılmış bir konumu belirtir (genellikle ortak bir ada sahip bir bina veya bina topluluğu)
• subpremise, adlandırılmış bir konumun altında birinci dereceden varlığı (genellikle ortak bir ada sahip bir bina topluluğu içinde tek bir bina) belirtir.
• plus_code, enlem ve boylamdan türetilen kodlanmış bir konum referansını gösterir. Artı kodları, var olmayan (bina numaralandırılmamış veya sokakların adlanmadığı yerlerde) açık adreslerin yerine kullanılabilir. Ayrıntılar için https://plus.codes sayfasına bakın.
• postal_code, ülke içindeki posta adresine yanıt vermek için kullanılan bir posta kodunu belirtir.
• natural_feature, belirgin bir doğal özelliği belirtir.
• airport bir havaalanını belirtir.
• park, adlandırılmış bir parkı belirtir.
• point_of_interest, adlandırılmış bir önemli noktayı gösterir. Genellikle bu "ÖY"ler, "Empire State Binası" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca sığmayan belirgin yerel varlıklardır.

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

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

• 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 belirtir.
• point_of_interest, adlandırılmış bir önemli noktayı gösterir.
• parking bir park yeri veya park 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 gruplandırmasını belirtir.
• room, bir bina adresinin odasını belirtir.
• street_number, tam sokak numarasını belirtir.
• bus_station, train_station ve transit_station bir 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ı içindeki (sınırlayıcı kutu olarak ifade edilir) sonuçları tercih etmesi talimatını verebilirsiniz. Bu işlemi, istek URL'sinde bounds parametresini ayarlayarak yaparsınız.

bounds parametresi, koordinatları ayırmak için bir dikey çizgi (|) karakterini 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 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"
}

Bununla birlikte, ABD'nin kuzeydoğusundaki sınırlayıcı kutuyu tanımlayan bir 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

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 ön yargısını belirten bir ccTLD (ülke kodu üst düzey alan) bağımsız değişkeni alır. Çoğu ccTLD kodu, bazı önemli istisnalar dışında ISO 3166-1 kodlarıyla aynıdır. Örneğin, Birleşik Krallık'ın ccTLD'si "uk" (.co.uk) ve 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 önyargılı olabilir. Ağırlık vermenin yalnızca belirli bir alan için sonuçları tercih ettiğini unutmayın. Bu alan dışında daha alakalı sonuçlar varsa onlar da dahil edilebilir.

Örneğin, Geocoding API'nin varsayılan alanı ABD olarak ayarlandığı için "Toledo"nun coğrafi kodlaması 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) için gönderilen "Toledo" coğrafi kodlama isteği, İspanya şehrini 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, Coğrafi Kodlama API'si belirli bir alanla kısıtlanmış adres sonuçlarını döndürebilir. Kısıtlamayı, components filtresini kullanarak belirtebilirsiniz. Filtre, dikey çizgi (|) 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şleşme yöntemlerini destekler. Coğrafi kodlayıcı bir bileşen filtresiyle kısmi eşleşme bulursa yanıtta bir partial_match alanı bulunur.

Filtrelenebilecek components verileri:

• postal_code; postal_code ve postal_code_prefix ile eşleşiyor.
• country, bir ülke adı veya iki harfli ISO 3166-1 ülke koduyla eşleşir. API, ülkeleri tanımlamak için ISO standardına uyar ve filtreleme, ülkenin ilgili ISO kodu kullanıldığında en iyi sonucu verir. 'nda bulabilirsiniz.

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şiyor.

Bileşen filtreleme hakkında notlar:

• İsteklerde şu bileşen filtrelerini tekrarlamayın. Aksi takdirde API, Invalid_request değerini döndürür: country, postal_code, route
• İstek tekrarlanan bileşen filtreleri içeriyorsa API bu filtreleri VEYA değil, VE olarak değerlendirir.
• Sonuçlar, zaman zaman beklenmedik ZERO_RESULTS yanıtları veren Google Haritalar ile tutarlıdır. Otomatik Yer Tamamlama'yı kullanmak bazı kullanım durumlarında daha iyi sonuçlar sağlayabilir. Daha fazla bilgi edinmek için bu SSS sayfasına göz atın.
• Her bir adres bileşeni için bunu address parametresinde veya components filtresinde belirtin ancak her ikisinde birden belirtmeyin. Her ikisinde de aynı değerlerin belirtilmesi ZERO_RESULTS sonucunu verebilir.

"High St, Hastings" için components=country:GB ile kullanılacak coğrafi kod, Hastings-On-Hudson, ABD'den ziyade Hastings, İngiltere'den sonuç döndürmektedir.

İ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 coğrafi kod isteği, İspanya, 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 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 address parametresi olmadan geçerli sorgular yapabilirsiniz. (Tam adresin coğrafi kodlamasını yaparken, istek bina 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"
}