Gerar rotas e HEs para veículos grandes

Para quem é este guia:leia este guia se você for um desenvolvedor que cria serviços para planejamento e execução de viagens 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:este guia explica como usar a API Routes com o Large Vehicle Routing para solicitar rotas, distância percorrida, 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 informações sobre como realizar cálculos no nível da frota para veículos grandes usando a API Route Optimization, consulte a documentação de roteamento de caminhões da API Route Optimization.

O que você vai aprender

Você vai aprender a fazer o seguinte:

  • Crie uma solicitação de roteamento válida.
  • Especifique um perfil para seu veículo real usando dimensões, peso e outras características.
  • Interprete a resposta, incluindo o token de rota 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 Roteamento de veículos grandes. Entre em contato com seu representante do Google para concluir esta etapa.

Limitações

Antes de começar, confira as seguintes limitações e requisitos.

  • Disponibilidade geográfica: o roteamento de veículos grandes está disponível apenas nos 48 estados contíguos dos Estados Unidos.
  • O roteamento de veículos grandes é uma oferta em pré-lançamento. Os motoristas não podem confiar apenas nas rotas retornadas por essa API para garantir a segurança ou a legalidade. As rotas não são garantidas como 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.
  • Trajetos de melhor esforço. Em alguns casos, a API não consegue encontrar uma rota que obedeça totalmente às restrições de viagem. Em vez disso, ele retorna uma rota de "melhor esforço" que ainda pode passar por áreas restritas. A resposta da API Routes sinaliza claramente essas rotas no campo routeRestrictionsPartiallyIgnored. Planeje sua rota com cuidado nesses casos, de preferência usando outras fontes de dados. Não use um trajeto sinalizado como única fonte de verdade para planejamento ou navegação.
  • Recursos não compatíveis: estamos trabalhando para trazer mais funcionalidades a essa oferta, mas o trajeto para veículos grandes não é compatível com o seguinte:
    • Preços de pedágios para caminhões
    • Limites de velocidade
    • Roteamento para materiais perigosos radioativos
  • 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 a um endpoint de API da API Routes com parâmetros específicos que descrevem seu veículo.

Endpoints

Você pode usar dois endpoints para o roteamento de caminhões:

  • 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 rota.

Principais parâmetros de solicitação

No corpo da solicitação, inclua o seguinte:

  • 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 um perfil de veículo

Para enviar uma solicitação, você precisa fornecer um corpo 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 exige esses detalhes para retornar rotas que consideram restrições de trânsito com base nos atributos do seu veículo.

Medições do veículo

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 dos caminhões geralmente são expressas em pés ou metros, isso pode exigir uma conversão de unidades.

Conversão de imperial para métrico

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

Exemplo:

  • Largura: muitos trailers dos EUA têm uma largura de 8' 6", o que equivale a 2.590,8 mm. Arredondar para 2.591 mm indicaria que o veículo tem mais de 2,59 m, o que o classificaria como um veículo grande nas vias dos EUA. Isso resultaria em um trajeto calculado de acordo com restrições significativamente diferentes do pretendido.
  • Altura: um trajeto que passa por baixo de uma ponte de 3,35 m não é adequado para um caminhão-trator típico com 4,11 m de altura. No entanto, caminhões menores, com cerca de 3 metros, conseguiriam passar pelo viaduto. Por isso, é fundamental especificar os atributos do veículo com precisão.

Um diagrama que ilustra as dimensões de um caminhão em comparação com as dimensões de um viaduto

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

"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.

Campo Descrição Observações / valores
totalHeightMm A altura máxima do veículo. Em milímetros, arredondado para baixo. Consulte Conversão de unidades imperiais para métricas para mais detalhes sobre o arredondamento.
totalWidthMm A largura máxima do veículo. Em milímetros, arredondado para baixo.
totalLengthMm O comprimento total combinado do veículo e de qualquer reboque. Em milímetros, arredondado para baixo.
totalWeightKg O peso bruto do veículo (incluindo reboques e carga). Em quilogramas, arredondado para baixo.
totalAxleCount O número total de eixos do veículo e de todos os reboques. Exato.
trailerInfo (opcional) Uma matriz de objetos, um para cada trailer. Omita para um veículo sem reboques, como um caminhão baú.
hazardousGoodsTypes (opcional) Uma matriz que especifica materiais perigosos a bordo. EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

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 a rota tem uma ou mais restrições aplicáveis ao seu veículo.

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

Pedágios

Para preferir trajetos 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 solicitação de API Routes, os trajetos que contêm vias com pedágio serão anotados de acordo com esse campo.

Exemplo de solicitação curl completa

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

Interpretar a resposta de computeRoutes

Uma solicitação bem-sucedida para a API Routes retorna um objeto de resposta JSON que contém 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 roteamento de veículos grandes usa um novo modelo treinado com base nas velocidades de viagem observadas de caminhões reais na rede viária. Também é possível usar esse recurso para calcular a ETA 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. É um token opaco que representa a rota calculada exata. Você transmite esse token para o SDK Navigation para garantir que o motorista veja o mesmo trajeto específico para caminhões. Para mais detalhes sobre como fazer isso, consulte o guia Fornecer navegação orientada.

Verificar se há indicadores de segurança na rota

Ao receber uma resposta, a primeira coisa que você deve fazer é verificar as flags de segurança do trajeto. 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 flag para responder à pergunta: "Este trajeto foi sinalizado por um possível problema?"

  • false(ou omitido da resposta): a rota não é sinalizada. O sistema encontrou um trajeto que acreditamos estar totalmente em conformidade com os parâmetros fornecidos na solicitação.
  • true: a rota é sinalizada. 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 muito cuidado.

Exemplo: resposta do computeRoutes

Este é um exemplo de resposta para a solicitação mostrada acima. Note que no travelAdvisory objeto, a flag routeRestrictionsPartiallyIgnored não está incluída. Isso indica que a rota não está sinalizada e acredita-se que ela esteja totalmente em conformidade com o perfil do veículo.

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

Receber uma matriz de rotas de caminhão

Para calcular os tempos de viagem de várias viagens possíveis de uma só vez, use o endpoint computeRouteMatrix para planejamento de alto nível e compare de maneira eficiente os tempos de viagem e as distâncias entre várias origens e destinos. Por exemplo, você pode usar esse recurso 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 para sua finalidade, emita uma solicitação computeRoutes para receber os detalhes e o token da rota do veículo proposto.

Para usar computeRouteMatrix, especifique o vehicleInfo em cada objeto de origem.

Exemplo de solicitação

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

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

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

Próximas etapas