Bir konumun coğrafi kodunu tersine çevirme

Avrupa Ekonomik Alanı (AEA) geliştiricileri

Tersine coğrafi kodlama, haritadaki bir konumu okunabilir bir adrese dönüştürür. Harita konumunu, konumun enlem ve boylam koordinatlarıyla gösterirsiniz.

Bir konumun tersine coğrafi kodlamasını yaptığı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şmek 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

Sorgu parametreleriyle temsil edilen yapılandırılmış 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 parametreler için GET isteğinin bir parçası olarak üstbilgilerde 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

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'u 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, ters coğrafi kodlamayla 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ş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.

Ters 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 nesneleri dizisi. GeocodeResult

    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 başlıklı makaleyi inceleyin.
    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 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. Bunların hepsi coğrafi kodlayıcı için "adres"tir. 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 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 Kodları 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ği için bu liste eksik olabilir.
    • languageCode sağlanmazsa API, varsayılan olarak konumun yerel dilini ve komut dosyasını 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 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 kodlanırken (ters coğrafi kodlama veya yer coğrafi kodlama) bu parametre, adresin biçimlendirilmesi 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 kısıtlamaz. Bunun yerine granularity, arama sonrası filtre görevi görür. API, belirtilen location için tüm sonuçları getirir ve 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 değerini 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 yanıt alan maskesi oluşturun. 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, yanıtın yalnızca 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.