Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

경로 계획하기

앱에서 사용자에게 제공하는 경로를 계획해야 하는 경우가 있습니다. 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에 전달할 때 사용할 경로의 토큰을 선택할 수 있습니다.
ETA 및 거리 추정치를 포함하여 사전에 가격을 추정합니다. 실제 비용과 시간은 다를 수 있지만 이 추정치를 사용하면 예상 경로 비용과 실제 경로 비용 간의 차이가 줄어듭니다.
친환경 경로 또는 최단 경로와 같은 고급 경로 목표를 지정합니다.

경로 토큰의 작동 방식

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는 경로 토큰에 설정된 경로 목표 및 경로 옵션을 따르는 새 경로를 계산합니다.

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

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

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

차량이 계획된 출발지에서 멀리 떨어진 곳에서 출발합니다.
이동 중에 교통 상황이나 도로 상황이 변경되는 경우
차량이 계획된 경로를 벗어납니다.

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

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

다음 단계에 설명된 대로 경로 토큰을 만든 후 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 요청을 설정합니다.
- travelMode를 DRIVE 또는 TWO_WHEELER으로 설정합니다.
- routingPreference를 TRAFFIC_AWARE 또는 TRAFFIC_AWARE_OPTIMAL으로 설정합니다.
- Via 경유지를 사용하지 마세요.

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

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

let routeToken = "route token returned by Routes API"

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

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

mapView.navigator의 setDestinationsWithToken:completionHandler: 메서드를 사용하여 Navigation SDK에 경로 토큰을 전달합니다. Navigation SDK는 경로 토큰에서 목적지와 경로 옵션을 가져오므로 경유지를 전달할 필요가 없습니다.

앱에 설정된 이동 수단(예: mapView.travelMode)은 다음 값 중 하나여야 합니다.
- .driving(GMSNavigationTravelModeDriving): 운전 중입니다. 이 값은 기본값이므로 대부분의 앱에서 변경할 필요가 없습니다.
- .twoWheeler(GMSNavigationTravelModeTwoWheeler): 이륜차
다른 이동 수단을 사용하면 .travelModeUnsupported(GMSRouteStatusTravelModeUnsupported) 오류가 발생하며 요청이 실패합니다. 지원되는 값 중 하나를 사용하면 경로에서 경로 토큰의 이동 수단을 사용합니다. 예를 들어 앱에서 운전을 사용하고 경로 토큰이 이륜차 경로인 경우 Navigation SDK는 이륜차 경로를 제공합니다. 경로에서 사용하는 이동 수단을 확인하려면 resolvedParameters.travelMode를 확인하세요. 자세한 내용은 확정된 라우팅 옵션을 참조하세요.

참고: 앱에서 11.3 이전 버전의 Navigation SDK를 사용하는 경우 지원 중단된 setDestinations:routeToken:callback: 메서드를 대신 사용하고 경로 토큰을 만드는 데 사용한 것과 동일한 목적지 경유지를 전달합니다.
완료 핸들러에서 경로 상태를 확인합니다. Navigation SDK가 경로 계산을 완료하면 GMSNavigationRouteDescription를 완료 핸들러에 전달합니다. 차량 위치에서 경로 토큰의 목적지까지의 경로를 찾으면 경로 설명의 routeStatus가 .OK(GMSRouteStatusOK)이고 안내를 시작할 수 있습니다. 그렇지 않으면 완료 핸들러도 실패를 설명하는 NSError를 수신합니다. 예를 들면 다음과 같습니다.
```
mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  if routeDescription?.routeStatus == .OK {
    self?.mapView.navigator?.isGuidanceActive = true
  }
}
```

Navigation SDK에서 경로 토큰을 적용했는지 확인하기

경로 상태가 .OK이면 Navigation SDK가 경로를 찾았지만 계획된 경로가 아닐 수도 있습니다. 경로가 계획된 경로와 일치하는지 확인하려면 완료 핸들러에서 다음 단계를 따르세요.

경로 설명의 routeStatus이 .OK인지 확인합니다. Navigation SDK는 경로를 찾은 경우에만 경로 토큰 세부정보를 제공합니다. 자세한 내용은 2단계를 참고하세요.
GMSNavigationRouteTokenExecutionDetails 프로토콜을 준수하는 객체인 경로 설명의 routeTokenExecutionDetails를 가져옵니다. 서버에서 경로 토큰 세부정보를 제공하지 않으면 이 속성은 nil입니다.
실행 세부정보의 tokenExecutionStatus 속성을 확인합니다. .tokenSuccessfullyApplied인 경우 경로는 계획된 경로와 일치합니다. 다른 상태는 경로가 계획된 경로와 다를 수 있음을 의미합니다. 각 상태에 대한 자세한 내용은 토큰 실행 상태 값을 참조하세요.
선택사항: 상태가 .tokenSuccessfullyApplied인 경우 동일한 실행 세부정보의 resolvedParameters 속성을 확인하여 경로에서 사용하는 경로 옵션(예: 통행료 회피 여부)을 확인합니다. 자세한 내용은 확정된 라우팅 옵션을 참조하세요.

토큰 실행 상태 값

routeStatus가 .OK이면 토큰 실행 상태로 안내를 시작할 수 있습니다. 상태는 경로가 계획된 경로를 따르는지 여부를 알려줍니다.

상태	계획된 경로를 따릅니다.	설명
`.tokenSuccessfullyApplied`	예	Navigation SDK가 경로 토큰을 적용했습니다.
`.tokenAppliedWithLocationMismatch`	꼭 그렇지는 않습니다.	Navigation SDK에서 계획된 경로를 다시 빌드할 수 없으며 기기가 경로 토큰의 출발지에서 25m 이상 떨어져 있습니다. 경로는 여전히 경로 토큰의 목적지와 경로 옵션을 사용합니다.
`.tokenIgnoredOther`	꼭 그렇지는 않습니다.	Navigation SDK가 다른 이유로 계획된 경로를 다시 만들 수 없습니다(예: 계획된 경로의 도로가 폐쇄됨). 경로는 여전히 경로 토큰의 목적지와 경로 옵션을 사용합니다.
`.noTokenProvided`	해당 없음	경로 요청에 경로 토큰이 포함되지 않았습니다.
`.unknown`	알 수 없음	상태를 알 수 없습니다.

경로가 계획된 경로를 따르지 않고 정확한 경로가 중요한 경우(예: 가격을 계산하는 데 사용한 경우) 상태를 기록하거나 차량의 현재 위치에서 새 경로 토큰을 요청합니다.

해결된 라우팅 옵션

resolvedParameters는 GMSNavigationRouteTokenResolvedParameters 프로토콜을 준수하는 객체이거나, 라우팅 옵션을 사용할 수 없는 경우 nil입니다. 다음과 같은 속성이 있습니다.

travelMode: 경로에서 사용하는 이동 수단(예: .driving(GMSNavigationTravelModeDriving)). Navigation SDK는 경로에서 일치하는 값이 없는 이동 수단을 사용하거나 이동 수단을 사용할 수 없는 경우에도 .driving를 보고합니다.
avoidTolls: 경로가 유료 도로를 피하는지 여부입니다.
avoidHighways: 경로가 고속도로를 제외하는지 여부입니다.
avoidFerries: 경로가 페리를 피하는지 여부입니다.
avoidTunnels: 가능한 경우 터널을 피하도록 경로가 계산되었는지 여부입니다.
avoidVignettes: 가능한 경우 통행료 비네트를 피하도록 경로가 계산된 국가입니다. 유니코드 CLDR 두 글자 리전 코드(예: 스위스의 경우 CH)로 표시됩니다.
rerouteStrategy: 이동 중에 라우팅 백엔드가 새 경로를 계산하는 데 사용하는 전략입니다. 전략에는 경로 토큰의 경로 매개변수를 사용하여 새 경로를 계산하는 .bestBasedOnTokenParameters(GMSNavigationRerouteStrategyBestBasedOnTokenParameters)가 포함됩니다.

토큰 실행 상태가 .tokenSuccessfullyApplied가 아니면 Navigation SDK는 travelMode, avoidTolls, avoidHighways, avoidFerries만 보고합니다. 경로 토큰을 요청할 때 터널이나 통행료 비네트를 피하도록 요청했더라도 다른 속성에는 기본값이 있습니다. avoidTunnels는 false(NO)이고, avoidVignettes는 비어 있으며, rerouteStrategy는 .unknown(GMSNavigationRerouteStrategyUnknown)입니다.

예

다음 코드 예는 경로 토큰을 사용하여 경로를 계획하고, Navigation SDK가 토큰을 적용했는지 확인하고, 안내를 시작하는 방법을 보여줍니다.

Swift

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

Objective-C

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

여러 경유지 시나리오

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

Navigation SDK는 다음 목적지로 자동으로 이동하지 않습니다. 차량이 경유지에 도착하면 continueToNextDestinationWithCompletion:를 호출하여 다음 구간을 시작합니다. 이는 중간 경유지가 있는 경로 토큰에도 적용됩니다. 다음 목적지로 이동하면 Navigation SDK는 새 경로를 계획하는 대신 경로 토큰의 경로를 계속 따릅니다.

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

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

이전에 설정된 모든 도착 페이지를 재정의합니다.
차량 시작 위치를 사용합니다.
도로 및 교통 상황에 따라 조정됩니다. 계획된 경로를 정확하게 따르지 않는 이유를 참고하세요.

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

경로를 계산하거나 조정할 때 다음 설정을 따릅니다.
- 경로 토큰의 경로 목표(예: 친환경 경로 또는 최단 경로) Navigation SDK에서 경로를 조정해야 하는 경우 경로 토큰을 요청할 때 지정한 경로 목표를 사용합니다.
- 경로 토큰의 경유지 관련 옵션(예: 도로변 환경설정)