計算路線摘要

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

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。如要進一步瞭解這些選項，請參閱「路線適用的車輛類型」。

  注意：Routes 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();
    });