Yer kimlikleri

Platform seçin: Android iOS JavaScript Web Hizmeti
Avrupa Ekonomik Alanı (AEA) geliştiricileri

Giriş

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

  • Geocoding API ve Geocoding Hizmeti, Maps JavaScript API'de bir yer kimliği için adres alma.
  • Routes API ve Directions API (Eski) ile Directions Hizmeti, Maps JavaScript API'de (Eski) başlangıç, hedef ve ara yol noktalarını belirtme.
  • Routes API, Distance Matrix API (Eski) ve Distance Matrix Hizmeti, Maps JavaScript API (Eski) ile başlangıç ve hedef noktaları belirtme
  • Yerler API'sinde (Yeni), Android için Yerler SDK'sında (Yeni), iOS için Yerler SDK'sında (Yeni) ve Yerler Kitaplığı'nda yer ayrıntılarını alma
  • Maps Embed API'de yer kimliği parametrelerini kullanma.
  • Haritalar URL'lerindeki arama sorgularını alma
  • Roads API'de hız sınırlarını gösterme
  • Sınırlar için veri odaklı stilde sınır çokgenlerini bulma ve stilini belirleme.

Belirli bir yerin kimliğini bulma

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

Alternatif olarak, Maps JavaScript API belgelerinde yer kimliği bulucuyu kodlarıyla birlikte görüntüleyebilirsiniz.

Genel Bakış

Yer kimliği, bir yeri benzersiz şekilde tanımlayan metin biçimindeki 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

İşletmeler, önemli noktalar, parklar ve kavşaklar dahil olmak üzere çoğu konum için yer kimlikleri kullanılabilir. Aynı yerin veya konumun birden fazla farklı yer kimliği olabilir. Yer kimlikleri zaman içinde değişebilir.

Places API ve bir dizi Google Haritalar Platformu API'sinde aynı yer kimliğini 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 kimliklerini kullanmanın yaygın bir yolu, Places API veya Maps JavaScript API'deki Places kitaplığını kullanarak bir yer aramaktır. Ardından, döndürülen yer kimliğini kullanarak yer ayrıntılarını alın. 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 bu belgenin ilerleyen bölümlerinde bulabilirsiniz.

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

Places API (Yeni)

Places API'yi kullanarak Text Search (New) (Yeni Metin Arama) isteği göndererek 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ıtta, aşağıdaki örnekte gösterildiği gibi id alanında bir yer kimliği bulunur:

{
  "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 (Eski)

Places API'yi kullanarak Yer Arama isteği göndererek yer kimliği bulabilirsiniz.

Aşağıdaki örnek, Avustralya'nın Sidney şehrindeki bir noktanın 1.500 metre yarıçapında, "cruise" kelimesini içeren "restoran" türündeki yerlerle ilgili 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ıtta, bu snippet'te gösterildiği gibi place_id alanında bir yer kimliği bulunuyor:

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

Artık place_id parametresine yer kimliğini yerleştirerek bir Yer Ayrıntıları (Eski) 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 üzere kaydetme

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

Kayıtlı yer kimliklerini yenileme

Google Haritalar veritabanındaki güncellemeler nedeniyle yer kimlikleri değişebileceğinden Google, 12 aydan eski yer kimliklerinin yenilenmesini önerir. fields parametresinde yalnızca yer kimliği alanını belirterek Yer Ayrıntıları isteği göndererek yer kimliklerini ücretsiz olarak yenileyebilirsiniz.

Places API (Yeni)

Örneğin, Yer Ayrıntıları (Yeni)'nı kullanma:

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

Places API (Eski)

Örneğin, Places API (Eski) kullanılarak:

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ıları Yeni Essentials Yalnızca Kimlikler veya Yer Ayrıntıları - Kimlik Yenileme SKU'sunu tetikler.

Yer kimlikleri kullanılırken hata kodları

INVALID_REQUEST

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

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

Eski bir yer kimliği olması durumunda sonuçları yenilemek için her yer kimliğini döndüren orijinal isteği saklayın ve gerektiğinde isteği yeniden gönderin. Yeniden gönderilen isteğin uygun SKU'da faturalandırıldığını unutmayın.

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 çıkarılan açık adresler.
  • İsteğin şehir veya yerleşim yeri de belirttiği uzun bir rotanın bölümleri.
  • Kavşaklar.
  • subpremise türünde bir adres bileşeni olan 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