Places API 會透過各種方法接受地點資料要求。Places API 回應包含地點資料,包括位置資料和圖像、地理位置和重要搜尋點。
在這個版本中,Text Search、Nearby Search 和 Place Details 的回應也能包含 Google 地圖的連結。使用者可以瀏覽這些 Google 地圖連結,查看回覆中關於某個地點的其他資訊。
舉例來說,假設您要搜尋加州舊金山的機場,回應會將舊金山國際機場 (SFO) 納入地點清單。在這個版本中,回應中 SFO 的 Place
物件會新增 googleMapsUri
欄位,其中包含 Google 地圖連結,可開啟 Google 地圖,前往該地點、查看該地點的路線、評論和地點相片。
除了新增至 Place
物件的連結之外,這個版本也將 googleMapsUri
欄位新增至回應中的 Reviews
和 Photos
物件:
Reviews.googleMapsUri
:包含評論的 Google 地圖連結,方便您在瀏覽器中查看。Photos.googleMapsUri
:包含相片的 Google 地圖連結,方便您在瀏覽器中查看相片。
您可以透過 API Explorer 提出即時要求,熟悉這些新選項:
支援的 Google 地圖連結
下表列出您可以在回應中加入的 Google 地圖連結:
Google 地圖連結 | 說明 | 欄位名稱 |
---|---|---|
地點 | 連結至 Google 地圖,開啟該地點。 | googleMapsLinks.placeUri |
路線 | 連結:開啟前往該地點的路線,並在 Google 地圖中顯示。 | googleMapsLinks.directionsUri |
撰寫評論 | 連結至 Google 地圖,以便為該地點撰寫評論。 | googleMapsLinks.writeAReviewUri |
閱讀評論 | 連結至 Google 地圖,顯示該地點的評論。 | googleMapsLinks.reviewsUri |
相片 | 連結至 Google 地圖中顯示該地點的相片。 | googleMapsLinks.photosUri |
定價
這項功能目前處於正式發布前預覽階段,因此在預覽期間使用時不會產生費用,也就是帳單金額為 $0。如要進一步瞭解建議的定價,請參閱「Places API 用量與計費」。
在 Places 回應中加入所有連結
地點回應中的連結包含在 googleMapsLinks
欄位中。如果您希望 googleMapsLinks
欄位出現在回應中,請務必在要求的欄位遮罩中加入該欄位。
舉例來說,下列文字搜尋會在回應中加入所有 Google 地圖連結:
curl -X POST -d '{ "textQuery" : "San Francisco International Airport" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key:API_KEY ' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel,places.googleMapsLinks' \ 'https://places.googleapis.com/v1/places:searchText'
回應的格式如下:
{ "places": [ { "formattedAddress": "San Francisco, CA 94128, USA", "displayName": { "text": "San Francisco International Airport", "languageCode": "en" }, "googleMapsLinks": { "placeUri": "https://maps.google.com/?cid=11885663895765773631", "directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x808f778c55555555:0xa4f25c571acded3f!3e0", "writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x808f778c55555555:0xa4f25c571acded3f!12e1", "reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x808f778c55555555:0xa4f25c571acded3f!9m1!1b1", "photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x808f778c55555555:0xa4f25c571acded3f!10e5" } } ] }
在回覆中加入特定連結
您不必在回應中傳回所有連結。舉例來說,如果您只想要回應中的相片連結,請修改欄位遮罩,如以下所示,只包含 photosUri
欄位:
curl -X POST -d '{ "textQuery" : "San Francisco International Airport" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key:API_KEY ' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel,places.googleMapsLinks.photosURI' \ 'https://places.googleapis.com/v1/places:searchText'
在回覆中加入指示
所有 Places 方法都支援在回應中產生路線連結。目前位置會用做起點,地點位置會用做目的地,而交通模式則是開車。
以下範例使用 Nearby Search,在 directionsUri
欄位的回應中加入地圖路線連結:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": -33.8688, "longitude": 151.1957362}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key:API_KEY ' \ -H 'X-Goog-FieldMask: places.displayName,places.googleMapsLinks.directionsUri' \ https://places.googleapis.com/v1/places:searchNearby
加入評論和相片連結
這個版本會將 googleMapsUri
欄位新增至回應中的 Reviews
和 Photos
物件。瀏覽這些連結會在 Google 地圖中開啟評論或相片。
舉例來說,下列文字搜尋會在回應中加入每個地點的評論和相片:
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.displayName,places.reviews,places.photos' \ 'https://places.googleapis.com/v1/places:searchText'
在回應中,評論和相片陣列的每個元素都包含 googleMapsUri
欄位,可在瀏覽器中開啟評論或相片。
試試看!
您可以使用 API Explorer 提出範例要求,熟悉 API 和 API 選項。
選取頁面右側的 API 圖示
。
您可以選擇展開「顯示標準參數」,然後將
fields
參數設為欄位遮罩。您可以選擇編輯要求主體。
選取「執行」按鈕。在對話方塊中,選擇要用來提出要求的帳戶。
在 API Explorer 面板中,選取展開圖示
來展開 API Explorer 視窗。