경로 계획하기

참고: Navigation SDK가 계획된 경로를 따르는 방식에 대한 업데이트(새 betterRouteTimeTolerance 필드 포함)는 점진적으로 출시되며 2026년 10월 22일까지 모든 프로젝트에서 사용할 수 있습니다. 그때까지는 Routes API가 betterRouteTimeTolerance를 포함하는 요청을 거부할 수 있습니다.

앱에서 사용자에게 제공하는 경로를 계획해야 하는 경우가 있습니다. Routes API, Routes Preferred API 또는 Route Optimization API의 경로 토큰을 사용하면 계획된 경로에 대해 다음 두 가지를 지정할 수 있습니다.

• 경로의 다중선

• 경로 목표

예를 들어 다음과 같은 라우팅 목표가 있을 수 있습니다.

• 배송 시간 최소화: 음식을 배달하는 비즈니스는 음식을 배달하는 데 걸리는 시간을 최소화하려고 할 수 있습니다.

• 이동 시간 또는 연료 소비 최소화: 물류 비즈니스에서 운전자의 효율성을 개선하고 연료 비용을 줄이려고 할 수 있습니다.

• 목적지까지의 시간 최소화: 서비스 파견 작업에서 작업자가 작업 요청을 처리하는 데 걸리는 시간을 최소화해야 할 수 있습니다.

• 비용 절감 및 안전 개선: 차량 공유 비즈니스에서는 탑승자에게 더 저렴한 비용이 들고 안전상의 이유로 특정 지역을 피하는 경로를 찾고자 할 수 있습니다.

중요: 운전자가 이동하는 경로는 계획된 경로와 다를 수 있습니다. 교통 상황이나 도로 상황이 변경되거나, 차량이 계획된 경로를 벗어나거나, 더 빠른 경로로 전환하면 이동 중에 경로가 변경될 수 있습니다. Navigation SDK는 새 경로를 계산할 때마다 경로 토큰에 설정된 경로 옵션(예: 유료 도로 제외)을 사용합니다.

경로 토큰을 사용하여 경로를 계획하는 방법에 관한 자세한 내용은 Routes API의 경로 토큰 가져오기 및 Route Optimization API의 전환 다중선 및 경로 토큰을 참고하세요.

경로 목표에 경로 토큰을 사용하는 이유

Routes API, Routes Preferred API 또는 Route Optimization API의 경로 토큰을 사용하면 제공되는 경로를 더 세부적으로 제어할 수 있습니다.

• Navigation SDK에서 사용할 경로를 미리 계획합니다.

• Navigation SDK에서 사용할 최적의 경로 선택 Routes API에서 경로를 생성할 때 경로 토큰을 요청하면 생성된 각 경로에 대한 경로 토큰을 받게 됩니다. 그런 다음 Navigation SDK에 전달할 때 사용할 경로의 토큰을 선택할 수 있습니다.

• ETA 및 거리 추정치를 포함하여 사전에 가격을 추정합니다. 실제 비용과 시간은 다를 수 있지만 이 추정치를 사용하면 예상 경로 비용과 실제 경로 비용 간의 차이를 줄일 수 있습니다.

• 친환경 경로 또는 최단 경로와 같은 고급 경로 목표를 지정합니다.

도움말: 경로 토큰은 특정 출발지와 목적지, 특정 시간에 사용됩니다. 새 경로 토큰을 사용하려면 새 Routes API, Routes Preferred API 또는 Route Optimization API 요청을 해야 합니다.

경로 토큰의 작동 방식

Routes API, Routes Preferred API 또는 Route Optimization API를 사용하여 경로 목표를 사용해 경로를 계획할 수 있습니다. 이러한 API에서 반환된 경로 토큰을 Navigation SDK에 전달하여 차량의 경로를 안내할 수 있습니다.

경로 토큰을 요청하고 사용할 때 발생하는 상황은 다음과 같습니다.

1. Routes API, Routes Preferred API 또는 Route Optimization API는 경로 다중선과 경로 목표가 포함된 암호화된 경로 토큰을 반환합니다.

2. 경로 토큰을 Navigation SDK에 전달합니다.

3. Navigation SDK는 더 빠른 경로가 있더라도 계획된 경로에서 내비게이션을 시작합니다.

4. 이동 중에 교통 상황이나 도로 상황이 변경되거나 차량이 계획된 경로를 벗어나면 Navigation SDK는 경로 토큰에 설정된 경로 목표 및 경로 옵션을 따르는 새 경로를 계산합니다.

이 프로세스는 실제 경로가 계획된 경로에 최대한 가깝도록 합니다.

계획된 경로를 정확하게 따르지 않을 수 있는 이유

내비게이션은 계획된 경로에서 시작되지만 실제 경로는 다음과 같은 상황에서 다를 수 있습니다.

• 차량이 계획된 출발지에서 출발합니다.
• 이동 중에 교통 상황이나 도로 상황이 변경됩니다.
• 차량이 계획된 경로를 벗어납니다.

이러한 차이는 계획한 거리, 도착 예정 시간, 기타 중요한 이동 품질에 영향을 미칠 수 있습니다.

도움말: Navigation SDK에서 목적지를 설정할 때마다 항상 새 경로 토큰을 요청하고 비즈니스에 영향을 미치지 않도록 약간의 변형을 계획하는 것이 좋습니다.

경로 토큰을 사용하여 경로 계획

다음 단계에 설명된 대로 경로 토큰을 만든 후 Navigation SDK에 전달하여 경로를 계획할 수 있습니다.

1단계: Routes API, Routes Preferred API 또는 Route Optimization API를 사용하여 경로 토큰 만들기

1. 다음 방법 중 하나를 사용하여 경로 토큰을 요청합니다.

   • Routes API: computeRoutes. Routes API에서 경로 토큰을 요청하는 방법에 관한 자세한 내용은 경로 계산 및 경로 토큰 가져오기를 참고하세요.

   • Routes Preferred API: computeCustomRoutes. Routes Preferred API에서 경로 토큰을 요청하는 방법에 관한 자세한 내용은 경로 계획을 참고하세요.

   • Route Optimization API: optimizeTours 또는 batchOptimizeTours Route Optimization API에서 경로 토큰을 요청하는 방법에 대한 자세한 내용은 전환 다중선 및 경로 토큰을 참고하세요.

2. 경로 토큰 사용 요구사항을 충족하도록 Routes API 또는 Routes Preferred API 요청을 설정합니다.

   • travelMode를 DRIVE 또는 TWO_WHEELER으로 설정합니다.
   • routingPreference를 TRAFFIC_AWARE 또는 TRAFFIC_AWARE_OPTIMAL으로 설정합니다.
   • Via 경유지를 사용하지 마세요.

참고: 내비게이션 지점 토큰을 사용하여 경로 토큰에 입구, 하역장, 지정된 승차 구역과 같은 정확한 출발지 및 목적지 값을 지정할 수 있습니다.

2단계: Navigation SDK에 경로 토큰 전달

1. 경로 토큰 저장: Navigation SDK에서 경로 토큰을 저장할 문자열을 설정합니다. 예를 들면 다음과 같습니다.

   let routeToken = "route token returned by Routes API"
   

   반환된 경로 토큰의 예는 다음과 같습니다.

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. mapView.navigator.setDestinations를 사용하여 Navigation SDK에 경로 토큰을 전달합니다. 경로 토큰을 만들 때 사용한 것과 동일한 목적지 경유지를 지정합니다.

   mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})
   

   참고: 동일한 경로를 다시 이동해야 하는 경우 새 경로 토큰을 요청하세요.

   setDestinations 메서드는 요청 상태를 콜백에 전달합니다. 사용자의 위치에서 지정된 목적지까지의 경로를 찾으면 상태는 .OK (GMSRouteStatusOK)입니다.

여러 경유지 시나리오

경유지는 최대 25개까지 구성할 수 있습니다.

setDestinations 메서드는 여러 경유지가 있는 여정을 지원하지 않습니다. continueToNextDestinationWithCompletion()를 사용하여 경유지를 여정의 다음 구간으로 진행합니다.

주의: continueToNextDestinationWithCompletion() 메서드를 호출하면 잘못된 도착 이벤트가 발생하여 방금 완료된 목적지가 다시 선택된 것처럼 보일 수 있습니다.

예

다음 코드 예는 계획된 경로를 검색하는 방법을 보여줍니다.

Swift

let location = CLLocationCoordinate2D(latitude: 47.67, longitude: -122.20)
let waypoint1 = GMSNavigationWaypoint(location: location, title: "waypoint from location")!
let waypoint2 = GMSNavigationWaypoint(placeID: "samplePlaceID", title: "waypoint from Place ID")!

let routeToken = "route token returned by Routes API"
mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})

Objective-C

CLLocationCoordinate2D location = CLLocationCoordinate2DMake(47.67, -122.20);
GMSNavigationWaypoint *waypoint1 = [[GMSNavigationWaypoint alloc] initWithLocation:location title:@"waypoint from location"];
GMSNavigationWaypoint *waypoint2 = [[GMSNavigationWaypoint alloc] initWithPlaceID:@"samplePlaceID"
                                                                            title:@"waypoint from Place ID"];
NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinations:@[waypoint1, waypoint2]
                        routeToken:routeToken
                          callback:^(GMSRouteStatus routeStatus){...}];

경로 토큰과 Navigation SDK의 상호작용 방식

Navigation SDK는 계획된 경로를 다음과 같이 처리합니다.

• 이전에 설정된 모든 대상을 재정의합니다.

• 차량 시작 위치를 사용합니다.

• 도로 및 교통 상황에 따라 조정합니다. 계획된 경로를 정확하게 따르지 않는 이유를 참고하세요.

• 이동 중에 새 경로를 계산할 때를 포함하여 앱의 다음 설정 대신 경로 토큰에 설정된 경로 옵션을 사용합니다.

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • 앱에 설정된 이동 모드

• 경로를 계산하거나 조정할 때 다음 설정을 따릅니다.

  • 경로 토큰의 경로 목표(예: 친환경 경로 또는 최단 경로) Navigation SDK에서 경로를 조정해야 하는 경우 경로 토큰을 요청할 때 지정한 경로 목표를 사용합니다.

  • 앱의 경유지 관련 옵션(예: 도로 측면 환경설정) 경로 토큰을 요청할 때 지정한 것과 동일한 경유지 관련 옵션을 사용합니다.