이동 데이터 처리

이동 데이터를 검색하면 백엔드에서 운전자의 이동 진행 상황을 자세히 설명하는 JSON 페이로드를 수신합니다. 이러한 페이로드를 파싱하여 이동을 모니터링하고, 배차 시스템을 업데이트하고, 현재 이동 상태를 해석하여 운전자가 이동을 진행하거나 이동이 완료될 때 운전자의 다음 단계를 결정합니다.

데이터 페이로드 읽기

Google 지도 또는 Waze는 운전자가 내비게이션을 시작할 때, 경로를 따라 주기적으로 (기본적으로 60초마다), 운전자가 목적지에 도착할 때 이동 데이터 페이로드를 Navigation Connect 서버로 전송합니다. 각 JSON 메시지에는 운전자의 도로 스냅 좌표, 이동 거리, 도착 예정 시간(ETA)을 비롯한 관련 이동 데이터가 포함됩니다. 이러한 업데이트는 운전자의 활성 실시간 경로를 반영하므로 백엔드에서 미리 계산한 경로와 다를 수 있습니다(FAQ 참고).

다음 코드 샘플은 운전자가 King's Cross에서 Central St. Giles까지의 이동을 위해 내비게이션을 시작할 때의 이동 데이터 페이로드를 보여줍니다.

{
  "name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
  "state": "ENROUTE",
  "execution": {
    "origin": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      }
    },
    "destination": {
      "point": {
        "latitude": 51.515598,
        "longitude": -0.1277623
      }
    },
    "location": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      },
      "sourceTime": "2025-05-30T12:37:26Z",
      "serverTime": "2025-05-30T12:37:26.221069Z"
    },
    "traveledDuration": "0s",
    "remainingDuration": "990s",
    "traveledDistanceMeters": 0,
    "remainingDistanceMeters": 2879,
    "stopAddedInRoute": false
  }
}

활성 이동 상태 모니터링

성공적인 시작을 확인하고 진행 상황을 모니터링하려면 모든 페이로드에서 state 필드를 평가합니다.

상태 설명
NEW 여정이 생성되었지만 운전자가 아직 내비게이션을 시작하지 않았습니다.
ENROUTE 운전자가 목적지로 이동 중입니다. 이 상태를 사용하여 이동이 인증되고 성공적으로 시작되었는지 확인합니다.

추가된 경유지 처리

운전자는 내비게이션 중에 경로에 경유지를 추가할 수 있습니다. 이 경우 Navigation Connect는 JSON 데이터 페이로드에서 execution.stopAddedInRoute 필드를 true로 설정합니다. Navigation Connect API는 원래 목적지를 향해 운전자를 계속 추적합니다. 도착 예정 시간 (ETA), 거리, 소요 시간과 같은 측정항목이 추가된 경유지를 포함하도록 증가합니다.

경유지 추가 동작은 내비게이션 앱에 따라 다르며 표준 기능과 일치합니다.

  • Google 지도: 운전자는 경로에 여러 경유지를 추가할 수 있습니다.
  • Waze: 운전자는 경유지를 하나만 추가할 수 있습니다. 운전자가 다른 경유지를 추가하려고 하면 Waze는 현재 경로에 경유지를 추가하는 대신 새 탐색 세션을 시작하라는 메시지를 표시합니다.

이 기능을 지원하기 위해 백엔드 입력을 조정할 필요는 없습니다.

인증 및 시작 문제 해결하기

ENROUTE 상태를 수신하지 않으면 인증 오류가 발생했을 수 있습니다. 일반적인 원인으로는 API 매개변수의 맞춤법 오류 또는 만료된 이동 토큰이 있습니다. 초기 CreateTrip 응답에서 토큰 만료 시간을 확인합니다.

상태가 NEW에서 ENROUTE로 변경되지 않으면 운전자의 기기가 인증을 차단하고 있을 수 있습니다. 이러한 경우 Navigation Connect는 오류 메시지를 전송하지 않습니다. 다음을 확인합니다.

  • 운전자가 Waze 버전 5.15.5 이상 또는 Google 지도 버전 26.14 이상을 설치했습니다.
  • 운전자가 Android Auto 또는 Apple CarPlay를 사용하지 않습니다.
  • 운전자가 인터넷에 연결되어 있습니다.

나머지 경로 데이터 처리

여정 생성 중에 남은 경로 보고를 사용 설정한 경우 백엔드는 운전자의 현재 위치에서 최종 목적지까지의 남은 경로 다중선과 실시간 교통 상황을 수신합니다. 운전자는 Android에서 Waze 버전 5.20.0.2 이상, iOS에서 5.20.0.1 이상 또는 Android용 Google 지도 버전 26.27 이상이 필요합니다.

이 데이터를 수집하고 처리하여 애플리케이션에서 다음 예시를 비롯한 여러 기능을 지원할 수 있습니다.

  • 실시간 추적 지도 지원: 고객용 웹 또는 모바일 지도에 남은 경로 다중선을 렌더링하여 운전자의 여정을 보여줍니다.
  • 도착예정시간 정확성 개선: 도로에 스냅된 다중선과 교통정보 구간 속도를 결합하여 내부 물류 또는 배송 도착 예측을 개선합니다.
  • 경로 규정 준수 분석: 남은 경로 도형을 예상 배송 경로와 비교하여 운전자의 준수 여부를 평가합니다(실시간 경로와 사전 계산된 경로가 다를 수 있는 이유에 관한 자세한 내용은 FAQ 참고).

Navigation Connect는 GetTrip 요청을 전송하든 Google Cloud Pub/Sub를 사용하여 이벤트 기반 업데이트를 수신하든 관계없이 execution.remainingRoute 필드에 남은 경로 세부정보를 반환합니다. 하지만 페이로드가 이 데이터를 형식화하고 구조화하는 방법은 사용하는 검색 방법에 따라 다릅니다.

GetTrip 메서드

GetTrip 메서드를 호출할 때 다중선의 응답 형식은 요청에 지정한 routePolylineFormat 매개변수에 따라 달라집니다. 자세한 내용은 다중선 형식 맞춤설정을 참고하세요.

모든 다중선 형식에서 Navigation Connect는 execution.remainingRoute.trafficInformation 필드에 SpeedReadingInterval 객체의 별도 목록으로 트래픽을 반환합니다. 이러한 객체는 다음 값을 사용하여 교통정보 카테고리를 다중선 색인에 매핑합니다.

  • startPolylinePointIndex: 다중선에서 교통정보 간격의 시작 색인입니다.
  • endPolylinePointIndex: 트래픽 간격의 종료 색인입니다.
  • speed: 이 세그먼트의 트래픽 카테고리입니다(NORMAL, SLOW 또는 TRAFFIC_JAM).

Google Cloud Pub/Sub 업데이트

Pub/Sub를 사용하여 이동 데이터를 검색하면 업데이트는 항상 execution.remainingRoute 필드의 통합 GeoJSON FeatureCollection에 남은 경로 데이터를 반환합니다.

이 형식은 다중선 도형을 교통 속도와 직접 결합하므로 색인을 수동으로 매핑할 필요가 없습니다.

Pub/Sub 페이로드 예시 보기

다음 코드 샘플은 Pub/Sub 메시지의 updatedTrip 객체 내 execution.remainingRoute 필드에 반환된 GeoJSON 구조를 보여줍니다.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.3934, 37.7955],
          [-122.4010, 37.7980]
        ]
      },
      "properties": {
        "speed": "SLOW"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.4010, 37.7980],
          [-122.4058, 37.8025],
          [-122.4187, 37.8021]
        ]
      },
      "properties": {
        "speed": "NORMAL"
      }
    }
  ]
}
    

페이로드 크기 최적화

좌표 배열은 크기 때문에 Pub/Sub 메시지에 나머지 경로 데이터를 포함하면 페이로드 크기가 크게 증가할 수 있습니다 (메시지당 최대 13~14KB). 업데이트를 자주 수신하는 경우 이 볼륨으로 인해 백엔드 처리 부하와 사용 비용이 증가할 수 있습니다.

스트림을 최적화하려면 여행을 만드는 동안 TripConfig 객체에서 pubsubFieldMask 매개변수를 사용하여 무거운 필드를 제외합니다. 자세한 내용은 선택적 구성을 참조하세요.

경로 이탈 처리(Waze만 해당)

운전자는 Waze 버전 5.22 이상이 필요합니다.

여정 생성 중에 경로 이탈 보고를 사용 설정한 경우 운전자가 경로를 이탈하면 API가 경로 이탈 메타데이터를 반환합니다. 다음과 같은 방법으로 이 데이터에 액세스할 수 있습니다.

  • 주문형: GetTrip 메서드를 호출합니다. 서버는 마지막으로 알려진 편차 상태를 유지합니다.
  • 실시간: Google Cloud Pub/Sub를 구독합니다. 서비스는 감지 후 5초 이내에 기존 updated_trip 이벤트를 사용하여 편차 업데이트를 게시합니다.

편차 페이로드 읽기

last_route_deviation 객체는 이벤트를 분석하는 데 도움이 되는 다음 메타데이터를 제공합니다.

필드 유형 설명
location LatLng 클라이언트 기기에서 편차를 기록한 위도 및 경도 좌표입니다.
source TriggerSource 편차의 이유입니다. 이를 사용하여 운전자가 예상치 못한 조치를 취했는지 또는 시스템 안내를 따랐는지 확인합니다.
  • DRIVER_INITIATED_REROUTE: 운전자가 적극적으로 선택했습니다(예: 잘못된 방향으로 회전하거나 새 경로를 수동으로 선택).
  • SYSTEM_INITIATED_REROUTE: 내비게이션 앱이 새 경로를 계산했습니다 (예: 교통 상황 변화 또는 도로 폐쇄로 인해).
client_timestamp Timestamp 클라이언트 기기에서 편차를 감지한 시간입니다.
server_timestamp Timestamp 서버에서 편차 업데이트를 처리한 시간입니다.

이동 종료 상태 처리

운전자가 목적지에 도착하거나 내비게이션을 중지하면 페이로드는 다음 종료 상태 중 하나를 반환합니다. 이러한 상태를 사용하여 앱에서 적절한 다음 단계를 트리거합니다.

상태 설명 권장 조치
ARRIVED 운전자가 목적지에 도착했습니다. remainingDistanceMeters을 확인합니다. 운전자가 정확한 좌표가 아닌 근처에 주차한 경우 앱에서 도보 경로를 제공하는 것이 좋습니다.
SUSPENDED 운전자가 목적지에 도착하기 전에 세부 경로 안내 내비게이션을 수동으로 종료했습니다.
Google 지도 또는 Waze는 운전자가 세션을 일찍 종료할 때 자동으로 앱으로 돌아가지 않으므로 운전자가 수동으로 돌아가기 버튼을 탭해야 합니다.
운전자가 여정을 완료할 수 있도록 execution.location를 목적지와 비교합니다. 거리가 남아 있으면 이동을 재개하거나 도보 모드로 전환하는 버튼이나 링크를 제공합니다.
FAILED 기술적 오류로 인해 연결이 중단되었습니다. 이는 앱에서 경로를 계산할 수 없거나 안전 경고가 표시되는 경우에 발생합니다. 운전자는 계속 탐색 중일 수 있지만 업데이트는 수신되지 않습니다. 앱에서 수동 상태 추적으로 대체합니다.
CLIENT_ERROR 이 상태는 다음 중 한 가지 이유로 표시됩니다.
  • 운전자가 동의를 취소합니다.
  • 운전자가 Android Auto 또는 Apple CarPlay와 같이 지원되지 않는 플랫폼을 사용합니다.
  • 앱이 여러 이동에서 이동 토큰을 재사용합니다. 예를 들어 Navigation Connect는 이동 목적지를 변경하거나 완료된 이동을 업데이트하는 요청을 거부합니다.
  • 운전자가 이동 중 어느 시점에 미국에 있지만 설정 중에 앱을 인증할 때 앱에서 미국 내 데이터 공유를 사용 설정하지 않았습니다.
앱에서 수동 상태 추적으로 대체합니다.