Bir konumun coğrafi kodunu tersine çevirme

Avrupa Ekonomik Alanı (AEA) geliştiricileri

Tersine coğrafi kodlama, harita konumunu okunabilir bir adrese dönüştürür. 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 ayrıntılı sokak adresinden mahalleler, şehirler, ilçeler ve eyaletler gibi daha az ayrıntılı siyasi birimlere kadar farklı adres türleri döndürür. En doğru adres genellikle ilk sonuçtur. Belirli bir adres türünü eşleştirmek istiyorsanız types parametresini kullanın.

Tersine coğrafi kodlama isteği

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

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

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

https://geocode.googleapis.com/v4beta/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/v4beta/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/v4beta/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/v4beta/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 uç noktalarıyla kullanılır.
  • 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 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.

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.

    Ters coğrafi kodlayıcı, results dizisinde birden fazla sonuç döndürüyor. 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 kodlandığında, coğrafi olarak kodlanan nokta sokak adresi, şehir (Chicago), eyalet (Illinois) veya ülke (ABD) olarak belirtilebilir. Tümü coğrafi kodlayıcı için "adres" olarak kabul edilir. 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 Artı Kodu içerir. Çözülen artı kodu ile istek noktası arasındaki mesafe 10 metreden azdır.

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 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.

  • 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/v4beta/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ü. 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ı 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/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

    Aşağıdaki değerler desteklenir:

    Adres türleri ve adres bileşeni türleri

    Yanıtın GeocodeResult gövdesindeki types dizisi, adres türünü belirtir. Adres türlerine örnek olarak açık adres, ülke veya siyasi birim verilebilir. GeocodeResult gövdesinin AddressComponents alanındaki types dizisi, adresin her bir bölümünün türünü belirtir. Örneğin, bina numarası veya ülke.

    Adresler birden fazla türde olabilir. Türler "etiket" olarak kabul edilebilir. Örneğin, birçok şehir political ve locality türleriyle etiketlenir.

    Aşağıdaki türler desteklenir ve hem adres türü hem de adres bileşeni türü dizilerinde döndürülür:

    Adres Türü Açıklama
    street_address Açık adres.
    route Adlandırılmış bir rota (ör. "US 101").
    intersection Genellikle iki ana yolun kesiştiği büyük bir kavşak.
    political Siyasi bir tüzel kişilik Genellikle bu tür, bir idari birimin poligonunu gösterir.
    country Ulusal siyasi varlık ve genellikle Coğrafi Kodlayıcı tarafından döndürülen en yüksek sıralı türdür.
    administrative_area_level_1 Ülke düzeyinin altındaki birinci dereceden idari bölge. Amerika Birleşik Devletleri'nde bu idari düzeyler eyaletlerdir. Bu idari düzeyler bazı ülkelerde kullanılmaz. Çoğu durumda, administrative_area_level_1 kısa adları ISO 3166-2 alt bölümleri ve yaygın olarak kullanı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 durum garanti edilmez.
    administrative_area_level_2 Ülke düzeyinin altındaki ikinci dereceden idari bölge. Amerika Birleşik Devletleri'nde bu idari düzeyler ilçelerdir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    administrative_area_level_3 Ülke düzeyinin altındaki üçüncü düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    administrative_area_level_4 Ülke düzeyinin altındaki dördüncü düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    administrative_area_level_5 Ülke düzeyinin altındaki beşinci düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    administrative_area_level_6 Ülke düzeyinin altındaki altıncı düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    administrative_area_level_7 Ülke düzeyinin altındaki yedinci düzey idari bölge. Bu tür, küçük bir idari bölgeyi gösterir. Bu idari düzeyler bazı ülkelerde kullanılmaz.
    colloquial_area Tüzel kişi için yaygın olarak kullanılan alternatif bir ad.
    locality Tüzel kişiliğe sahip bir şehir veya kasaba siyasi tüzel kişiliği.
    sublocality Bir yerleşim biriminin altındaki birinci dereceden idari bölge. Bazı konumlar için sublocality_level_1 ile sublocality_level_5 arasındaki ek türlerden biri gösterilebilir. Her alt yerleşim birimi düzeyi, sivil bir varlıktır. Daha büyük sayılar, daha küçük bir coğrafi alanı gösterir.
    neighborhood Adlandırılmış bir mahalle.
    premise Adlandırılmış bir konumdur. Genellikle ortak bir adı olan bir bina veya binalar topluluğudur.
    subpremise Tesis düzeyinin altında bulunan, adreslenebilir bir öğe (ör. apartman, birim veya süit).
    plus_code Enlem ve boylamdan elde edilen, kodlanmış bir konum referansı. Plus code'lar, sokak adreslerinin olmadığı yerlerde (binaların numaralandırılmadığı veya sokakların adlandırılmadığı yerler) sokak adreslerinin yerine kullanılabilir. Ayrıntılar için https://plus.codes adresini ziyaret edin.
    postal_code Ülke içinde posta göndermek için kullanılan posta kodu.
    natural_feature Belirgin bir doğal alan.
    airport Havalimanı
    park Adlandırılmış bir park.
    point_of_interest Adlandırılmış bir önemli yer. Genellikle bu "önemli yerler", "Empire State Binası" veya "Eyfel Kulesi" gibi başka bir kategoriye kolayca uymayan, öne çıkan yerel varlıklardır.

    Boş bir tür listesi, belirli adres bileşeni için bilinen bir tür olmadığını gösterir (örneğin, Fransa'da Lieu-dit).