Bir konumun coğrafi kodunu tersine çevirme

Avrupa Ekonomik Alanı (AEA) geliştiricileri

Tersine coğrafi kodlama, harita konumunu okunabilir bir adrese çevirir. Harita konumunu, konumun enlem ve boylam koordinatlarıyla gösterirsiniz.

Bir konumu tersine coğrafi kodladığınızda yanıtta şunlar yer alır:

Bu API, en spesifik sokak adresinden daha az spesifik siyasi varlıklara (ör. mahalleler, şehirler, ilçeler ve eyaletler) kadar farklı adres türleri döndürür. En doğru adres genellikle ilk sonuçtur. Belirli bir adres türüyle eşleşmek istiyorsanız types parametresini kullanın.

Tersine coğrafi kodlama isteği

Ters coğrafi kodlama isteği bir HTTP GET isteğidir. Konumu yapılandırılmamış bir dize olarak belirtebilirsiniz:

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

Alternatif olarak, sorgu parametreleriyle gösterilen yapılandırılmış bir enlem ve boylam koordinatları kümesi olarak da iletebilirsiniz:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

Genellikle bir HTML formunda yakalanan konum 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ı ya da alan maskesi gibi parametreleri GET isteğinin bir parçası olarak başlıklarda iletin. Örneğin:

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

Yapılandırılmamış konum, enlem ve boylam koordinatlarının virgülle ayrılmış dizesi olarak biçimlendirilmiş bir konumdur:

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=API_KEY

Alternatif olarak bir curl komutunda:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

Yapılandırılmış bir konum iletme

location sorgu parametresini kullanarak yapılandırılmış konumu belirtin. Bu parametrenin türü LatLng olmalıdır. LatLng nesnesi, enlem ve boylamı ayrı sorgu parametreleri olarak belirtmenize olanak tanır:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&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, tersine coğrafi kodlama ile kullanılmak üzere aşağıdaki kapsamları destekler:

  • https://www.googleapis.com/auth/maps-platform.geocode — Tüm Geocoding API yöntemleriyle kullanılabilir.
  • https://www.googleapis.com/auth/maps-platform.geocode.location — Tersine coğrafi kodlama için yalnızca GeocodeLocation ile kullanın.

Ayrıca, tüm Geocoding API yöntemleri için genel https://www.googleapis.com/auth/cloud-platform kapsamını kullanabilirsiniz. Bu kapsam, tüm yöntemlere 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.

Tersine coğrafi kodlama yanıtı

Tersine coğrafi kodlama, aşağıdakileri içeren bir GeocodeLocationResponse nesnesi döndürür:

  • Yeri temsil eden results dizisi. GeocodeResult nesneleri.

    Geocoding API yanıtları, GeocodeResult içinde iki ana yerde types dizilerini içerir:

    1. GeocodeResult.types: Bu dizi, sonucun genel türlerini gösterir. Olası değerler, Yer Türleri (Yeni) sayfasındaki Tablo A ve Tablo B'den alınır.
    2. GeocodeResult.addressComponents[].types: Her adres bileşeninde, adresin söz konusu bölümünün türünü belirten bir types dizisi bulunur. Bu değerler, Yer Türleri (Yeni) sayfasındaki Adres türleri ve adres bileşeni türleri tablosundan alınır.

    Ters coğrafi kodlayıcı, results dizisinde birden fazla sonuç döndürüyor. Sonuçlar yalnızca posta adresleri değil, bir konuma coğrafi olarak ad vermenin herhangi bir yolunu içerir. Örneğin, Chicago şehrindeki bir nokta coğrafi olarak kodlandığında, coğrafi olarak kodlanan nokta sokak adresi, şehir (Chicago), eyalet (Illinois) veya ülke (ABD) olarak belirtilebilir. Tümü coğrafi kodlayıcıya "adres" olarak gönderilir. Ters coğrafi kod çözücü, bu türlerden herhangi birini geçerli sonuç olarak döndürür.

  • PlusCode türündeki plusCode alanı, istekteki enlem ve boylamı en iyi şekilde yaklaştıran artı kodunu içerir. Ayrıca, results dizisinin her öğesi bir artı kodu içerir. Çözümlenen artı kodu ile istek noktası arasındaki mesafe 10 metrenin altındadır.

    Not: API, Plus Code'ları her zaman döndürmez.

Tam JSON nesnesi şu biçimdedir:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

Gerekli parametreler

  • konum

    En yakın ve okunabilir adresi istediğiniz yeri belirten enlem ve boylam koordinatları.

İsteğe bağlı parametreler

  • 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 amaca ulaşmak 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.
    • Bir ad tercih edilen dilde kullanılamıyorsa 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, hizmetin sonuçlarını 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.

  • ayrıntı düzeyi

    Granularity tarafından tanımlandığı şekilde ayrı sorgu parametreleri olarak belirtilen bir veya daha fazla konum ayrıntı düzeyi. Birden fazla granularity parametresi belirtirseniz API, ayrıntı düzeylerinden herhangi biriyle eşleşen tüm adresleri döndürür.

    granularity parametresi, aramayı belirtilen konum ayrıntılarıyla sınırlandırmaz. Bunun yerine, granularity arama sonrası filtre olarak işlev görür. API, belirtilen location için tüm sonuçları getirir, ardından belirtilen konum ayrıntı düzeyleriyle eşleşmeyen sonuçları atar.

    Hem types hem de granularity öğesini belirtirseniz API yalnızca her ikisiyle de eşleşen sonuçları döndürür. Örneğin:

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • türler

    Ayrı sorgu parametreleri olarak belirtilen bir veya daha fazla adres türü. Olası değerler, Yer Türleri (Yeni) sayfasındaki Adres türleri ve adres bileşeni türleri tablosundan alınır. Birden fazla types parametresi belirtirseniz API, türlerden herhangi biriyle eşleşen tüm adresleri döndürür.

    types parametresi, aramayı belirtilen adres türleriyle sınırlandırmaz. Bunun yerine, types arama sonrası filtre olarak işlev görür. API, belirtilen konumla ilgili tüm sonuçları getirir ve ardından belirtilen adres türleriyle eşleşmeyen sonuçları siler.

    Hem types hem de granularity öğesini belirtirseniz API yalnızca her ikisiyle de eşleşen sonuçları döndürür. Örneğin:

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • FieldMask

    Yanıt alan maskesi oluşturarak yanıtta döndürülecek alanları belirtin. Yanıt alan maskesini, $fields veya fields URL parametresini ya da X-Goog-FieldMask HTTP üst bilgisini kullanarak yönteme iletin. Örneğin, aşağıdaki istek yalnızca yanıtın placeID alanlarını döndürür.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    Yanıt: 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

    Daha fazla bilgi için Döndürülecek alanları seçme bölümüne bakın.