이동 데이터를 가져올 때 백엔드에서 운전자의 이동 진행 상황을 자세히 설명하는 JSON 페이로드를 수신합니다. 이 페이로드를 파싱하여 이동을 모니터링하고, 디스패치 시스템을 업데이트하고, 현재 이동 상태를 해석하여 이동이 진행되거나 이동이 종료될 때 운전자의 다음 단계를 결정합니다.
데이터 페이로드 읽기
운전자가 내비게이션을 시작할 때, 경로를 따라 주기적으로 (기본적으로 60초마다), 운전자가 목적지에 도착할 때 Google 지도 또는 Waze가 이동 데이터 페이로드를 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를 사용하지 않습니다.
- 운전자가 인터넷에 연결되어 있습니다.
나머지 경로 데이터 처리 (Waze만 해당)
여행 생성 중에 남은 경로 보고를 사용 설정한 경우 백엔드에서 운전자의 현재 위치에서 최종 목적지까지의 남은 경로 폴리라인과 실시간 교통 상황을 수신합니다.
이 데이터를 수집하고 처리하여 애플리케이션에서 다음과 같은 여러 기능을 지원할 수 있습니다.
- 실시간 추적 지도 지원: 고객용 웹 또는 모바일 지도에 남은 경로 다중선을 렌더링하여 운전자의 여정을 표시합니다.
- 도착 예정 시간 정확성 향상: 도로에 스냅된 폴리라인과 교통량 간격 속도를 결합하여 내부 물류 또는 배송 도착 예측을 개선합니다.
- 라우팅 규정 준수 분석: 남은 경로 지오메트리를 예상 배차 경로와 비교하여 운전자 준수 여부를 평가합니다 (실시간 경로와 사전 계산된 경로가 다를 수 있는 이유에 관한 자세한 내용은 FAQ 참고).
GetTrip 요청을 전송하든 Google Cloud Pub/Sub를 사용하여 이벤트 기반 업데이트를 수신하든 Navigation Connect는 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만 해당)
여행 생성 시 경로 이탈 보고를 사용 설정한 경우 운전자가 경로를 벗어나면 API가 경로 이탈 메타데이터를 반환합니다. 다음과 같은 방법으로 이 데이터에 액세스할 수 있습니다.
- 주문형:
GetTrip메서드를 호출합니다. 서버는 마지막으로 알려진 편차 상태를 유지합니다. - 실시간: Google Cloud Pub/Sub을 구독합니다. 서비스는 감지 후 5초 이내에 기존
updated_trip이벤트를 사용하여 편차 업데이트를 게시합니다.
편차 페이로드 읽기
last_route_deviation 객체는 이벤트를 분석하는 데 도움이 되는 다음 메타데이터를 제공합니다.
| 필드 | 유형 | 설명 |
|---|---|---|
location |
LatLng |
클라이언트 기기에서 편차를 기록한 위도 및 경도 좌표입니다. |
source |
TriggerSource |
편차의 이유입니다. 이를 사용하여 드라이버가 예기치 않은 작업을 수행했는지 아니면 시스템 안내를 따랐는지 확인합니다.
|
client_timestamp |
Timestamp |
클라이언트 기기에서 편차를 감지한 시간입니다. |
server_timestamp |
Timestamp |
서버가 편차 업데이트를 처리한 시간입니다. |
이동 종료 상태 처리
운전자가 목적지에 도착하거나 내비게이션을 중지하면 페이로드가 다음 종료 상태 중 하나를 반환합니다. 이러한 상태를 사용하여 앱에서 적절한 다음 단계를 트리거합니다.
| 상태 | 설명 | 권장 조치 |
|---|---|---|
ARRIVED |
운전자가 목적지에 도착했습니다. | remainingDistanceMeters을 확인합니다. 운전자가 근처에 주차했지만 정확한 좌표에 주차하지 않은 경우 앱에서 도보 경로를 제공하는 것이 좋습니다. |
SUSPENDED |
운전자가 목적지에 도착하기 전에 세부 경로 안내 내비게이션을 수동으로 종료했습니다. Google 지도나 Waze는 운전자가 세션을 일찍 종료할 때 자동으로 앱으로 돌아가지 않으므로 운전자가 수동으로 돌아가기 버튼을 탭해야 합니다. |
운전자가 여정을 완료할 수 있도록 execution.location을 목적지와 비교합니다. 이동 거리가 남아 있으면 이동을 재개하거나 걷기 모드로 전환하는 버튼이나 링크를 제공합니다. |
FAILED |
기술적 오류로 인해 연결이 중단되었습니다. 앱에서 경로를 계산할 수 없거나 안전 경고가 표시되는 경우에 발생합니다. 운전자가 계속 탐색할 수 있지만 업데이트는 수신되지 않습니다. | 앱에서 수동 상태 추적으로 대체합니다. |
CLIENT_ERROR |
이 상태는 다음 이유 중 하나로 표시됩니다.
|
앱에서 수동 상태 추적으로 대체합니다. |