Yer kimlikleri

Platform seçin: Android iOS JavaScript Web Hizmeti

Yer kimlikleri, Google Rehber veritabanında ve Google Haritalar'da bir yeri benzersiz şekilde tanımlar. Yer kimlikleri, aşağıdaki Haritalar API'lerine yapılan isteklerde kabul edilir:

  • Geocoding API web hizmeti ve Coğrafi Kodlama Hizmeti, Maps JavaScript API'de bir Yer Kimliği için adres alma.
  • Routes API Directions API web hizmeti ve Directions Service'teki Maps JavaScript API'de başlangıç, hedef ve ara ara noktaları belirtme.
  • Routes API ve DISTANCE Matris API web hizmeti ile Mesafe Matrisi Hizmeti ve Maps JavaScript API'de kalkış noktalarının ve varış noktalarının belirlenmesi.
  • Places API web hizmetinde, Android için Yerler SDK'sı, iOS için Yerler SDK'sı ve Yerler Kitaplığı'nda Yer Ayrıntılarını alma.
  • Maps Embed API'de Yer Kimliği parametrelerini kullanma.
  • Haritalar URL'lerindeki arama sorguları alınıyor.
  • Roads API'de hız sınırları gösteriliyor.
  • Sınırlar için veriye dayalı stil oluşturma amacıyla sınır poligonlarını bulma ve stil özelliklerini ayarlama.

Belirli bir yerin kimliğini bulma

Belirli bir yerin yer kimliğini mi arıyorsunuz? Bir yeri aramak ve kimliğini öğrenmek için aşağıdaki yer kimliği bulucuyu kullanın:

Alternatif olarak, Maps JavaScript API dokümanlarındaki kodla birlikte yer kimliği bulucuyu görüntüleyebilirsiniz.

Genel bakış

Yer kimliği, bir yeri benzersiz şekilde tanımlayan metinsel bir tanımlayıcıdır. Tanımlayıcının uzunluğu değişebilir (Yer Kimlikleri için maksimum uzunluk yoktur). Örnekler:

  • ChIJgUbEo8cfqokR5lP9_Wh_DaM
  • GhIJQWDl0CIeQUARxks3icF8U8A
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
  • IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

Yer kimlikleri işletmeler, önemli noktalar, parklar ve kavşaklar dahil çoğu konumda kullanılabilir. Aynı yer veya konum, birden fazla farklı yer kimliğine sahip olabilir. Yer kimlikleri zaman içinde değişebilir.

Aynı yer kimliğini Places API'de ve çeşitli Google Haritalar Platformu API'lerinde kullanabilirsiniz. Örneğin, Places API, Haritalar JavaScript API, Geocoding API, Haritalar Embed API ve Roads API'de bir yere referans vermek için aynı yer kimliğini kullanabilirsiniz.

Yer kimliğini kullanarak yer ayrıntılarını alın

Yer kimliklerini kullanmanın yaygın bir yolu, bir yeri aramaktır (örneğin, Maps JavaScript API'de Places API'yi veya Yerler kitaplığını kullanarak), ardından yer ayrıntılarını almak için döndürülen yer kimliğini kullanmaktır. Yer kimliğini depolayabilir ve daha sonra aynı yer ayrıntılarını almak için kullanabilirsiniz. Aşağıdaki yer kimliklerini kaydetme bölümünü okuyun.

Aşağıdaki örneklerde, Places API (Yeni) ve Places API için simge URL'sinin nasıl isteneceği gösterilmektedir.

Places API (Yeni)

Places API'yi kullanarak, bir Text Search (Yeni) isteği yaparak yer kimliğini bulabilirsiniz.

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Yanıtın id alanında aşağıda gösterildiği gibi bir yer kimliği bulunur:

{
  "places": [
    {
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
  ...
}

Artık yer kimliğini istek URL'sine ekleyerek bir Yer Ayrıntıları (Yeni) isteğinde bulunabilirsiniz:

https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY

Places API

Places API'yi kullanarak, bir Yer Arama isteği yaparak bir yer kimliğini bulabilirsiniz.

Aşağıdaki örnek, Avustralya'nın Sidney şehrindeki bir noktanın 1.500 m yarıçapında yer alan ve "gemi seyahati" kelimesini içeren "restoran" türündeki yerlere yönelik bir arama isteğidir:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

Yanıtın place_id alanında, aşağıdaki snippet'te gösterildiği gibi bir yer kimliği bulunur:

{
  "html_attributions" : [],
  "results" : [
    {
      "geometry" : {
        "location" : {
          "lat" : -33.870775,
          "lng" : 151.199025
        }
      },
      ...
      "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
      ...
    }
  ],
  "status" : "OK"
}

Artık yer kimliğini place_id parametresine ekleyerek bir Yer Ayrıntıları isteği gönderebilirsiniz:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEY

Daha sonra kullanmak üzere yer kimliklerini kaydedin

Yer kimlikleri, Google Haritalar Platformu Hizmet Şartları'ndaki Bölüm 3.2.3(b)'de belirtilen önbelleğe alma kısıtlamalarından muaftır. Bu nedenle, yer kimliği değerlerini daha sonra kullanmak üzere saklayabilirsiniz.

Depolanan yer kimliklerini yenileme

12 aydan eski yer kimliklerini yenilemenizi öneririz. fields parametresinde yalnızca yer kimliği alanını belirterek Yer Ayrıntıları isteğinde bulunarak Yer Kimliklerini ücretsiz yenileyebilirsiniz.

Places API (Yeni)

Örneğin, Yer Ayrıntıları (Yeni) seçeneğini kullanarak:

https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY

Places API

Örneğin, eski Yer Ayrıntıları API'sini kullanarak: 

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY

Bu çağrı, Yer Ayrıntısı Yeni (Yalnızca Kimlikler) veya Yer Ayrıntıları - Kimlik Yenileme SKU'sunu tetikler.

Bu istek, NOT_FOUND durum kodu da döndürebilir. Stratejilerden biri, her bir yer kimliğini döndüren orijinal isteği depolamaktır. Bir yer kimliği geçersiz hale gelirse yeni sonuçlar almak için bu isteği yeniden gönderebilirsiniz. Bu sonuçlar orijinal yeri içerebilir veya içermeyebilir. Ancak, bu istek ücretlidir.

Yer kimlikleri kullanılırken karşılaşılan hata kodları

INVALID_REQUEST durum kodu, belirtilen yer kimliğinin geçerli olmadığını gösterir. Yer kimliği kısaltıldığında veya başka bir şekilde değiştirildiğinde ve artık doğru olmadığında INVALID_REQUEST döndürülebilir.

NOT_FOUND durum kodu, belirtilen yer kimliğinin eski olduğunu belirtir. Bir işletme yeni bir konuma kapanırsa veya yeni bir konuma taşınırsa yer kimliği geçersiz olabilir. Yer kimlikleri, Google Haritalar veritabanındaki büyük ölçekli güncellemeler nedeniyle değişebilir. Bu gibi durumlarda, yer yeni bir yer kimliği alabilir ve eski kimlik NOT_FOUND yanıtı döndürür.

Özellikle, bazı yer kimliği türleri bazen NOT_FOUND yanıtına neden olabilir veya API, yanıtta farklı bir yer kimliği döndürebilir. Bu yer kimliği türleri şunlardır:

  • Google Haritalar'da tam adres olarak bulunmayan, ancak bir adres aralığından tahmin edilen açık adresler.
  • İsteğin aynı zamanda bir şehri veya konumu da belirttiği uzun bir rotanın segmentleri.
  • Kesişimler.
  • subpremise türünde adres bileşenine sahip yerler.

Bu kimlikler genellikle uzun bir dizedir (Yer Kimlikleri için maksimum uzunluk yoktur). Örneğin:

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4