Adresi coğrafi kodlama

Avrupa Ekonomik Alanı (AEA) geliştiricileri

Coğrafi kodlama, bir adresi haritadaki bir konuma çevirir. Bir adrese coğrafi kodlama uyguladığınızda yanıtta şunlar yer alır:

  • Konumun yer kimliği
  • Konumun enlem ve boylam koordinatları
  • Konumun Plus Code'u
  • Genişletilmiş adres ayrıntıları

Coğrafi kod isteği

Bir coğrafi kod isteği, HTTP GET isteğidir. Adresi yapılandırılmamış bir dize olarak belirtebilirsiniz:

https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING

Alternatif olarak, sorgu parametreleriyle gösterilen yapılandırılmış bir adres bileşenleri grubu olarak da kullanılabilir:

https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS

Genellikle bir HTML formunda yakalanan adres bileşenlerini işlerken yapılandırılmış biçimi kullanırsınız.

Diğer tüm parametreleri URL parametreleri olarak veya API anahtarı ve alan maskesi gibi parametreleri GET isteğinin bir parçası olarak başlıklarda iletin.

Yapılandırılmamış bir adres dizesi iletme

Yapılandırılmamış adres, dize veya Plus Code olarak biçimlendirilmiş bir adrestir. Örneğin, aşağıdaki örnekte URL kodlu adres dizesi "1600 Amphitheatre Parkway, Mountain View, CA" iletilir:

https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

URL'deki "+" karakterinin boşluğa dönüştürüldüğünü unutmayın.

İsteği bir curl komutu kullanarak da yapabilirsiniz:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Adresler birçok özel karakter türü içerebilir. Örneğin, "7/1 King St, Concord West" ifadesindeki gibi "/". "/" karakterini %2F olarak URL kodlayın:

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

Diğer bir yaygın örnek ise "#" karakteridir. Örneğin, "9500 W Bryn Mawr Ave #650, Rosemont". "#" karakterini %2FE olarak URL kodlayın:

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

Sonraki örnekte, düzensiz bir adres dizesini Plus Kodu 849VCWC8+R4 olarak belirtiyorsunuz. "+" karakterini %2B olarak URL kodladığınızdan emin olun:

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

Yapılandırılmış adres iletme

address sorgu parametresini kullanarak yapılandırılmış bir adres belirtin. Bu parametrenin türü PostalAddress olmalıdır. PostalAddress nesnesi, istekteki adres bileşenlerinin bir kısmını veya tamamını ayrı sorgu parametreleri olarak belirtmenize olanak tanır.

Örneğin, kullandığınız adresin yalnızca posta kodunu belirtmek için PostalAddress.postalCode:

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

Bir HTML formunda yakalanan adres bileşenleri gibi birden çok adres bileşenini belirtmek için birden çok sorgu parametresi kullanın:

https://geocode.googleapis.com/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

İstek göndermek için OAuth kullanma

Geocoding API v4, kimlik doğrulama için OAuth 2.0'ı destekler. Coğrafi Kodlama API'si ile OAuth'u kullanmak için OAuth jetonuna doğru kapsam atanmalıdır. Geocoding API, ileri coğrafi kodlama ile kullanılmak üzere aşağıdaki kapsamları destekler:

  • https://www.googleapis.com/auth/maps-platform.geocode — Tüm Geocoding API uç noktalarıyla kullanılır.
  • https://www.googleapis.com/auth/maps-platform.geocode.address — Yalnızca ileri coğrafi kodlama için GeocodeAddress ile birlikte kullanın.

Ayrıca, tüm Geocoding API uç noktaları için genel https://www.googleapis.com/auth/cloud-platform kapsamını kullanabilirsiniz. Bu kapsam, tüm uç noktalara erişime izin veren genel bir kapsam olduğundan geliştirme sırasında kullanışlıdır ancak üretimde kullanışlı değildir.

Daha fazla bilgi ve örnek için OAuth'u kullanma başlıklı makaleyi inceleyin.

Coğrafi kod yanıtı

Coğrafi kodlama, GeocodeResult nesnelerinin results dizisini içeren bir GeocodeAddressResponse nesnesi döndürür. Her GeocodeResult nesnesi tek bir yeri temsil eder.

Tam JSON nesnesi şu biçimdedir:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

Gerekli parametreler

  • address — Coğrafi kodunu almak istediğiniz cadde adresi veya Artı Kodu. Adresleri, ilgili ülkenin ulusal posta hizmetinin kullandığı biçime göre belirtin. İşletme adları ve birim, daire veya kat numaraları gibi ek adres öğelerinden kaçınılmalıdır. Açık adres öğeleri boşluklarla sınırlandırılmalı ve %20 olarak URL kodlamalı olmalıdır. Örneğin, "24 Sussex Drive Ottawa ON" adresini şu şekilde iletin: 
    24%20Sussex%20Drive%20Ottawa%20ON
     Plus kodlarını aşağıda gösterildiği gibi biçimlendirin. Artı işaretleri %2B olarak URL biçiminde kodlanır. Boşluklar ise %20 olarak URL biçiminde kodlanır:
    • Global kod, 4 karakterlik bir alan kodu ve 6 karakter veya daha uzun bir yerel koddur. Örneğin, "849VCWC8+R9" ifadesini 849VCWC8%2BR9 olarak kodlayın.
    • Bileşik kod, açık bir konuma sahip 6 karakterli veya daha uzun bir yerel koddur. Örneğin, "CWC8+R9 Mountain View, CA, ABD"yi CWC8%2BR9%20Mountain%20View%20CA%20USA olarak kodlayın.

İsteğe bağlı parametreler

  • locationBias

    Arama yapılacak alanı Viewport olarak belirtir. Bu konum, sonuçların belirtilen konumun çevresinde döndürülebileceği anlamına gelen bir önyargı olarak işlev görür. Bu sonuçlar, alanın yakınında ancak dışında olan sonuçları da içerir.

    Bölgeyi dikdörtgen görüntü alanı olarak belirtin. Dikdörtgen, iki çapraz olarak zıt düşük ve yüksek nokta şeklinde gösterilen bir enlem-boylam görüntü alanıdır. Düşük nokta, dikdörtgenin güneybatı köşesini, yüksek nokta ise dikdörtgenin kuzeydoğu köşesini gösterir.

    Görüntü alanı, sınırını da içeren kapalı bir bölge olarak kabul edilir. Enlem sınırları -90 ile 90 derece arasında (bu değerler dahil), boylam sınırları ise -180 ile 180 derece arasında (bu değerler dahil) olmalıdır:

    • low = high ise görüntü alanı tek bir noktadan oluşur.
    • low.longitude > high.longitude ise boylam aralığı ters çevrilir (görüntü alanı 180 derece boylam çizgisini geçer).
    • low.longitude = -180 derece ve high.longitude = 180 derece ise görüntü alanı tüm boylamları içerir.
    • low.longitude = 180 derece ve high.longitude = -180 derece ise boylam aralığı boş olur.
    • low.latitude > high.latitude ise enlem aralığı boş olur.

    Hem düşük hem de yüksek değerler doldurulmalı ve gösterilen kutu boş olmamalıdır. Boş bir görünüm alanı hataya neden olur.

    Örneğin, bu sorgu dizesi New York şehrini tamamen içine alan bir görünüm alanı tanımlar:

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • languageCode

    Sonuçların döndürüleceği dil.

    • Desteklenen dillerin listesini inceleyin. Google, desteklenen dilleri sık sık güncellediği için bu liste kapsamlı olmayabilir.
    • languageCode sağlanmazsa API varsayılan olarak en değerini kullanır. Geçersiz bir dil kodu belirtirseniz API INVALID_ARGUMENT hatası döndürür.
    • API, hem kullanıcı hem de yerel halk tarafından okunabilir bir açık adres sağlamak için elinden geleni yapar. Bu hedefi gerçekleştirmek için tercih edilen dili dikkate alarak gerekirse kullanıcının okuyabileceği bir alfabeye çevrilmiş, yerel dildeki sokak adreslerini döndürür. Diğer tüm adresler tercih edilen dilde döndürülür. Adres bileşenlerinin tümü aynı dilde döndürülür. Bu dil, ilk bileşenden seçilir.
    • Tercih edilen dilde ad yoksa API en yakın eşleşmeyi kullanır.
    • Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç kümesi ve bu sonuçların döndürülme sırası üzerinde küçük bir etkiye sahiptir. Coğrafi kodlayıcı, kısaltmaları dile bağlı olarak farklı şekilde yorumlar. Örneğin, sokak türlerinin kısaltmaları veya bir dilde geçerli olup başka bir dilde geçerli olmayan eş anlamlılar.

  • regionCode

    Bölge kodu, iki karakterli CLDR kodu değeri olarak. Varsayılan değer yoktur. Çoğu CLDR kodu, ISO 3166-1 kodlarıyla aynıdır.

    Bir adresin coğrafi kodlaması yapılırken (ileri coğrafi kodlama) bu parametre, hizmetten gelen sonuçları belirtilen bölgeyle sınırlayabilir ancak tamamen kısıtlayamaz. Bir konum veya yer coğrafi olarak kodlanırken (tersine coğrafi kodlama veya yer coğrafi kodlama), bu parametre adresi biçimlendirmek için kullanılabilir. Bu parametre, her durumda geçerli yasaya göre sonuçları etkileyebilir.

Konum önyargısı

Coğrafi kodlama hizmetine, belirli bir görünüm alanındaki (sınırlayıcı kutu olarak ifade edilir) sonuçları tercih etmesi talimatını vermek için locationBias parametresini kullanın. locationBias parametresi, bu sınırlayıcı kutunun güneybatı ve kuzeydoğu köşelerinin enlem/boylam koordinatlarını tanımlar.

Örneğin, "Washington" adresi için yapılan bir coğrafi kod isteği, Washington, D.C. ve ABD'nin Washington eyaletiyle ilgili sonuçlar döndürebilir:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?key=API_KEY

Yanıt şu biçimdedir:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

Ancak ABD'nin kuzeydoğu kısmında sınırlayıcı kutu tanımlayan bir locationBias parametresi eklemek, bu coğrafi kodun yalnızca Washington, D.C. şehrini döndürmesine neden olur:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

Bölgeye ağırlık verme

Bir coğrafi kodlama isteğinde, regionCode parametresini kullanarak Coğrafi Kodlama hizmetine belirli bir bölgeye yönelik sonuçlar döndürmesi talimatını verebilirsiniz. Bu parametre, bölgesel önyargıyı belirten iki karakterli CLDR kodu değerini alır. Çoğu CLDR kodu ISO 3166-1 kodlarıyla aynıdır.

regionCode için varsayılan değer yoktur. Örneğin, "Toledo" için bir coğrafi kod, ABD ve İspanya ile ilgili sonuçlar döndürür:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?key=API_KEY

Yanıt:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

Yalnızca regionCode=es (İspanya) ile "Toledo" için yapılan bir coğrafi kodlama isteği yalnızca İspanya'dan sonuç döndürür:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY