Gezi verilerinizi aldığınızda arka ucunuz, sürücünün gezi ilerleme durumunu ayrıntılı olarak açıklayan JSON yükleri alır. Geziyi izlemek, sevk sistemlerinizi güncellemek ve sürücünün ilerleme durumuna veya gezinin sona ermesine göre bir sonraki adımını belirlemek için mevcut gezi durumlarını yorumlamak üzere bu yükleri ayrıştırın.
Veri yükünü okuma
Google Haritalar veya Waze, sürücü navigasyonu başlattığında, rota boyunca düzenli olarak (varsayılan olarak her 60 saniyede bir) ve sürücü hedefe ulaştığında gezi verisi yüklerini Navigation Connect sunucularına gönderir. Her JSON mesajı, sürücünün yola sabitlenmiş koordinatları, katettiği mesafe ve tahmini varış zamanı (TVS) dahil olmak üzere ilgili gezi verilerini içerir. Bu güncellemeler sürücünün etkin, gerçek zamanlı rotasını yansıttığından arka ucunuz tarafından önceden hesaplanan rotalardan farklı olabilir (SSS bölümüne bakın).
Aşağıdaki kod örneğinde, bir sürücü King's Cross'tan Central St. Giles'a giden bir gezi için navigasyonu başlattığında gezi verileri yükü gösterilmektedir.
{
"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
}
}
Etkin gezi durumlarını izleme
Başarılı bir başlangıç yapıldığını onaylamak ve ilerleme durumunu izlemek için her yükteki state alanını değerlendirin.
| Durum | Açıklama |
|---|---|
NEW |
Gezi oluşturuldu ancak sürücü henüz navigasyonu başlatmadı. |
ENROUTE |
Sürücü, hedefe doğru aktif olarak ilerliyor. Gezinin kimliğinin doğrulandığını ve başarıyla başlatıldığını onaylamak için bu durumu kullanın. |
Eklenen durakları işleme
Sürücüler, navigasyon sırasında rotalarına durak ekleyebilir. Eşleşme varsa Navigation Connect, JSON veri yükündeki execution.stopAddedInRoute alanını true olarak ayarlar. Navigation Connect API, sürücüyü orijinal hedefe doğru takip etmeye devam eder. Tahmini varış zamanı (ETA), mesafe ve süre gibi metrikler, eklenen durakları içerecek şekilde artar.
Durak ekleme davranışı, navigasyon uygulamasına bağlıdır ve uygulamanın standart işlevine uygundur:
- Google Haritalar: Sürücüler rotalarına birden fazla durak ekleyebilir.
- Waze: Sürücüler yalnızca bir durak ekleyebilir. Sürücü başka bir durak eklemeye çalışırsa Waze, durağı mevcut rotaya eklemek yerine yeni bir navigasyon oturumu başlatmasını ister.
Bu özelliği desteklemek için arka uç girişlerinizi ayarlamanız gerekmez.
Kimlik doğrulama ve başlatma sorunlarını giderme
ENROUTE durumunu almazsanız büyük olasılıkla bir kimlik doğrulama hatası oluşmuştur. Sık karşılaşılan nedenler arasında yanlış yazılmış API parametreleri veya süresi dolmuş bir gezi jetonu yer alır. İlk CreateTrip yanıtınızda jetonun geçerlilik bitiş zamanını kontrol edin.
Durum NEW yerine ENROUTE olarak değişmiyorsa sürücünün cihazı kimlik doğrulamasını engelliyor olabilir. Navigation Connect, bu durumlarda hata mesajı göndermez. Aşağıdakileri doğrulayın:
- Sürücünün cihazında Waze 5.15.5 veya sonraki bir sürümü ya da Google Haritalar 26.14 veya sonraki bir sürümü yüklü olmalıdır.
- Sürücü, Android Auto veya Apple CarPlay kullanmıyor.
- Sürücünün etkin bir internet bağlantısı olmalıdır.
Kalan rota verilerini işleme
Gezi oluşturma sırasında kalan rota raporlamasını etkinleştirdiyseniz arka ucunuz, sürücünün mevcut konumundan son hedefine kadar olan kalan rota çoklu çizgisini ve anlık trafik koşullarını alır. Sürücülerin Android'de Waze 5.20.0.2 veya sonraki bir sürüme, iOS'te 5.20.0.1 veya sonraki bir sürüme ya da Android için Google Haritalar'ın 26.27 veya sonraki bir sürümüne ihtiyacı vardır.
Uygulamalarınızdaki çeşitli özellikleri desteklemek için bu verileri alıp işleyebilirsiniz. Örneğin:
- Canlı takip haritalarını destekleme: Sürücünün yolculuğunu görünür kılmak için müşteriye yönelik bir web veya mobil haritada kalan rotanın çoklu çizgisini oluşturun.
- TVS doğruluğunu artırma: Dahili lojistik veya teslimat varış tahminlerini iyileştirmek için yola sabitlenmiş çoklu çizgi ile trafik aralığı hızlarını birleştirin.
- Rota uygunluğunu analiz etme: Sürücünün rotaya uyup uymadığını değerlendirmek için kalan rota geometrisini beklenen sevkiyat rotalarıyla karşılaştırın (Anlık ve önceden hesaplanan rotaların neden farklı olabileceğiyle ilgili ayrıntılar için SSS bölümüne bakın).
Navigation Connect, Google Cloud Pub/Sub'ı kullanarak GetTrip isteği göndermeniz veya etkinliğe dayalı güncellemeler almanız fark etmeksizin kalan rota ayrıntılarını execution.remainingRoute alanında döndürür. Ancak yükün bu verileri nasıl biçimlendirdiği ve yapılandırdığı, kullandığınız alma yöntemine bağlıdır.
GetTrip yöntemi
GetTrip yöntemini çağırdığınızda, çoklu çizginin yanıt biçimi, isteğinizde belirttiğiniz routePolylineFormat parametresine bağlıdır. Daha fazla bilgi için Çoklu çizgi biçimlerini özelleştirme başlıklı makaleyi inceleyin.
Navigation Connect, tüm çoklu çizgi biçimleri için trafiği, execution.remainingRoute.trafficInformation alanında ayrı bir SpeedReadingInterval nesnesi listesi olarak döndürür. Bu nesneler, aşağıdaki değerleri kullanarak trafik kategorilerini çoklu çizgi dizinleriyle eşler:
startPolylinePointIndex: Çoklu çizgi üzerindeki trafik aralığının başlangıç dizini.endPolylinePointIndex: Trafik aralığının bitiş dizini.speed: Bu segmentin trafik kategorisi:NORMAL,SLOWveyaTRAFFIC_JAM.
Google Cloud Pub/Sub güncellemeleri
Pub/Sub ile gezi verilerini aldığınızda güncellemeler, kalan rota verilerini her zaman execution.remainingRoute alanında birleştirilmiş bir GeoJSON FeatureCollection olarak döndürür.
Bu biçim, çoklu çizgi geometrisini doğrudan trafik hızlarıyla birleştirerek dizinleri manuel olarak eşleme ihtiyacını ortadan kaldırır.
Örnek Pub/Sub yükünü inceleme
Aşağıdaki kod örneğinde, bir Pub/Sub mesajının updatedTrip nesnesindeki execution.remainingRoute alanında döndürülen GeoJSON yapısı gösterilmektedir:
{ "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" } } ] }
Yük boyutunu optimize etme
Koordinat dizileri büyük olduğundan, kalan rota verilerini Pub/Sub mesajlarınıza dahil etmek, yük boyutunu önemli ölçüde artırabilir (mesaj başına 13-14 KB'a kadar). Yüksek sıklıkta güncelleme alıyorsanız bu hacim, arka uç işleme yükünü ve kullanım maliyetlerini artırabilir.
Akışınızı optimize etmek için gezi oluşturma sırasında TripConfig nesnenizde pubsubFieldMask parametresini kullanarak ağır alanları hariç tutun. Ayrıntılar için İsteğe bağlı yapılandırmalar başlıklı makaleyi inceleyin.
Rota sapmalarını yönetme (yalnızca Waze)
Sürücülerin Waze 5.22 veya sonraki bir sürümü kullanması gerekir.
Gezi oluşturma sırasında rota sapması raporlamasını etkinleştirdiyseniz sürücü rotadan çıktığında API, rota sapması meta verilerini döndürür. Bu verilere aşağıdaki yöntemlerle erişebilirsiniz:
- İsteğe bağlı:
GetTripyöntemini çağırın. Sunucu, bilinen son sapma durumunu korur. - Gerçek Zamanlı Analiz: Google Cloud Pub/Sub'a abone olun. Hizmet, sapma güncellemelerini mevcut
updated_tripetkinliğini kullanarak algılamadan sonraki 5 saniye içinde yayınlar.
Sapma yükünü okuma
last_route_deviation nesnesi, etkinliği analiz etmenize yardımcı olmak için aşağıdaki meta verileri sağlar.
| Alan | Tür | Açıklama |
|---|---|---|
location |
LatLng |
İstemci cihazın sapmayı kaydettiği enlem ve boylam koordinatları. |
source |
TriggerSource |
Sapmanın nedeni Sürücünün beklenmedik bir işlem yapıp yapmadığını veya sistem talimatlarını uygulayıp uygulamadığını belirlemek için bu bilgiyi kullanın:
|
client_timestamp |
Timestamp |
İstemci cihazın sapmayı algıladığı zaman. |
server_timestamp |
Timestamp |
Sunucunun sapma güncellemesini işlediği zaman. |
Gezi sonu durumlarını işleme
Sürücü hedefe ulaştığında veya navigasyonu durdurduğunda yük, aşağıdaki bitiş durumlarından birini döndürür. Uygulamanızda uygun sonraki adımları tetiklemek için bu durumları kullanın.
| Durum | Açıklama | Önerilen işlem |
|---|---|---|
ARRIVED |
Sürücü hedefe ulaştı. | remainingDistanceMeters bağlantısını kontrol edin. Sürücü yakına park ettiyse ancak tam koordinatlarda değilse uygulamanızda yaya yol tarifi vermeyi düşünebilirsiniz. |
SUSPENDED |
Sürücü, hedefe varmadan önce adım adım rotadan manuel olarak çıktı. Google Haritalar veya Waze, oturumdan erken çıkan sürücüleri uygulamanıza otomatik olarak geri döndürmediğinden sürücünün geri dön düğmesine manuel olarak dokunması gerekir. |
Sürücülerin yolculuklarını tamamlamasına yardımcı olmak için execution.location ile varış noktasını karşılaştırın. Kalan mesafe varsa geziye devam etmek veya yürüme moduna geçmek için bir düğme ya da bağlantı sağlayın. |
FAILED |
Teknik bir hata nedeniyle bağlantı kesildi. Bu durum, uygulama rota hesaplayamadığında veya bir güvenlik uyarısı gösterildiğinde ortaya çıkar. Sürücü hâlâ navigasyonu kullanıyor olabilir ancak güncellemeleri almazsınız. | Uygulamanızda manuel durum takibine geri dönün. |
CLIENT_ERROR |
Bu durum, aşağıdaki nedenlerden biriyle gösterilir:
|
Uygulamanızda manuel durum takibine geri dönün. |