計算路線摘要

如要使用文字搜尋 (新版) 或附近地點搜尋 (新版)，計算回應中每個地點的交通時間和距離，請按照下列步驟操作：

  1. 在要求中傳遞 routingParameters.origin 參數，指定路線起點的經緯度座標。計算回應中每個地點的距離和時間時，必須使用這個參數。

  2. 在欄位遮罩中加入 routingSummaries，讓回應包含 routingSummaries 陣列。這個陣列包含從路徑起點到回應中每個地點的所需時間和距離。

您可以使用 APIs Explorer 傳送即時要求，熟悉 API 和 API 選項：

使用 Text Search (新版)

在下列要求中，您會計算 Text Search (新版) 回應中每個地點的行程時間和距離：

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

回應包含兩個 JSON 陣列：places 陣列包含相符地點，routingSummaries 陣列則包含前往每個地點的距離和時間：

{
  "places": [
    {
      object (Place)
    }
  ]
  "routingSummaries": [
    {
      object (RoutingSummary)
    }
}

routingSummaries 陣列中的每個元素都位於對應的陣列位置，與 places 陣列中的地點相同。也就是說，routingSummaries[0] 的元素對應於 places[0] 的地點。

routingSummaries 的陣列長度與 places 的陣列長度相同。如果地點的 routingSummary 無法使用，陣列項目會是空白。

由於這個範例會計算從路線起點到每個地點的所需時間和距離，因此回應中的 routingSummaries.legs 欄位會包含單一 Leg 物件，其中包含從路線起點到該地點的 duration 和 distanceMeters。

{
  "places": [
    {
      "formattedAddress": "1, Westfield Sydney Central Plaza, 450 George St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Gözleme King Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    …
  ]
  "routingSummaries": [
    {
      "legs": [
        {
          "duration": "597s",
          "distanceMeters": 2607
        }
      ],
      "directionsUri": "https://www.google.com/maps/dir/-33.8688,151.1957362/''/data=!4m6!4m5!1m0!1m2!1m1!1s0x6b12ae3fa97cd745:0x6aecf365bf497c08!3e0"
    },
    {
      "legs": [
        {
          "duration": "562s",
          "distanceMeters": 2345
        }
      ],
      "directionsUri": "https://www.google.com/maps/dir/-33.8688,151.1957362/''/data=!4m6!4m5!1m0!1m2!1m1!1s0x6b12ae3da97f60c1:0x845f3273bd764f6c!3e0"
    },
   …
  ]
}

從這個範例中，您可以看到從路徑起點到結果中第一個地點的距離和時間分別是 2607 公尺和 597 秒。

在這個範例中，您會計算「附近搜尋」回應中每個地點的行程時間和距離。這個範例會搜尋澳洲雪梨的餐廳，並將地點限制和路線起點設為相同的經緯度座標：

  curl -X POST -d '{
    "includedTypes": ["restaurant"],
    "maxResultCount": 10,
    "locationRestriction": {
      "circle": {
        "center": {
          "latitude": -33.8688,
          "longitude": 151.1957362},
        "radius": 500.0
      }
    },
    "routingParameters": {
      "origin": {
        "latitude": -33.8688,
        "longitude": 151.1957362
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key:API_KEY" \
  -H "X-Goog-FieldMask: places.displayName,routingSummaries" \
  https://places.googleapis.com/v1/places:searchNearby

您不必為 locationRestriction 和路徑起點使用相同的座標。舉例來說，您可以將 locationRestriction 設為雪梨的中心點，讓搜尋結果偏向該圓圈。但您隨後將路線起點設為住家座標，也就是搜尋圓圈內的不同位置。然後，要求會將搜尋結果偏向圓圈，並根據住家位置計算路線摘要。

指定交通方式

根據預設，系統會計算車輛的行程時間和距離。不過，你可以在搜尋時控制車輛類型和其他選項。

  • 使用 routingParameters.travelMode 參數將交通方式設為 DRIVE、BICYCLE、WALK 或 TWO_WHEELER。如要進一步瞭解這些選項，請參閱「路線適用的車輛類型」。

  • 使用 routingParameters.routingPreference 屬性將轉送偏好設定選項設為 TRAFFIC_UNAWARE (預設值)、TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL。每個選項的資料品質和延遲程度不一。詳情請參閱指定是否要納入流量資料及納入方式。

    routingParameters.routingPreference 屬性會影響「預覽」(Pre-GA) directionsUri 欄位中包含的路線，因為 Google 地圖會在開啟連結時顯示交通選項。

  • 使用 routingParameters.routeModifiers 屬性指定 avoidTolls、avoidHighways、avoidFerries 和 avoidIndoor。如要進一步瞭解這些選項，請參閱「指定要避開的路線功能」。

在下一個範例中，您將交通方式指定為 DRIVE，並避開高速公路：

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "routingParameters": {
    "origin": {
      "latitude": -33.8688,
      "longitude": 151.1957362
    },
    "travelMode":"DRIVE",
    "routeModifiers": {
      "avoidHighways": true
    }
  }
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel,routingSummaries' \
'https://places.googleapis.com/v1/places:searchText'

試試看！

您可以使用 APIs Explorer 提出範例要求，熟悉 API 和 API 選項。

  1. 選取頁面右側的 API 圖示 api。

  2. 視需要編輯要求參數。

  3. 選取「Execute」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。

  4. 在 APIs Explorer 面板中，選取全螢幕圖示 fullscreen 展開 APIs Explorer 視窗。

上一頁
沿路線搜尋
下一頁
結合路徑摘要與路徑一併搜尋