Gerar rotas e HEs para veículos grandes

Para quem este guia é destinado:leia este guia se você for um desenvolvedor que cria serviços para planejamento de viagens e execução usando caminhões ou outros veículos grandes. Os casos de uso relevantes incluem o cálculo de tempos e distâncias de viagem, o cálculo de ETAs ou a geração de rotas que serão usadas por um aplicativo de navegação.

O que este guia aborda:como usar a API Routes com o Large Vehicle Routing para solicitar rotas, distância de viagem, tempo de viagem previsto e ETAs que consideram os atributos específicos de um veículo grande, como um caminhão comercial ou um ônibus de passageiros.

Para saber como realizar cálculos no nível da frota para veículos grandes usando a API Route Optimization, consulte a documentação sobre roteamento de caminhões da API Route Optimization.

O que você vai aprender

Você vai aprender como fazer o seguinte:

• Criar uma solicitação de roteamento válida.
• Especifique as informações do seu veículo real, usando dimensões, peso e outras características.
• Interprete a resposta, incluindo o token de trajeto e as flags de segurança de viagem.

Pré-requisitos

1. Seu projeto na nuvem do Google Cloud precisa ser criado, e a API Routes precisa estar ativada.
2. Seu projeto precisa ser provisionado para o Large Vehicle Routing. O trajeto para veículos grandes está disponível para um conjunto limitado de clientes. Entre em contato para solicitar acesso.

Limitações

Antes de começar, é preciso estar ciente das seguintes limitações e requisitos.

• Disponibilidade geográfica: o trajeto de veículos grandes está disponível nos 48 estados contíguos dos Estados Unidos (disponibilidade geral) e no Japão (experimental). Ele não está disponível no Alasca, no Havaí nem nos territórios dos EUA.
• Avisos e segurança do motorista. Os motoristas não devem depender apenas das rotas retornadas por essa API para garantir a segurança ou a legalidade. Não há garantia de que as rotas sejam adequadas para o veículo, e segui-las pode expor os motoristas a perigos, como pontes baixas ou vias em que veículos grandes são proibidos.
• Rotas de melhor esforço. Em alguns casos, a API não consegue encontrar um trajeto que atenda totalmente às restrições de viagem. Em vez disso, ela retorna uma rota de "melhor esforço" que ainda pode atravessar áreas restritas. A resposta da API Routes sinaliza claramente essas rotas no campo routeRestrictionsPartiallyIgnored. Nesses casos, planeje seu trajeto com cuidado, de preferência usando outros dados de origem. Não use um trajeto sinalizado como única fonte de verdade para planejamento ou navegação.
• Recursos não compatíveis: o trajeto de veículos grandes não é compatível com o seguinte:
  • Preços de pedágio para caminhões
  • Limites de velocidade
  • Rotas para materiais radioativos perigosos
• Limites de uso:todas as solicitações estão sujeitas aos limites padrão de consultas por segundo (QPS).

Criar uma solicitação de rota de caminhão

Para receber uma rota de caminhão, envie uma solicitação HTTPS para um endpoint da API Routes com parâmetros específicos que descrevem seu veículo. Os conceitos desta seção se aplicam a solicitações de rota única e de matriz de rotas.

Endpoints

É possível usar dois endpoints para rotas de caminhão:

• computeRoutes: calcula um único trajeto entre uma origem e um destino.
• computeRouteMatrix: calcula a distância e a duração de uma matriz de origens e destinos, mas não retorna uma polilinha de trajeto.

Principais parâmetros de solicitação

No corpo da solicitação, inclua os seguintes parâmetros para ativar o trajeto de caminhão:

• travelMode: defina esse valor como TRUCK.
• routingPreference: defina esse valor como TRAFFIC_AWARE_OPTIMAL.
• routeModifiers: esse objeto contém o objeto vehicleInfo, em que você define os atributos do veículo. O objeto vehicleInfo é descrito em detalhes abaixo.

Especificar atributos do veículo

Para enviar uma solicitação, é necessário fornecer um corpo de solicitação com um objeto vehicleInfo que descreva seu veículo. Pense nessas informações como uma especificação que corresponde aos detalhes físicos do seu veículo no mundo real. O serviço precisa desses detalhes para retornar rotas que considerem as restrições de trânsito com base nos atributos do veículo.

Medições de veículos

Informe o peso do veículo em quilogramas e as dimensões em milímetros, conforme indicado pelos nomes dos campos. Por exemplo, a altura total precisa ser fornecida em milímetros (totalHeightMm). Como as dimensões do caminhão geralmente são expressas em pés ou metros, pode ser necessário converter as unidades.

Conversão de imperial para métrico

Ao converter unidades imperiais, sempre considere as dimensões específicas do seu veículo, além dos limites de tamanho padrão de estradas e passagens subterrâneas. Isso pode ser especialmente importante com valores fracionários. Dependendo do tamanho real do veículo, arredondar um valor fracionário pode resultar em um trajeto excessivamente restritivo para o veículo.

Exemplo:

• Largura: muitos trailers dos EUA têm uma largura de 8' 6", que se converte em 2.590,8 mm. Arredondar para 2.591 mm indicaria que o veículo tem mais de 8' 6", o que o classificaria como um veículo de grande porte nas estradas dos EUA. Isso resultaria em um trajeto calculado de acordo com restrições significativamente diferentes das pretendidas.
• Altura: uma rota que passa por baixo de uma ponte de 3,35 m não é adequada para um caminhão com 4,11 m de altura. No entanto, caminhões menores, com cerca de 3 metros, poderiam passar por ali. Por isso, é fundamental especificar os atributos do veículo com precisão.

Confira a seguir um snippet de código que mostra um objeto vehicleInfo de exemplo:

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

Campos de objeto vehicleInfo

A tabela a seguir mostra todas as definições de veículo e carga que podem ser enviadas com a solicitação.

Usar máscaras de campo

Para melhores resultados, inclua o cabeçalho X-Goog-FieldMask na solicitação para especificar exatamente os campos que você quer na resposta. As máscaras de campo reduzem a latência e garantem que você receba campos de aviso importantes. No mínimo, sempre inclua routes.travelAdvisory.routeRestrictionsPartiallyIgnored na máscara de campo, já que isso indica se o trajeto tem uma ou mais restrições que se aplicam ao seu veículo.

Para mais detalhes sobre FieldMasks com a API Routes, consulte este artigo.

Pedágios

Para preferir rotas sem pedágio, especifique avoidTolls na propriedade routeModifiers de uma solicitação. Para mais informações sobre modificadores de rota, consulte Especificar recursos de rota a serem evitados.

Especificar avoidTolls não garante rotas sem pedágio na resposta. Em alguns casos, é necessário usar uma via com pedágio para viajar entre a origem e o destino. Se você incluir routes.warnings na máscara de campo da sua solicitação de API Routes, os trajetos com vias com pedágio serão anotados de acordo nesse campo.

Outros comportamentos de roteamento

Quando você define travelMode como TRUCK, a API otimiza automaticamente o trajeto para a manobrabilidade de veículos grandes. As rotas geradas evitam retornos e dão preferência a rodovias e estradas em vez de vias menores. Não é necessário definir outros parâmetros ou modificadores para ativar esses comportamentos.

Calcular um único trajeto com computeRoutes

Use o endpoint computeRoutes para calcular uma rota específica para caminhões entre uma origem e um destino.

Exemplo de solicitação computeRoutes

Veja uma solicitação curl completa para um caminhão semirreboque típico. Este exemplo inclui o endpoint, os cabeçalhos e o corpo da solicitação.

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
      }]
    }
  }
}'

Exemplo de resposta de computeRoutes

Este é um exemplo de resposta para a solicitação anterior mostrada acima. No objeto travelAdvisory, a flag routeRestrictionsPartiallyIgnored não está incluída. Isso indica que o trajeto não está sinalizado e é considerado totalmente compatível com os atributos do veículo.

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

Interpretar a resposta de computeRoutes

Uma solicitação bem-sucedida ao endpoint computeRoutes retorna um objeto de resposta JSON com uma ou mais rotas possíveis.

Campos de resposta principais

• Geometria do trajeto codificada: routes.polyline. Isso pode ser usado para renderizar o trajeto em um mapa.
• Duração estimada da viagem: routes.duration (em segundos). A duração da viagem de rotas de veículos grandes usa um novo modelo treinado com base nas velocidades de viagem observadas de caminhões reais na rede viária. Ela também pode ser usada para calcular o HEC, adicionando a duração estimada da viagem ao horário de partida esperado.
• Distância total do trajeto: routes.distanceMeters (em metros).
• Token de rota: routes.routeToken. Esse é um token opaco que representa o trajeto exato calculado. Você transmite esse token ao SDK de navegação para garantir que o motorista veja o mesmo trajeto específico para caminhões. Para mais detalhes, consulte os guias do SDK do Navigation para Android ou iOS.

Verificar se há sinalizações de segurança de rota

Ao receber uma resposta, a primeira coisa a fazer é verificar se há sinalizações de segurança de rota. Se uma rota fornecida tiver uma ou mais restrições que a tornem inadequada para o veículo, o campo travelAdvisory.routeRestrictionsPartiallyIgnored será definido como true.

Esse campo funciona como uma sinalização para responder à pergunta: "Este trajeto está sinalizado para um possível problema?"

• false(ou omitido da resposta): o trajeto não está sinalizado. O sistema encontrou um trajeto que parece estar totalmente em conformidade com os parâmetros fornecidos na solicitação.
• true: o trajeto está sinalizado. O sistema não encontrou um trajeto totalmente compatível e retornou um trajeto de "melhor esforço" que pode não ser seguro ou legal. Essa rota precisa ser usada com extrema cautela.

Calcular uma matriz de rotas (computeRouteMatrix)

Use o endpoint computeRouteMatrix para comparar de forma eficiente os tempos de viagem e as distâncias entre muitas origens e destinos. Por exemplo, você pode usá-lo para encontrar o caminhão mais próximo de um novo local de retirada. Depois de identificar a origem do veículo que você quer usar, emita uma solicitação computeRoutes para receber os detalhes e o token do trajeto do veículo proposto.

Para usar computeRouteMatrix, especifique o vehicleInfo em cada objeto origin, em vez de na raiz da solicitação.

Exemplo de solicitação computeRouteMatrix

{
  "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"
}

Exemplo de resposta de computeRouteMatrix

A resposta é uma matriz em que cada objeto contém a duração e o distanceMeters para um par de origem e destino.

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

Próximas etapas

• Oferecer navegação guiada: saiba como usar o routeToken no SDK de navegação para Android ou iOS.
• Otimizar a frota: use a API Route Optimization com o roteamento de veículos grandes.
• Referência da API: para uma lista completa de todos os campos e valores possíveis, consulte a Referência da API Routes.