計算路由摘要

如要使用 Text Search (新版) 或 Nearby Search (新版) 來計算回應中各個地點的交通時間和距離：

1. 在要求中傳遞 RoutingParameters 參數，使用 setOrigin() 指定路徑起點的經緯度座標。這個參數是計算回應中各個地點的時間長度和距離所需的必要參數。

2. 建構要求物件時，請新增 .setRoutingSummariesIncluded(true)。

使用 Text Search (新版)

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

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the routing parameters object and pass the routing origin.
RoutingParameters routingParameters = RoutingParameters.builder()
    .setOrigin(toLatLng("-33.8688, 151.1957362"))
    .build();

// Use the builder to create a SearchByTextRequest object and pass the routing parameters.
// Set setRoutingSummariesIncluded to true.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food in Sydney, Australia", placeFields)
    .setMaxResultCount(10)
    .setRoutingParameters(routingParameters)
    .setRoutingSummariesIncluded(true)
    .build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned Lists of Place objects, RoutingSummary objects, and Leg objects.
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
      List<RoutingSummary> routingSummaries = response.getRoutingSummaries();
      List<Leg> legs = routingSummaries.get(0).getLegs();
      Duration duration = legs.get(0).getDuration();
    });

SearchByTextResponse 類別代表搜尋要求的回應。您可以呼叫 SearchByTextResponse.getRoutingSummaries() 來傳回路由摘要清單。SearchByTextResponse 物件還包含：

• 代表所有相符地點的 Place 物件清單，每個相符地點對應一個 Place 物件。
• 每個 Place 物件只包含要求中傳遞的欄位清單所定義的欄位。

注意：回應只包含每個地點的 duration 和 distanceMeters。但不包含實際路線。如要計算路線，請使用 Routes API，並將目的地位置和起點傳遞給 API。

使用 Nearby Search

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

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the search area as a 500 meter diameter circle in Sydney, Australia.
LatLng center = new LatLng(-33.8688, 151.1957362);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 500);

// Define the routing parameters object and pass the routing origin.
RoutingParameters routingParameters = RoutingParameters.builder()
    .setOrigin(toLatLng("-33.8688, 151.1957362"))
    .build();

// Use the builder to create a SearchNearbyRequest object and pass the routing parameters.
// Set setRoutingSummariesIncluded to true.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setMaxResultCount(10)
    .setRoutingParameters(routingParameters)
    .setRoutingSummariesIncluded(true)
    .build();

// Call PlacesClient.searchNearby() to perform the search.
// Define a response handler to process the returned Lists of Place objects, RoutingSummary objects, and Leg objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
      List<RoutingSummary> routingSummaries = response.getRoutingSummaries();
      List<Leg> legs = routingSummaries.get(0).getLegs();
      Duration duration = legs.get(0).getDuration();
    });

SearchNearbyResponse 類別代表搜尋要求的回應。您可以呼叫 SearchNearbyResponse.getRoutingSummaries() 來傳回路由摘要清單。SearchNearbyResponse 物件還包含：

• 代表所有相符地點的 Place 物件清單，每個相符地點對應一個 Place 物件。
• 每個 Place 物件只包含要求中傳遞的欄位清單所定義的欄位。

您不必使用相同的座標來設定位置限制和路徑起點。舉例來說，如果您將位置限制設為雪梨的中心點，搜尋結果就會限制在該圓圈內。但您將路線起點設為住家的座標，也就是搜尋圓圈內的其他位置。然後將搜尋結果限制在圓圈內，並根據住家位置計算路線摘要。

指定交通選項

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

• 使用 routingParameters.setTravelMode() 將傳輸模式設為 DRIVE、BICYCLE、WALK 或 TWO_WHEELER。如要進一步瞭解這些選項，請參閱「路線可用的車輛類型」。

  注意：路徑 API 也支援 TRANSIT 模式，但 Places API 不支援該模式。
  注意：TWO_WHEELER 選項僅適用於兩輪車輛支援的國家/地區所列國家/地區。
• 使用 routingParameters.setRoutingPreference() 將路徑偏好設定選項設為 TRAFFIC_UNAWARE (預設)、TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL。每個選項的資料品質和延遲時間都不同。詳情請參閱「指定是否要納入流量資料的方式」。
• 使用 routingParameters.setRouteModifiers() 指定 avoidTolls、avoidHighways、avoidFerries 和 avoidIndoor。如要進一步瞭解這些選項，請參閱「指定要避免的路線地圖項目」。

在下一個範例中，您將旅遊模式指定為 DRIVE，並避免高速公路：

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the routing modifiers object.
RouteModifiers routeModifiers = RouteModifiers.builder()
    .setAvoidHighways(true)
    .build();

// Define the routing parameters object and pass the routing origin.
RoutingParameters routingParameters = RoutingParameters.builder()
    .setOrigin(toLatLng("-33.8688, 151.1957362"))
    .setTravelMode(DRIVE)
    .setRouteModifiers(routeModifiers)
    .build();

// Use the builder to create a SearchByTextRequest object and pass the routing parameters.
// Set setRoutingSummariesIncluded to true.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food in Sydney, Australia", placeFields)
    .setMaxResultCount(10)
    .setRoutingParameters(routingParameters)
    .setRoutingSummariesIncluded(true)
    .build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned Lists of Place objects, RoutingSummary objects, and Leg objects.
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
      List<RoutingSummary> routingSummaries = result.getRoutingSummaries();
      List<Leg> legs = routingSummaries.get(0).getLegs();
      Duration duration = legs.get(0).getDuration();
    });