이동 데이터 처리

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

데이터 페이로드 읽기

운전자가 내비게이션을 시작할 때, 경로를 따라 주기적으로 (기본적으로 60초마다), 운전자가 목적지에 도착할 때 Google 지도 또는 Waze에서 이동 데이터 페이로드를 Navigation Connect 서버로 전송합니다. 각 JSON 메시지에는 운전자의 도로에 스냅된 좌표, 이동 거리, 도착 예정 시간 (ETA)을 비롯한 이동 데이터가 포함되어 있습니다.

다음 코드 샘플은 운전자가 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
  }
}

활성 여행 상태 모니터링

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

상태 설명
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를 사용하고 있지 않습니다.
  • 운전자가 인터넷에 연결되어 있습니다.

남은 경로 데이터 처리 (Waze만 해당)

여행 생성 중에 남은 경로 보고를 사용 설정한 경우 백엔드에서 운전자의 현재 위치에서 최종 목적지까지의 활성 경로 폴리라인과 실시간 교통상황을 수신합니다.

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

  • 실시간 추적 지도 지원: 고객 대상 웹 또는 모바일 지도에 남은 경로 다중선을 렌더링하여 운전자의 여정을 파악할 수 있도록 합니다.
  • ETA 정확도 개선: 도로에 스냅된 폴리라인과 교통 간격 속도를 결합하여 내부 물류 또는 배송 도착 예측을 개선합니다.
  • 경로 준수 분석: 남은 경로 지오메트리를 예상 배차 경로와 비교하여 운전자의 준수 여부를 평가합니다.

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로 이동 데이터를 가져오면, 업데이트는 항상 통합 GeoJSON FeatureCollection에 남은 경로 데이터를 반환합니다. execution.remainingRoute 필드에 있습니다.

이 형식은 폴리라인 지오메트리를 교통 속도와 직접 결합하여 색인을 수동으로 매핑할 필요가 없습니다.

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 매개변수를 사용하여 대용량 필드를 제외합니다. 자세한 내용은 선택적 구성을 참고하세요.

여행 종료 상태 처리

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

상태 설명 행동 요령
ARRIVED 운전자가 목적지에 도착했습니다. remainingDistanceMeters를 확인합니다. 운전자가 정확한 좌표가 아닌 근처에 주차한 경우 앱에서 도보 경로를 제공하는 것이 좋습니다.
SUSPENDED 운전자가 목적지에 도착하기 전에 세부 경로 안내 내비게이션을 수동으로 종료했습니다.
Google 지도 또는 Waze는 세션을 일찍 종료할 때 운전자를 앱으로 자동 반환하지 않으므로 운전자가 반환 버튼을 수동으로 탭해야 합니다. 		운전자가 여정을 완료할 수 있도록 execution.location을 목적지와 비교합니다. 거리가 남아 있으면 여행을 재개하거나 도보 모드로 전환하는 버튼 또는 링크를 제공합니다.
FAILED 기술적 오류로 인해 연결이 중단되었습니다. 앱에서 경로를 계산할 수 없거나 안전 경고가 표시되는 경우에 발생합니다. 운전자가 계속 내비게이션하고 있을 수 있지만 업데이트는 수신되지 않습니다. 앱에서 수동 상태 추적으로 대체합니다.
CLIENT_ERROR 이 상태는 다음 중 한 가지 이유로 표시됩니다. 앱에서 수동 상태 추적으로 대체합니다.