Bir konumun coğrafi kodunu tersine çevirme

Avrupa Ekonomik Alanı'ndaki (AEA) geliştiriciler

Tersine coğrafi kodlama, haritadaki bir konumu kullanıcı tarafından okunabilir bir adrese dönüştürür. Harita konumunu, konumun enlem ve boylam koordinatlarıyla temsil edersiniz.

Bir konumu tersine coğrafi kodladığınızda yanıt şunları içerir:

Bu API, en spesifik açık adresten mahalle, şehir, ilçe ve eyalet gibi daha az spesifik idari birimlere 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ştirmek istiyorsanız types parametresini kullanın.

Tersine coğrafi kodlama isteği

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

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

Veya sorgu parametreleriyle temsil edilen yapılandırılmış enlem ve boylam koordinatları kümesi olarak:

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

Yapılandırılmış biçimi genellikle bir HTML formunda yakalanan konum bileşenlerini işlerken kullanırsınız.

Diğer tüm parametreleri URL parametresi olarak veya API anahtarı ya da alan maskesi gibi parametreler için 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ış konum iletme

LatLng türündeki location sorgu parametresini kullanarak yapılandırılmış konumu belirtin. 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'u kullanma

Geocoding API v4, kimlik doğrulama için OAuth 2.0'ı destekler. Geocoding API ile OAuth 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ın.
  • 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şim sağlayan 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 GeocodeResult nesnelerinin results dizisi.

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

    1. GeocodeResult.types: Bu dizi, sonucun genel türlerini gösterir. Olası değerler, Places API tarafından kullanılan yer türlerinden alınır. Daha fazla bilgi için Yer türleri Tablo A ve B'ye bakın.
    2. GeocodeResult.addressComponents[].types: Her adres bileşeninde, adresin ilgili bölümünün türünü belirten bir types dizisi bulunur. Bu değerler, Places API tarafından kullanılan Adres türleri ve adres bileşeni türleri tablosundan alınır.

    Tersine coğrafi kodlayıcı, results dizisinde birden fazla sonuç döndürür. Sonuçlar yalnızca posta adresleri değil, bir konumu coğrafi olarak adlandırmanın herhangi bir yoludur. Örneğin, Chicago şehrindeki bir nokta coğrafi olarak kodlanırken coğrafi olarak kodlanmış nokta açık adres, şehir (Chicago), eyalet (Illinois) veya ülke (ABD) olarak gösterilebilir. Bunların hepsi coğrafi kodlayıcı için "adres"tir. Tersine coğrafi kodlayıcı, bu türlerden herhangi birini geçerli sonuç olarak döndürür.

  • PlusCode türündeki plusCode alanı, istekteki enlem ve boylama en yakın Plus Code'u içerir. Ayrıca results dizisinin her öğesi bir Plus Code içerir. Kodu çözülen Plus Code ile istek noktası arasındaki mesafe 10 metreden azdır.

    Not: API her zaman Plus Code döndürmez.

JSON nesnesinin tamamı ş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, 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ğinden bu liste kapsamlı olmayabilir.
    • languageCode sağlanmazsa API, varsayılan olarak konumun yerel dilini ve alfabesini 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 okunabilen bir açık adres sağlamak için elinden geleni yapar. Bu amaca ulaşmak için açık adresleri yerel dilde döndürür ve gerekirse tercih edilen dili dikkate alarak kullanıcı tarafından okunabilir bir alfabeye dönüştü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 dilde döndürülür.
    • Tercih edilen dilde bir 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 göre 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ı kelimeler buna dahildir.

  • regionCode

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

    Bir adresi coğrafi olarak kodlarken (ileri coğrafi kodlama) bu parametre, hizmetten gelen sonuçları belirtilen bölgeyle sınırlayabilir ancak tamamen kısıtlamaz. Bir konumun veya yerin coğrafi kodlaması, tersine coğrafi kodlama ya da yer coğrafi kodlaması yapılırken bu parametre, adresi biçimlendirmek için kullanılabilir. Bu parametre, geçerli yasaya bağlı olarak her durumda sonuçları etkileyebilir.

  • öğe kapsamı seviyesi

    Granularity tarafından tanımlanan, 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ı düzeyleriyle kısıtlamaz. Bunun yerine granularity, arama sonrası filtre görevi 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ı siler.

    Hem types hem de granularity parametrelerini 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 kısıtlamaz. Bunun yerine types, arama sonrası filtre görevi görür. API, belirtilen konum için tüm sonuçları getirir ve ardından belirtilen adres türleriyle eşleşmeyen sonuçları siler.

    Hem types hem de granularity parametrelerini 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ıtta döndürülecek alanları belirtmek için bir yanıt alanı maskesi oluşturun. Yanıt alanı maskesini, $fields veya fields URL parametresini ya da X-Goog-FieldMask HTTP üstbilgisini 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ünü inceleyin.