앱에서 사용자에게 제공하는 경로를 계획해야 할 때가 있습니다. Routes API, Routes Preferred API 또는 Route Optimization API의 경로 토큰을 사용하면 계획된 경로에 대해 다음 두 가지를 지정할 수 있습니다.
경로의 다중선
내 경로 목표
예를 들어 다음과 같은 라우팅 목표가 있을 수 있습니다.
배송 시간 최소화: 음식 배달 비즈니스는 음식 배달 시간을 최소화하는 것이 좋습니다.
이동 시간 또는 연료 소비 최소화: 물류 비즈니스에서는 운전기사의 효율성을 개선하고 연료 비용을 절감할 수 있습니다.
목적지까지의 시간 최소화: 서비스 파견 작업은 작업 요청에 작업자를 배치하는 데 걸리는 시간을 최소화할 수 있습니다.
비용 절감 및 안전 개선: 차량 공유 비즈니스에서는 승객의 비용을 절감하고 안전상의 이유로 특정 지역을 피하는 경로를 찾을 수 있습니다.
경로 토큰을 사용하여 경로를 계획하는 방법에 대한 자세한 내용은 Routes API의 경로 토큰 요청 및 Route Optimization API의 폴리라인 및 경로 토큰 전환을 참고하세요.
경로 목표에 경로 토큰을 사용하는 이유
Routes API, Routes Preferred API 또는 Route Optimization API의 경로 토큰을 사용하면 제공되는 경로를 더 세부적으로 제어할 수 있습니다.
가능한 경우 Navigation SDK에서 사용할 수 있도록 미리 경로를 계획합니다.
Navigation SDK에서 사용할 최적의 경로를 선택합니다. Routes API에서 경로를 생성할 때 경로 토큰을 요청하면 생성된 각 경로에 대한 경로 토큰이 제공됩니다. 그런 다음 Navigation SDK에 전달할 때 사용할 경로의 토큰을 선택할 수 있습니다.
예상 도착 시간과 거리를 포함하여 미리 가격을 추정합니다. 실제 비용과 시간은 다를 수 있지만 이 추정치를 사용하면 예상 경로 비용과 실제 경로 비용 간의 차이가 줄어듭니다.
친환경 경로 또는 최단 경로와 같은 고급 경로 목표를 지정합니다.
경로 토큰의 작동 방식
Routes API, Routes Preferred API 또는 Route Optimization API를 사용하여 경로 목표를 사용하는 경로를 계획할 수 있습니다. 이러한 API에서 반환된 경로 토큰을 Navigation SDK에 전달하여 차량의 경로를 지정할 수 있습니다.
경로 토큰을 요청하고 사용하면 다음과 같은 일이 발생합니다.
Routes API, Routes Preferred API 또는 Route Optimization API는 경로 폴리라인과 경로 목표를 포함하는 암호화된 경로 토큰을 반환합니다.
경로 토큰을 Navigation SDK에 전달합니다.
Navigation SDK는 경로를 가져오고, 변경된 조건으로 인해 경로를 사용할 수 없는 경우 가장 적합한 경로를 가져옵니다.
경로를 운전하는 동안 교통 상황이나 기타 도로 상황이 변경되거나 차량이 계획된 경로에서 벗어나면 수정된 경로가 토큰의 경로 목표에 따라 최적의 경로와 일치하도록 지속적으로 시도합니다.
이 프로세스를 통해 실제 경로가 계획된 경로에 최대한 가까워집니다.
계획된 경로를 정확하게 따르지 못하는 이유
계획된 경로와 경로 목표는 따라야 하는 가이드라인으로 생각하세요. 규범적인 것은 아닙니다. 계획한 경로와 안내 내비게이션에서 제공하는 경로가 다를 수 있습니다. 이는 계획한 경로를 만든 후 도로 상황, 시작 위치 또는 기타 매개변수가 변경되었기 때문입니다. 이 차이로 인해 거리 및 예상 도착 시간과 기타 중요한 여정 품질에 대한 계획된 목표와 실제 목표 간에 불일치가 발생할 수 있습니다.
경로 토큰을 사용하여 경로 계획하기
다음 단계에 설명된 대로 경로 토큰을 만든 다음 Navigation SDK에 전달하여 경로를 계획할 수 있습니다.
1단계: Routes API, Routes Preferred API 또는 Route Optimization API를 사용하여 경로 토큰 만들기
다음 방법 중 하나를 사용하여 경로 토큰을 요청합니다.
Routes API: computeRoutes. Routes API에서 경로 토큰을 요청하는 방법에 관한 자세한 내용은 경로 계산 및 경로 토큰 요청을 참고하세요.
Routes Preferred API: computeCustomRoutes. Routes Preferred API에서 경로 토큰을 요청하는 방법에 관한 자세한 내용은 경로 계획을 참고하세요.
Route Optimization API: optimizeTours 또는 batchOptimizeTours Route Optimization API에서 경로 토큰을 요청하는 방법에 대한 자세한 내용은 폴리라인 및 경로 토큰 전환을 참고하세요.
경로 토큰 사용 요구사항을 충족하도록 Routes API 또는 Routes Preferred API 요청을 설정합니다.
travel_mode을 DRIVING 또는 TWO_WHEELER로 설정합니다.
routing_preference을 TRAFFIC_AWARE 또는 TRAFFIC_AWARE_OPTIMAL로 설정합니다.
Via 경유지를 사용하지 마세요.
2단계: 경로 토큰을 Navigation SDK에 전달
경로 토큰 저장: Navigation SDK에서 경로 토큰을 저장하는 문자열을 설정합니다. 예를 들면 다음과 같습니다.
letrouteToken="route token returned by Routes API"
반환된 경로 토큰의 예:
{// Other fields"routeToken":"CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",}
mapView.navigator setDestinations 메서드를 사용하여 Navigation SDK에 경로 토큰을 전달하고 경로 토큰을 만들 때 사용한 것과 동일한 대상 경유지를 지정합니다.
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){...}];
경로 토큰과 Navigation SDK의 상호작용 방식
Navigation SDK에서 생성된 경로와 경로 토큰의 계획된 경로가 상호작용하는 방식은 다음과 같습니다.
[null,null,["최종 업데이트: 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."]]
