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 hizmetinde ve Coğrafi Kodlama Hizmeti, Maps JavaScript API'de bir yer kimliği için adres alma.
  • Rotalar API ve Directions API web hizmetinde ve Directions Hizmeti, Maps JavaScript API'de başlangıç, varış ve ara ara noktaları belirtme.
  • Rotalar API'sinde ve Distance Matrix API web hizmetinde, Distance Matrix Hizmeti ve Maps JavaScript API'de başlangıç ve varış noktalarını belirtme.
  • Places API web hizmetinde, Android için Yerler SDK'sında, iOS için Yerler SDK'sında ve Yerler Kitaplığı'nda yer ayrıntılarını alma.
  • Maps Embed API'de yer kimliği parametrelerini kullanma.
  • Haritalar URL'lerinde arama sorgularını alma.
  • Roads API'de hız sınırlarını görüntüleme.
  • Sınırlar için veri odaklı stil özelliğinde sınır poligonlarını bulma ve biçimlendirme.

Belirli bir yerin kimliğini bulma

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

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

Genel Bakış

Yer kimliği, bir yeri benzersiz şekilde tanımlayan metin tabanlı 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 yerler, parklar ve kavşaklar dahil çoğu konum için kullanılabilir. Aynı yerin veya konumun birden fazla farklı yer kimliği olabilir. Yer kimlikleri zaman içinde değişebilir.

Aynı yer kimliğini Places API ve çeşitli Google Haritalar Platformu API'lerinde kullanabilirsiniz. Örneğin, Places API, Maps JavaScript API, Geocoding API, Maps 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ı alma

Yer kimliklerinin yaygın kullanım alanlarından biri, bir yer aramak (ör. Places API veya Maps JavaScript API'deki Yerler kitaplığını kullanarak) ve ardından yer ayrıntılarını almak için döndürülen yer kimliğini kullanmaktır. Yer kimliğini saklayabilir ve daha sonra aynı yer ayrıntılarını almak için kullanabilirsiniz. Yer kimliklerini kaydetme hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

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 Metin Arama (Yeni) isteğinde bulunarak bir yer kimliği 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, aşağıdaki gibi id alanında bir yer kimliği içerir:

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

Artık istek URL'sine yer kimliğini ekleyerek Yer Ayrıntıları (Yeni) isteği gönderebilirsiniz:

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

Places API

Places API'yi kullanarak yer arama isteği göndererek bir yer kimliği bulabilirsiniz.

Aşağıdaki örnek, Avustralya'nın Sidney kentindeki bir noktadan 1.500 m yarıçapındaki alanda "cruise" kelimesini içeren "restoran" türündeki yerler için 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, bu snippet'te gösterildiği gibi place_id alanında bir yer kimliği içerir:

{
  "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 koyarak 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

Yer kimliklerini daha sonra kullanmak için kaydetme

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

Depolanan yer kimliklerini yenileme

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

Places API (Yeni)

Örneğin, Yer Ayrıntıları (Yeni)'ni kullanarak:

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

Places API

Örneğin, eski Place Details 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ı, Place Detail New (IDs Only) (Yeni Yer Ayrıntıları (Yalnızca Kimlikler)) veya Places Details - ID Refresh (Yer Ayrıntıları - Kimlik Yenileme) SKU'sunu tetikler.

Bu istek, NOT_FOUND durum kodu da döndürebilir. Bir strateji, her 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 hata kodları

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

NOT_FOUND durum kodu, belirtilen yer kimliğinin geçerli olmadığını gösterir. Bir işletme kapanırsa veya yeni bir konuma taşınırsa yer kimliği geçersiz hale gelebilir. Yer kimlikleri, Google Haritalar veritabanındaki güncellemeler nedeniyle değişebilir. Bu gibi durumlarda, bir yer yeni bir yer kimliği alabilir ve eski kimlik NOT_FOUND yanıtı döndürebilir.

Ö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 dizi adresten tahmin edilen açık adresler.
  • İstekte bir şehir veya yerleşim yeri de belirtildiği uzun bir rotanın segmentleri.
  • Kesişimler.
  • subpremise türündeki bir adres bileşenine sahip yerler.

Bu kimlikler genellikle uzun bir dize biçimindedir (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