Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Đôi khi, bạn có thể muốn lên kế hoạch cho tuyến đường mà ứng dụng cung cấp cho người dùng. Việc sử dụng mã thông báo tuyến đường từ Routes API, Routes Preferred API hoặc Route Optimization API có thể giúp bạn chỉ định 2 điều cho tuyến đường đã lên kế hoạch:
Một đường nhiều đoạn cho tuyến đường
Mục tiêu của tuyến đường
Ví dụ: sau đây là một số ví dụ về mục tiêu định tuyến mà bạn có thể có:
Giảm thiểu thời gian giao hàng: Một doanh nghiệp giao đồ ăn có thể muốn giảm thiểu thời gian giao đồ ăn.
Giảm thiểu thời gian di chuyển hoặc mức tiêu thụ nhiên liệu: Một doanh nghiệp hậu cần có thể muốn cải thiện hiệu suất của người lái xe và giảm chi phí nhiên liệu.
Giảm thiểu thời gian đến đích đến: Một hoạt động điều phối dịch vụ có thể muốn giảm thiểu thời gian cần thiết để đưa nhân viên đến nơi có yêu cầu công việc.
Giảm chi phí và cải thiện độ an toàn: Một doanh nghiệp đi chung xe có thể muốn tìm một tuyến đường có chi phí thấp hơn cho người đi xe và tránh một số khu vực vì lý do an toàn.
Lý do bạn nên sử dụng mã thông báo tuyến đường cho các mục tiêu về tuyến đường
Với mã thông báo tuyến đường từ Routes API, Routes Preferred API hoặc Route Optimization API, bạn có thể kiểm soát tốt hơn tuyến đường được cung cấp:
Lập kế hoạch trước cho một tuyến đường để Navigation SDK sử dụng khi có thể.
Chọn tuyến đường phù hợp nhất để Navigation SDK sử dụng. Nếu yêu cầu mã thông báo tuyến đường khi tạo tuyến đường trong Routes API, bạn sẽ nhận được mã thông báo tuyến đường cho mỗi tuyến đường được tạo. Sau đó, bạn có thể chọn mã thông báo cho tuyến đường mà bạn muốn sử dụng khi truyền mã thông báo đó đến Navigation SDK.
Ước tính giá trước, bao gồm cả thông tin ước tính về thời gian đến dự kiến và khoảng cách. Mặc dù chi phí và thời gian thực tế có thể khác, nhưng thông tin ước tính này sẽ giảm khoảng cách giữa chi phí dự kiến và chi phí thực tế của tuyến đường.
Chỉ định các mục tiêu nâng cao hơn cho tuyến đường, chẳng hạn như định tuyến thân thiện với môi trường hoặc tuyến đường ngắn nhất.
Cách hoạt động của mã thông báo tuyến đường
Bạn có thể sử dụng Routes API, Routes Preferred API hoặc Route Optimization API để lập kế hoạch cho một tuyến đường bằng cách sử dụng các mục tiêu về tuyến đường. Bạn có thể truyền mã thông báo tuyến đường do bất kỳ API nào trong số này trả về đến Navigation SDK để hướng dẫn cách SDK này định tuyến cho xe của bạn.
Sau đây là những điều sẽ xảy ra khi bạn yêu cầu và sử dụng mã thông báo tuyến đường:
Routes API, Routes Preferred API hoặc Route Optimization API trả về một mã thông báo tuyến đường được mã hoá, bao gồm đường đa tuyến và các mục tiêu của tuyến đường.
Bạn truyền mã thông báo tuyến đường đến Navigation SDK.
Navigation SDK sẽ truy xuất tuyến đường hoặc nếu tuyến đường không có sẵn do điều kiện thay đổi, thì SDK này sẽ truy xuất tuyến đường phù hợp nhất.
Trong khi lái xe trên tuyến đường, nếu tình trạng giao thông hoặc tình trạng đường khác thay đổi, hoặc nếu xe đi lệch khỏi tuyến đường đã lên kế hoạch, thì các tuyến đường đã sửa đổi sẽ liên tục cố gắng khớp với tuyến đường tốt nhất dựa trên các mục tiêu của tuyến đường trong mã thông báo.
Quá trình này giúp tối đa hoá mức độ trùng khớp giữa tuyến đường thực tế và tuyến đường bạn đã lên kế hoạch.
Lý do bạn có thể không đi theo đúng tuyến đường đã lên kế hoạch
Hãy coi tuyến đường và mục tiêu của tuyến đường mà bạn dự định đi là những nguyên tắc cần tuân thủ, chứ không phải là những quy tắc bắt buộc. Bạn có thể thấy sự khác biệt giữa tuyến đường đã lên kế hoạch và tuyến đường do chế độ chỉ đường từng bước cung cấp do sự khác biệt về điều kiện đường, vị trí bắt đầu hoặc các thông số khác đã thay đổi kể từ khi bạn tạo tuyến đường đã lên kế hoạch. Sự khác biệt này có thể dẫn đến sự không khớp giữa mục tiêu dự kiến và mục tiêu thực tế về khoảng cách và thời gian đến dự kiến, cùng với những yếu tố quan trọng khác của chuyến đi.
Lập kế hoạch cho một tuyến đường bằng mã thông báo tuyến đường
Bạn có thể lập kế hoạch cho một tuyến đường bằng cách tạo mã thông báo tuyến đường rồi truyền mã thông báo đó đến Navigation SDK, như mô tả trong các bước sau:
Bước 1: Tạo mã thông báo tuyến đường bằng Routes API, Routes Preferred API hoặc Route Optimization API
Yêu cầu mã thông báo tuyến đường bằng một trong các phương thức sau:
Routes Preferred API: computeCustomRoutes. Để biết thêm thông tin về cách yêu cầu mã thông báo tuyến đường trong Routes Preferred API, hãy xem phần Lập kế hoạch cho một tuyến đường.
Route Optimization API: optimizeTours hoặc batchOptimizeTours. Để biết thêm thông tin về cách yêu cầu mã thông báo tuyến đường trong Route Optimization API, hãy xem bài viết Chuyển đổi mã thông báo tuyến đường và đường nhiều đoạn.
Thiết lập yêu cầu Routes API hoặc Routes Preferred API để đáp ứng các yêu cầu khi sử dụng mã thông báo tuyến đường:
Đặt travel_mode thành DRIVING hoặc TWO_WHEELER
Đặt routing_preference thành TRAFFIC_AWARE hoặc TRAFFIC_AWARE_OPTIMAL
KHÔNG sử dụng Via điểm đánh dấu
Bước 2: Truyền mã thông báo tuyến đường đến Navigation SDK
Lưu trữ mã thông báo tuyến đường: Trong Navigation SDK, hãy thiết lập một chuỗi để lưu trữ mã thông báo tuyến đường. Ví dụ:
letrouteToken="route token returned by Routes API"
Ví dụ về mã thông báo tuyến đường được trả về:
{// Other fields"routeToken":"CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",}
Truyền mã thông báo tuyến đường đến Navigation SDK bằng phương thức mapView.navigator setDestinations, chỉ định các điểm đến tương tự mà bạn đã sử dụng khi tạo mã thông báo tuyến đường:
Phương thức Navigator.setDestinations trả về trạng thái của yêu cầu.
Nếu tìm thấy một tuyến đường từ vị trí của người dùng đến đích đến đã cho, thì phương thức này sẽ trả về RouteStatus.OK.
Các ví dụ về mã sau đây minh hoạ cách truy xuất một tuyến đường đã lên kế hoạch.
Swift
letlocation=CLLocationCoordinate2D(latitude:47.67,longitude:-122.20)letwaypoint1=GMSNavigationWaypoint(location:location,title:"waypoint from location")!letwaypoint2=GMSNavigationWaypoint(placeID:"samplePlaceID",title:"waypoint from Place ID")!letrouteToken="route token returned by Routes API"mapView.navigator?.setDestinations([waypoint1,waypoint2],routeToken:routeToken,callback:{...})
Objective-C
CLLocationCoordinate2Dlocation=CLLocationCoordinate2DMake(47.67,-122.20);GMSNavigationWaypoint*waypoint1=[[GMSNavigationWaypointalloc]initWithLocation:coordinatetitle:@"waypoint from location"];GMSNavigationWaypoint*waypoint2=[[GMSNavigationWaypointalloc]initWithPlaceID:@"samplePlaceID"title:@"waypoint from Place ID"];NSString*routeToken=@"route token returned by Routes API";[mapView.navigatorsetDestinations:@[waypoint1,waypoint2]routeToken:routeTokencallback:^(GMSRouteStatusrouteStatus){...}];
Cách mã thông báo tuyến đường và Navigation SDK tương tác
Sau đây là cách tương tác giữa tuyến đường do Navigation SDK tạo và tuyến đường đã lên kế hoạch trong mã thông báo tuyến đường:
Bỏ qua các lựa chọn sau đây liên quan đến việc định tuyến vì không cần thiết:
avoidsHighways
avoidsTolls
avoidsFerries
licensePlateRestriction
Follows:
Các lựa chọn liên quan đến điểm đánh dấu, chẳng hạn như lựa chọn ưu tiên về phía đường.
Mục tiêu của tuyến đường. Nếu Navigation SDK phải điều chỉnh tuyến đường được trả về, thì SDK này sẽ sử dụng các mục tiêu về tuyến đường mà bạn đã chỉ định khi yêu cầu mã thông báo tuyến đường. Vì lý do này, bạn nên sử dụng các lựa chọn liên quan đến điểm tham chiếu mà bạn đã chỉ định trong Routes API.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-31 UTC."],[[["\u003cp\u003eRoute tokens let you plan routes in advance, optimizing for factors like time, fuel, or safety, and can be generated using the Routes, Routes Preferred, or Route Optimization API.\u003c/p\u003e\n"],["\u003cp\u003eWhile the Navigation SDK attempts to follow the planned route, real-world conditions may cause deviations; it dynamically adjusts while prioritizing the specified route objectives.\u003c/p\u003e\n"],["\u003cp\u003eYou create a route token via the Routes, Routes Preferred, or Route Optimization API, then pass it to the Navigation SDK's \u003ccode\u003esetDestinations\u003c/code\u003e method alongside your waypoints.\u003c/p\u003e\n"],["\u003cp\u003eThe Navigation SDK prioritizes the route token's plan but dynamically adapts to real-time conditions, potentially leading to variations between the planned and actual route.\u003c/p\u003e\n"],["\u003cp\u003eAlways request a fresh route token for each trip and anticipate potential route adjustments to ensure smooth navigation and accurate estimations.\u003c/p\u003e\n"]]],[],null,["# Plan a route\n\nAt times, you might want to plan the route your app provides to users. Using a\nroute token from the Routes API,\nRoutes Preferred API, or Route Optimization API can\nhelp you specify two things for your planned route:\n\n- A polyline for the route\n\n- Your route objectives\n\nFor example, here are some examples of routing objectives you may have:\n\n- **Minimize time to delivery**: A business delivering food might want to\n minimize the time it takes to deliver the food.\n\n- **Minimize travel time or fuel consumption**: A logistics business might\n want to improve the efficiency of their drivers and reduce their fuel costs.\n\n- **Minimize time to destination**: A service dispatch operation might want to\n minimize the time it takes to get operators to a job request.\n\n- **Lower costs and improve safety**: A ride-sharing business might want to\n find a route that costs less for riders and avoids certain areas for safety\n reasons.\n\n| **Important:** The actual route traveled may vary from the planned route provided by the token. Changing traffic, road conditions, or the vehicle deviating from the given route can result in route changes. As changes occur, the Navigation SDK continually attempts to return to the planned route, or if returning is impractical, follows the route objectives in the route token.\n\nFor more information about planning a route using a route token, see [Request a\nroute token](/maps/documentation/routes/choose_fields#route-token) in\nRoutes API and [Transition Polylines and Route\nTokens](/maps/documentation/route-optimization/polylines-and-route-tokens) in\nRoute Optimization API.\n\nWhy use a route token for route objectives\n------------------------------------------\n\nWith a route token from the Routes API,\nRoutes Preferred API, or Route Optimization API, you\nhave more control over the route provided:\n\n- **Plan a route in advance** for the Navigation SDK to use when\n possible.\n\n- **Choose the best route for the Navigation SDK to use**. If you\n request route tokens when generating routes in the Routes API,\n you get a route token for each generated route. You can then choose the\n token for the route you want to use when you pass it to the\n Navigation SDK.\n\n- **Estimate the price in advance**, including estimations for ETA and\n distance. While the actual cost and time might vary, this estimation reduces\n the gap between expected and actual route cost.\n\n- **Specify more advanced route objectives**, such as eco routing or the\n shortest route.\n\n| **Tip:** A route token is for one specific origin and destination and at a particular time. You must make a new Routes API, Routes Preferred API, or Route Optimization API request for a new route token.\n\nHow route tokens work\n---------------------\n\nYou can use the Routes API, Routes Preferred API, or\nRoute Optimization API to plan a route using route objectives. You\ncan pass a route token returned from any of these APIs to the\nNavigation SDK to guide how it routes your vehicle.\n\nHere's what happens when you request and use a route token:\n\n1. The Routes API, Routes Preferred API, or\n Route Optimization API returns an encrypted route token that\n includes the route polyline and route objectives.\n\n2. You pass the route token to the Navigation SDK.\n\n3. The Navigation SDK retrieves the route, or if the route is not\n available due to changing conditions, it retrieves the best matching route.\n\n4. While driving the route, if traffic or other road conditions change, or if a\n vehicle deviates from the planned route, the modified routes continually\n attempt to match the best route based on the route objectives in the token.\n\nThis process maximizes how close the actual route is to your planned route.\n\n### Why a planned route may not be followed exactly\n\nThink of your planned route and route objectives as guidelines to follow: they\nare not prescriptive. You might see a difference between your planned route and\nthe route provided by guided navigation due to differences in the road\nconditions, starting location, or other parameters that have changed since you\ncreated the planned route. This difference might result in a mismatch between\nyour planned and actual goals for distance and ETA, among other important trip\nqualities.\n| **Tip:** As a best practice, always request a new route token every time you set the destination in the Navigation SDK, and plan for some variation to avoid any impact to your business.\n\nPlan a route using a route token\n--------------------------------\n\nYou can plan a route by creating a route token and then passing it to the\nNavigation SDK, as described in the following steps:\n\n### Step 1: Create a route token using the Routes API, Routes Preferred API, or Route Optimization API\n\n1. **Request a route token** with one of the following methods:\n\n - **Routes API** : `computeRoutes`. For more information\n about requesting a route token in the Routes API, see\n [Compute a route](/maps/documentation/routes/compute_route_directions)\n and [Request a route\n token](/maps/documentation/routes/choose_fields#route-token).\n\n - **Routes Preferred API** : `computeCustomRoutes`. For more\n information about requesting a route token in the\n Routes Preferred API, see [Plan a\n route](/maps/documentation/routes_preferred/custom_routes).\n\n - **Route Optimization API** : `optimizeTours` or\n `batchOptimizeTours`. For more information about requesting a route\n token in the Route Optimization API, see [Transition Polylines and Route\n Tokens](/maps/documentation/route-optimization/polylines-and-route-tokens).\n\n2. **Set up your Routes API or Routes Preferred API\n request** to meet the requirements for using a route token:\n\n - Set `travel_mode` to `DRIVING` or `TWO_WHEELER`\n - Set `routing_preference` to `TRAFFIC_AWARE` or `TRAFFIC_AWARE_OPTIMAL`\n - Do NOT use `Via` waypoints\n\n### Step 2: Pass the route token to the Navigation SDK\n\n1. **Store the route token**: In the Navigation SDK, set up a string\n to store the route token. For example:\n\n let routeToken = \"route token returned by Routes API\"\n\n Example of a returned route token: \n\n {\n // Other fields\n \"routeToken\": \"CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g\",\n }\n\n2. **Pass the route token** to the Navigation SDK using the\n `mapView.navigator setDestinations` method, specifying the same destination\n waypoints that you used when creating the route token:\n\n mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})\n\n| **Note:** If you need to travel the same route again, request a new route token.\n\nThe `Navigator.setDestinations` method returns the status of the request.\nIf a route is found from the user's location to the given destination,\nit returns`RouteStatus.OK`.\n\nFor more information about this method, see\n[`GMSNavigator.setDestinations`](/maps/documentation/navigation/ios-sdk/reference/objc/Classes/GMSNavigator#-setdestinations:callback:).\n\n### Example\n\nThe following code examples demonstrate how to retrieve a planned route.\n\n\u003cbr /\u003e\n\n### Swift\n\n\u003cbr /\u003e\n\n let location = CLLocationCoordinate2D(latitude: 47.67, longitude: -122.20)\n let waypoint1 = GMSNavigationWaypoint(location: location, title: \"waypoint from location\")!\n let waypoint2 = GMSNavigationWaypoint(placeID: \"samplePlaceID\", title: \"waypoint from Place ID\")!\n\n let routeToken = \"route token returned by Routes API\"\n mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})\n\n\u003cbr /\u003e\n\n### Objective-C\n\n\u003cbr /\u003e\n\n CLLocationCoordinate2D location = CLLocationCoordinate2DMake(47.67, -122.20);\n GMSNavigationWaypoint *waypoint1 = [[GMSNavigationWaypoint alloc] initWithLocation:coordinate title:@\"waypoint from location\"];\n GMSNavigationWaypoint *waypoint2 = [[GMSNavigationWaypoint alloc] initWithPlaceID:@\"samplePlaceID\"\n title:@\"waypoint from Place ID\"];\n NSString *routeToken = @\"route token returned by Routes API\";\n\n [mapView.navigator setDestinations:@[waypoint1, waypoint2]\n routeToken:routeToken\n callback:^(GMSRouteStatus routeStatus){...}];\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nHow route tokens and the Navigation SDK interact\n------------------------------------------------\n\nHere's how the route generated by the Navigation SDK and the planned\nroute in the route token interact:\n\n- **Overrides** any previously-set destinations.\n\n- **Uses** the vehicle starting location.\n\n- **Adjusts** for road and traffic conditions. See\n [Why a planned route might not be followed exactly](#not-followed).\n\n- **Ignores** the following routing-related options as unneeded:\n\n - `avoidsHighways`\n - `avoidsTolls`\n - `avoidsFerries`\n - `licensePlateRestriction`\n- **Follows**:\n\n - **Waypoint-related options**, such as the side-of-road preference.\n\n - **Route objectives**. If the Navigation SDK has to\n adjust the returned route, it uses the route objectives you specified when\n requesting the route token. For this reason, you should use the same\n waypoint-related options that you specified in Routes API."]]
