Google 地圖連結

Places API 會透過各種方法接受地點資料要求。Places API 回應包含地點資料,包括位置資料和圖像、地理位置和重要搜尋點。

在這個版本中,Text Search、Nearby Search 和 Place Details 的回應也能包含 Google 地圖的連結。使用者可以瀏覽這些 Google 地圖連結,查看回覆中關於某個地點的其他資訊。

舉例來說,假設您要搜尋加州舊金山的機場,回應會將舊金山國際機場 (SFO) 納入地點清單。在這個版本中,回應中 SFO 的 Place 物件會新增 googleMapsUri 欄位,其中包含 Google 地圖連結,可開啟 Google 地圖,前往該地點、查看該地點的路線、評論和地點相片。

除了新增至 Place 物件的連結之外,這個版本也將 googleMapsUri 欄位新增至回應中的 ReviewsPhotos 物件:

  • Reviews.googleMapsUri:包含評論的 Google 地圖連結,方便您在瀏覽器中查看。

  • Photos.googleMapsUri:包含相片的 Google 地圖連結,方便您在瀏覽器中查看相片。

您可以透過 API Explorer 提出即時要求,熟悉這些新選項:

試試看!

下表列出您可以在回應中加入的 Google 地圖連結:

Google 地圖連結 說明 欄位名稱
地點 連結至 Google 地圖,開啟該地點。 googleMapsLinks.placeUri
路線 連結:開啟前往該地點的路線,並在 Google 地圖中顯示。 googleMapsLinks.directionsUri
撰寫評論 連結至 Google 地圖,以便為該地點撰寫評論。 googleMapsLinks.writeAReviewUri
閱讀評論 連結至 Google 地圖,顯示該地點的評論。 googleMapsLinks.reviewsUri
相片 連結至 Google 地圖中顯示該地點的相片。 googleMapsLinks.photosUri

定價

這項功能目前處於正式發布前預覽階段,因此在預覽期間使用時不會產生費用,也就是帳單金額為 $0。如要進一步瞭解建議的定價,請參閱「Places API 用量與計費」。

地點回應中的連結包含在 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 欄位新增至回應中的 ReviewsPhotos 物件。瀏覽這些連結會在 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 選項。

  1. 選取頁面右側的 API 圖示 展開 API Explorer。

  2. 您可以選擇展開「顯示標準參數」,然後將 fields 參數設為欄位遮罩

  3. 您可以選擇編輯要求主體

  4. 選取「執行」按鈕。在對話方塊中,選擇要用來提出要求的帳戶。

  5. 在 API Explorer 面板中,選取展開圖示 展開 API Explorer。 來展開 API Explorer 視窗。