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), çıkışı JavaScript Object Notation (JSON) biçiminde belirtir veya
• xml, çıkışı XML biçiminde gösterir

HTTPS gerekiyor.

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 çıkış karakterli 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 %20 için çıkışlıdır):
  • global kod, 4 karakterlik bir alan kodu ve 6 karakter veya daha uzun bir yerel koddur (849VCWC8+R9, 849VCWC8%2BR9).
  • birleşik kod, konumu açıkça belirtilmiş olan, 6 karakter veya daha uzun bir yerel koddur (CWC8+R9 Mountain View, CA, ABD'de CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --OR--
  components — Dikey çizgi (|) ile ayrılmış öğelere sahip bir bileşen filtresi. 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 alacağınızı öğ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 kodlamaya ağırlık vermekte kullanılacak görüntü alanının sınırlayıcı kutusu, sonuçları daha belirgin bir şekilde gösterir. Bu parametre yalnızca coğrafi kodlayıcıdan gelen sonuçları etkiler, tamamen kısıtlamaz. (Daha fazla bilgi için aşağıdaki Görünüme 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ıklıkla güncellediğinden bu liste tam olmayabilir.
  • language belirtilmezse coğrafi kodlayıcı, Accept-Language üst bilgisinde 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 bölge sakinleri tarafından okunabilen bir açık adres sağlamak için elinden geleni yapar. Bu hedefe ulaşmak için, yerel dildeki açık adresleri, gerektiğinde kullanıcı tarafından okunabilecek bir alfabeye çevrilmiş şekilde, tercih edilen dilde 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 sunulmuyorsa 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ı, sokak türlerinin kısaltmaları veya bir dilde geçerli olup bir başkasında geçerli olmayan eş anlamlılar gibi kısaltmaları dile bağlı olarak farklı şekilde yorumlar. Örneğin utca ve tér, Macarcada sırasıyla sokak ve meydan ile eş anlamlı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ı etkiler, tamamen 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: Dikey çizgi (|) ile ayrılmış öğelere sahip bir bileşen filtresidir. İstek address içermiyorsa bileşen filtresi gereklidir. 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ğ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 bina içindir.

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

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östermektedir:

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

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

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

Durum kodları

Coğrafi Kodlama yanıt nesnesindeki "status" alanı, isteğin durumunu içerir ve coğrafi kodlamanın neden çalışmadığını izlemenize yardımcı olacak hata ayıklama bilgilerini içerebilir. "status" alanı ş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ülür.
• "ZERO_RESULTS", coğrafi kodun başarılı olduğunu ancak sonuç döndürmediğini belirtir. Bu durum, coğrafi kodlayıcının var olmayan bir address iletilmiş olması durumunda gerçekleşebilir.
• OVER_DAILY_LIMIT, aşağıdakilerden herhangi birini belirtir:
  • API anahtarı eksik veya geçersiz.
  • Hesabınızda faturalandırma etkinleştirilmemiştir.
  • Kullanım sınırı aşıldı.
  • Sağlanan ödeme yöntemi artık geçerli değil (örneğin, bir kredi kartının geçerlilik süresi sona ermiş).

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

• "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 nedenleri hakkında daha ayrıntılı bilgiler yer alır.

Sonuçlar

Coğrafi kodlayıcı sonuçlar döndürdüğünde sonuçları bir (JSON) results dizisine yerleştirir. Coğrafi kodlayıcı hiçbir sonuç döndürmese bile (adres yoksa bile) 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, "İstanbul"un bir şehir olduğunu belirten "konum"u ve ayrıca "siyasi" bir coğrafi varlık olduğunu belirten "politik" değerini döndürür. Adres bileşeni için bilinen bir tür olmadığında bileşenlerin 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 konusuna bakın.
• formatted_address, bu konumun kullanıcılar tarafından okunabilen adresini içeren bir dizedir.

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

  Biçimlendirilmiş adres, mantıksal olarak bir veya daha fazla adres bileşeninden oluşur. Ö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ı 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şeni için kısaltılmış metin biçiminde bir addır. Örneğin, Alaska eyaletinin adres bileşeninde 2 harfli posta kısaltması kullanılarak long_name "Alaska" ve short_name "AK" kullanılabilir.

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

  • Adres bileşenleri dizisi, formatted_address öğesinden daha fazla bileşen içerebilir.
  • Dizi, formatted_address içinde yer alanlar dışında, bir adres içeren tüm siyasi varlıkları içermez. Belirli bir adres içeren tüm siyasi varlıkları geri almak için ters coğrafi kodlama kullanmanız ve adresin enlem/boylamını isteğe 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 konumunu 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ırmalı ve ifadeler aracılığıyla uygun değerleri seçmeniz gerekir. Yanıtları ayrıştırma rehberini inceleyin.

• postcode_localities[], bir posta kodunda yer alan 100'e kadar ş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 olarak kodlanmış enlem, boylam değerini içeriyor. Normal adres aramaları için bu alan genellikle en önemli olanıdı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 kesinliğine kadar doğru konum bilgilerine sahip olduğumuz tam coğrafi kod olduğunu belirtir.
    • "RANGE_INTERPOLATED", döndürülen sonucun iki kesin nokta (kavşaklar gibi) arasında ortalama olarak hesaplanan bir yaklaşık (genellikle yol üzerinde) yansıtıldığı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 (ör. 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, görüntü alanı sınırlama kutusunun southwest ve northeast köşesini tanımlayan iki enlem, boylam değeri olarak belirtilen, döndürülen sonucu görüntülemek için önerilen görünümü içerir. Görüntü alanı, genellikle bir sonucu kullanıcıya görüntülerken çerçevelemek için kullanılır.
  • bounds (isteğe bağlı olarak döndürülür) döndürülen sonucu tam olarak içerebilen sınırlayıcı kutuyu depolar. Bu sınırların, önerilen görüntü alanıyla eşleşmeyebileceğini unutmayın. (Örneğin San Francisco, teknik olarak şehrin bir parçası olan, ancak 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 kodlanmış konum referansıdır. Enlem ve boylam koordinatlarından türetilen ve bir derecenin 1/8.000'i 1/8.000'e kadar (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, 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 veya daha uzun bir yerel koddur (849VCWC8+R9).
  • compound_code, konum bilgisi (CWC8+R9, Mountain View, CA, ABD) olan, 6 karakter veya daha uzun bir yerel koddur. 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 istenen adresin bir kısmını eşleştirebildiği halde orijinal istek için tam eşleşme döndürmediğini belirtir. Orijinal istekte yazım yanlışı ve/veya eksik adres olup olmadığını inceleyebilirsiniz.

  Kısmi eşleşmeler çoğunlukla istekte geçirdiğiniz konum içinde bulunmayan açık adresler için meydana gelir. 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, "Atatürk Caddesi, İzmir, Türkiye" hem Henry Street hem de Henrietta Caddesi için kısmi bir 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ı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ı öğrenmek için Places API isteğindeki 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. Bina numarası veya ülke ö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, hem adres türü hem de adres bileşeni türü dizilerinde coğrafi kodlayıcı tarafından desteklenir ve 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 yolun yer aldığı ana kavşağı gösterir.
• political, siyasi bir tüzel kişiyi belirtir. Bu tür, genellikle bir sivil yönetim poligonu anlamına gelir.
• 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 birinci dereceden sivil tüzel kişiyi belirtir. Amerika Birleşik Devletleri'nde bu idari düzeyler eyaletlerdir. Tüm uluslar bu idari seviyeleri göstermez. Çoğu durumda idari_area_seviye_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ında ikinci dereceden bir 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ında üçüncü dereceden bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil çatışma olduğunu 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 bir sivil çatışma olduğunu gösterir. Tüm uluslar bu idari seviyeleri göstermez.
• administrative_area_level_5, ülke düzeyinin altında beşinci dereceden bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil çatışma olduğunu gösterir. Tüm uluslar bu idari seviyeleri göstermez.
• administrative_area_level_6, ülke düzeyinin altında altıncı dereceden bir sivil tüzel kişiyi belirtir. Bu tür, küçük bir sivil çatışma olduğunu 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 bir sivil çatışma olduğunu gösterir. Tüm uluslar bu idari seviyeleri göstermez.
• colloquial_area, varlık için yaygın olarak kullanılan alternatif bir adı belirtir.
• locality, anonim bir şehir veya kasaba siyasi tüzel kişiliğini belirtir.
• sublocality, bir konum altındaki birinci dereceden sivil tüzel kişiyi belirtir. Bazı konumlar için ek türlerden biri gönderilebilir: sublocality_level_1 - sublocality_level_5. Her bir alt konum düzeyi sivil tüzel kişidir. Daha büyük sayılar, daha küçük bir coğrafi alanı belirtir.
• neighborhood, adlandırılmış bir mahalleyi gösterir
• premise, adlandırılmış bir konumu belirtir. Bu genellikle ortak ada sahip bir bina veya bina koleksiyonudur
• subpremise, adlandırılmış bir konumun altındaki birinci derece varlığı ifade eder. Bu, genellikle ortak bir ada sahip bir grup bina içindeki tek bir binadır.
• plus_code, enlem ve boylamdan türetilen kodlanmış bir konum referansını gösterir. Artı kodları, bulunmadığı yerlerde (bina numaralandırılmamış veya sokakların adlandırılmadığı) açık adreslerin yerine kullanılabilir. Ayrıntılı bilgi için https://plus.codes sayfasına bakın.
• postal_code, ülkedeki posta kodunu göndermek için kullanılan bir posta kodunu belirtir.
• natural_feature, belirgin bir doğal özelliği belirtir.
• airport bir havaalanını gösterir.
• park, adlandırılmış bir parkı gösterir.
• 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 (örneğin, Fransa'daki Lieu-dit).

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

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

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

Coğrafi Kodlama isteğinde, Coğrafi Kodlama hizmetine belirli bir görüntü alanı (sınırlayıcı kutu olarak ifade edilir) içindeki sonuçları tercih etmesi talimatını verebilirsiniz. Bunu, 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ğusunda bir sınır kutucuğu 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 verilen sonuçlar döndürmesi talimatını 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ık'ı" için kullanılır).

Coğrafi kodlama sonuçları, ana Google Haritalar uygulamasının resmi olarak kullanıma sunulduğu her alan için ağırlıklandırılabilir. 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 onlar da dahil edilebilir.

Örneğin, Coğrafi Kodlama API'sinin varsayılan alanı ABD olarak ayarlandığından, "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) ile yapılan "Toledo" için 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 sınırlı adres sonuçları döndürebilir. Kısıtlamayı, components filtresini kullanarak belirtebilirsiniz. Filtre, dikey çizgi (|) ile ayrılmış component:value çiftlerini içeren 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 filtresi için 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 ş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şiyor.

Bileşen filtreleme hakkında notlar:

• Bu bileşen filtrelerini isteklerde tekrarlamayın. Aksi takdirde API, Invalid_request değerini döndürür: country, postal_code, route
• İstek yinelenen bileşen filtreleri içeriyorsa API bu filtreleri VEYA değil, VE olarak değerlendirir.
• Sonuçlar Google Haritalar ile tutarlıdır ve bazen beklenmedik ZERO_RESULTS yanıtları verir. Otomatik Yer Tamamlama'yı kullanmak bazı kullanım durumlarında daha iyi sonuçlar sağlayabilir. Daha fazla bilgi için bu SSS bölümüne bakı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 ile sonuçlanabilir.

"High St, Hastings" için components=country:GB kodlu bir coğrafi kod, Hastings-On-Hudson, ABD'deki değil Hastings, İngiltere'deki bir sonucu 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"
}

"Santa Cruz" bölgesi için components=country:ES ile yapılan 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 adresin coğrafi kodlaması yapılırken, 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"
}