Büyük araç rotaları ve tahmini varış zamanları oluşturma

Bu kılavuz kimler için hazırlanmıştır? Kamyon veya diğer büyük araçları kullanarak gezi planlama ve yürütme hizmetleri geliştiren bir geliştiriciyseniz bu kılavuzu okuyun. Alakalı kullanım alanları arasında seyahat sürelerini ve mesafelerini hesaplama, TVS'leri hesaplama veya bir navigasyon uygulaması tarafından kullanılacak rotalar oluşturma yer alır.

Bu kılavuzun kapsamı: Bu kılavuzda, büyük araç rotası ile Routes API'yi kullanarak rota, seyahat mesafesi, tahmini seyahat süresi ve ticari kamyon veya yolcu otobüsü gibi büyük bir aracın belirli özelliklerini hesaba katan tahmini varış sürelerini nasıl isteyeceğiniz açıklanmaktadır.

Route Optimization API'yi kullanarak büyük araçlar için filo düzeyinde hesaplamaların nasıl yapılacağı hakkında bilgi edinmek istiyorsanız Route Optimization Truck Routing belgelerini inceleyin.

Neler öğreneceksiniz?

Aşağıdaki işlemleri nasıl yapacağınızı öğreneceksiniz:

• Geçerli bir rota isteği oluşturun.
• Boyut, ağırlık ve diğer özellikleri kullanarak gerçek dünyadaki aracınızın bilgilerini belirtin.
• Rota jetonu ve seyahat güvenliği işaretleri de dahil olmak üzere yanıtı yorumlayın.

Ön koşullar

1. Google Cloud projeniz oluşturulmuş ve Routes API etkinleştirilmiş olmalıdır.
2. Projeniz Büyük Araç Rotası için temel hazırlığı yapılmış olmalıdır. Büyük araç rotası sınırlı sayıda müşteri tarafından kullanılabilir. Erişim isteğinde bulunmak için bizimle iletişime geçin.

Sınırlamalar

Başlamadan önce aşağıdaki sınırlamaları ve şartları bilmeniz gerekir.

• Coğrafi kullanılabilirlik: Büyük araç rotası, ABD'nin bitişik 48 eyaletinde (genel kullanıma sunulmuştur) ve Japonya'da (deneysel) kullanılabilir. Alaska, Hawaii veya ABD bölgelerinde kullanılamaz.
• Sürücü danışmanlığı ve güvenlik. Sürücüler, güvenli veya yasal olması için yalnızca bu API tarafından döndürülen rotalara güvenmemelidir. Rotaların araç için uygun olduğu garanti edilmez ve bu rotaları takip etmek, sürücüleri alçak köprüler veya büyük araçların yasak olduğu yollar gibi tehlikelere maruz bırakabilir.
• En iyi performans gösteren rotalar. Bazı durumlarda API, seyahat kısıtlamalarına tamamen uyan bir rota bulamayabilir. Bunun yerine, kısıtlanmış alanlardan geçebilecek "en iyi" rotayı döndürür. Routes API yanıtı, bu rotaları routeRestrictionsPartiallyIgnored alanında açıkça işaretler. Bu gibi durumlarda rotanızı dikkatli bir şekilde planlayın. İdeal olarak diğer kaynak verilerini kullanın. İşaretlenmiş bir rotayı planlama veya navigasyon için tek doğruluk kaynağı olarak kullanmayın.
• Desteklenmeyen özellikler: Büyük araç rotası aşağıdakileri desteklemez:
  • Kamyon geçiş ücretleri
  • Hız sınırları
  • Radyoaktif tehlikeli maddeler için rota belirleme
• Kullanım sınırları: Tüm istekler standart saniyedeki sorgu sayısı (QPS) sınırlarına tabidir.

Kamyon rotası isteği oluşturma

Kamyon rotası almak için aracınızı açıklayan belirli parametreleri içeren bir HTTPS isteğini Routes API uç noktasına gönderirsiniz. Bu bölümdeki kavramlar hem tek rota hem de rota matrisi istekleri için geçerlidir.

Uç noktalar

Kamyon rotası için iki uç nokta kullanabilirsiniz:

• computeRoutes: Bir başlangıç noktası ile bir hedef arasında tek bir rota hesaplar.
• computeRouteMatrix: Bir başlangıç ve hedef matrisi için mesafeyi ve süreyi hesaplar ancak rota çoklu çizgisi döndürmez.

Temel istek parametreleri

Kamyon rotasını etkinleştirmek için istek gövdenize aşağıdaki parametreleri eklemeniz gerekir:

• travelMode: Bu değeri TRUCK olarak ayarlayın.
• routingPreference: Bu değeri TRAFFIC_AWARE_OPTIMAL olarak ayarlayın.
• routeModifiers: Bu nesne, aracınızın özelliklerini tanımladığınız vehicleInfo nesnesini içerir. vehicleInfo nesnesi aşağıda ayrıntılı olarak açıklanmıştır.

Araç özelliklerini belirtme

İstek göndermek için aracınızı açıklayan bir vehicleInfo nesnesi içeren istek gövdesi sağlamanız gerekir. Bu bilgileri, gerçek dünyadaki aracınızın fiziksel ayrıntılarıyla eşleşen bir teknik özellik olarak düşünebilirsiniz. Hizmet, aracınızın özelliklerine göre yol kısıtlamalarını dikkate alan rotalar döndürmek için bu bilgilere ihtiyaç duyar.

Araç ölçümleri

Alan adlarında belirtildiği gibi, araç ağırlığını kilogram, araç boyutlarını ise milimetre cinsinden girin. Örneğin, toplam yükseklik milimetre (totalHeightMm) cinsinden belirtilmelidir. Kamyon boyutları genellikle fit veya metre cinsinden ifade edildiğinden birim dönüştürme gerekebilir.

İngiliz ölçü biriminden metrik sisteme dönüştürme

İngiliz ölçü birimlerinden dönüştürme yaparken standart yol ve alt geçit boyut sınırlarının yanı sıra her zaman aracınızın boyutlarını da göz önünde bulundurun. Bu, özellikle kesirli değerlerde önemli olabilir. Gerçek aracın boyutuna bağlı olarak, kesirli bir değerin yukarı yuvarlanması araç için aşırı kısıtlayıcı bir rotaya neden olabilir.

Örneğin:

• Genişlik: ABD'deki birçok römorkun genişliği 8 fit 6 inçtir. Bu da 2.590,8 mm'ye karşılık gelir. 2.591 mm'ye yuvarlamak,aracın 2,59 metreden daha uzun olduğunu gösterir. Bu da aracın ABD yollarında büyük araç olarak sınıflandırılmasına neden olur. Bu durumda, amaçlanandan anlamlı bir şekilde farklı kısıtlamalara göre hesaplanan bir rota ortaya çıkar.
• Yükseklik: 3,35 metrelik bir köprünün altından geçen rota, 4,11 metre yüksekliğindeki tipik bir çekici-treyler için uygun olmaz. Ancak yaklaşık 3 metre yüksekliğindeki daha küçük kamyonlar alt geçitten geçebilir. Bu nedenle, araç özelliklerinizi doğru şekilde belirtmeniz çok önemlidir.

Aşağıdaki kod snippet'inde örnek bir vehicleInfo nesnesi gösterilmektedir:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

vehicleInfo nesne alanı

Aşağıdaki tabloda, istekle birlikte gönderebileceğiniz tüm araç ve yük tanımları gösterilmektedir.

Alan maskelerini kullanma

En iyi sonuçlar için, yanıtta tam olarak istediğiniz alanları belirtmek üzere isteğinize X-Goog-FieldMask başlığını ekleyin. Alan maskeleri, gecikmeyi azaltır ve önemli tavsiye alanlarını almanızı sağlar. Rotanın aracınız için geçerli bir veya daha fazla kısıtlaması olup olmadığını gösterdiğinden alan maskesine her zaman en azından routes.travelAdvisory.routeRestrictionsPartiallyIgnored değerini ekleyin.

Routes API ile FieldMasks hakkında daha fazla bilgi için bu makaleyi inceleyin.

Ücretli geçişler

Ücretsiz rotaları tercih etmek için bir isteğin routeModifiers özelliğinde avoidTolls değerini belirtin. Rota değiştiriciler hakkında daha fazla bilgi için Kaçınılacak rota özelliklerini belirtme başlıklı makaleyi inceleyin.

avoidTolls değerinin belirtilmesi, yanıtta ücretsiz rotaların döndürüleceğini garanti etmez. Bazı durumlarda, başlangıç ve varış noktası arasında seyahat etmek için paralı yol kullanılması gerekir. Routes API isteğinizin alan maskesine routes.warnings değerini eklerseniz paralı yollar içeren rotalar bu alanda buna göre etiketlenir.

Diğer yönlendirme davranışları

travelMode değerini TRUCK olarak ayarladığınızda API, rotayı büyük araçların manevra kabiliyetine göre otomatik olarak optimize eder. Oluşturulan rotalarda U dönüşlerinden kaçınılır ve küçük yollar yerine eyaletler arası yollar ile otoyollar tercih edilir. Bu davranışları etkinleştirmek için ek parametreler veya değiştiriciler ayarlamanız gerekmez.

computeRoutes ile tek bir rota hesaplama

Bir başlangıç noktası ile bir hedef arasında kamyona özel rota hesaplamak için computeRoutes uç noktasını kullanın.

Örnek computeRoutes isteği

Tipik bir yarı römork kamyon için tam curl isteği aşağıda verilmiştir. Bu örnekte uç nokta, başlıklar ve istek gövdesi yer alır.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

Örnek computeRoutes yanıtı

Bu, yukarıda gösterilen önceki isteğe verilen örnek bir yanıttır. travelAdvisory nesnesinde routeRestrictionsPartiallyIgnored işaretinin bulunmadığını unutmayın. Bu, rotanın işaretlenmediğini ve aracın özellikleriyle tamamen uyumlu olduğunu gösterir.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

computeRoutes yanıtını yorumlama

computeRoutes uç noktasına gönderilen başarılı bir istek, bir veya daha fazla olası rota içeren bir JSON yanıt nesnesi döndürür.

Önemli yanıt alanları

• Kodlanmış rota geometrisi: routes.polyline. Bu, rotayı haritada göstermek için kullanılabilir.
• Tahmini gezi süresi: routes.duration (saniye cinsinden). Büyük araç rotası gezi süresi, yol ağındaki gerçek kamyonların gözlemlenen seyahat hızları üzerine eğitilmiş yeni bir model kullanır. Tahmini varış süresini (TVS) hesaplamak için de kullanılabilir. Bunun için tahmini yolculuk süresi, beklenen kalkış saatine eklenir.
• Rotanın toplam mesafesi: routes.distanceMeters (metre cinsinden).
• Rota jetonu: routes.routeToken. Bu, hesaplanan rotayı tam olarak temsil eden opak bir jetondur. Sürücüye kamyonlara özel aynı rotanın gösterilmesi için bu jetonu Navigation SDK'ya iletirsiniz. Ayrıntılı bilgi için Android veya iOS için Gezinme SDK'sı kılavuzlarına bakın.

Rota güvenliği işaretlerini kontrol etme

Yanıt aldığınızda ilk yapmanız gereken, rota güvenliği işaretlerini kontrol etmektir. Sağlanan bir rota, araca uygun olmamasına neden olan bir veya daha fazla kısıtlama içeriyorsa travelAdvisory.routeRestrictionsPartiallyIgnored alanı true olarak ayarlanır.

Bu alan, "Bu rota olası bir sorun için işaretlendi mi?" sorusunu yanıtlamak için bir işaret görevi görür.

• false(veya yanıttan çıkarılır): Rota işaretlenmez. Sistem, istekte sağladığınız parametrelerle tam uyumlu olduğu düşünülen bir rota buldu.
• true: Rota işaretlenir. Sistem, tamamen uyumlu bir rota bulamadı ve güvenli veya yasal olmayabilecek "en iyi" rotayı döndürdü. Bu rota çok dikkatli kullanılmalıdır.

Rota matrisi hesaplama (computeRouteMatrix)

Birçok başlangıç ve varış noktası arasındaki seyahat sürelerini ve mesafeleri verimli bir şekilde karşılaştırmak için computeRouteMatrix uç noktasını kullanın. Örneğin, yeni bir teslim alma konumuna en yakın kamyonu bulmak için kullanabilirsiniz. Amacınıza uygun araç başlangıç noktasını belirledikten sonra, önerilen aracın rota ayrıntılarını ve rota jetonunu almak için computeRoutes isteği gönderebilirsiniz.

computeRouteMatrix özelliğini kullanmak için vehicleInfo değerini isteğin kökünde değil, her bir origin nesnesinin içinde belirtirsiniz.

Örnek computeRouteMatrix isteği

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

Örnek computeRouteMatrix yanıtı

Yanıt, her nesnenin bir başlangıç-hedef çifti için süreyi ve distanceMeters değerini içerdiği bir dizidir.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

Sonraki adımlar

• Adım adım rota sağlama: Android veya iOS için Navigation SDK'da routeToken kullanmayı öğrenin.
• Filo düzeyinde optimizasyon yapma: Büyük Araç Rotası Belirleme ile Route Optimization API'yi kullanın.
• API referansı: Olası tüm alanların ve değerlerin tam listesi için Routes API referansına bakın.