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 trajetos que serão usados por um aplicativo de navegação.

O que este guia aborda:este guia aborda como usar a API Routes com o roteamento de veículos grandes para solicitar trajetos, 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 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:

  • Construir uma solicitação de roteamento válida.
  • Especificar as informações do veículo real, usando dimensões, peso e outras características.
  • Interpretar a resposta, incluindo o token de rota e as sinalizações de segurança de viagem.

Pré-requisitos

  1. Seu projeto 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. O roteamento de veículos grandes está disponível para um grupo limitado de clientes. Entre em contato conosco para solicitar acesso

Limitações

Antes de começar, você precisa estar ciente das seguintes limitações e requisitos.

  • Disponibilidade geográfica: o roteamento de veículos grandes está disponível nos 48 estados contíguos dos Estados Unidos (disponibilidade geral) e Japão (experimental). Ele não está disponível no Alasca, no Havaí ou nos territórios dos EUA.
  • Avisos e segurança do motorista. Os motoristas não devem confiar apenas nos trajetos retornados por essa API para serem seguros ou legais. Não há garantia de que os trajetos sejam adequados para o veículo, e segui-los pode expor os motoristas a perigos, como pontes baixas ou estradas em que veículos grandes são proibidos.
  • Trajetos de melhor esforço. Em alguns casos, a API não consegue encontrar um trajeto que esteja totalmente em conformidade com as restrições de viagem. Em vez disso, ela retorna um trajeto de "melhor esforço" que ainda pode atravessar áreas restritas. A resposta da API Routes sinaliza claramente esses trajetos no campo routeRestrictionsPartiallyIgnored. Planeje seu trajeto com cuidado nesses casos, de preferência usando outros dados de origem. Não use um trajeto sinalizado como uma única fonte de verdade para planejamento ou navegação.
  • Recursos não compatíveis: o roteamento de veículos grandes não oferece suporte ao seguinte:
    • Preços de pedágio de caminhões
    • Limites de velocidade
    • Roteamento de materiais perigosos radioativos
  • Limites de uso: todas as solicitações estão sujeitas a limites padrão de consultas por segundo (QPS).

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

Para receber um trajeto 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. Os conceitos desta seção se aplicam a solicitações de trajeto único e de matriz de trajetos.

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

Principais parâmetros de solicitação

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

  • 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, você precisa fornecer um corpo de solicitação com um objeto vehicleInfo que descreve seu veículo. Pense nessas informações como uma especificação que corresponde aos detalhes físicos do seu veículo real. O serviço exige esses detalhes para retornar trajetos que consideram as restrições de estrada com base nos atributos do veículo.

Medidas do veículo

Forneça o peso do veículo em quilogramas e as dimensões do veículo 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 são geralmente expressas em pés ou metros, isso pode exigir uma conversão de unidade.

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 estradas e passagens subterrâneas. Isso pode ser especialmente importante com valores fracionários. Dependendo do tamanho do veículo real, o arredondamento de um valor fracionário pode resultar em um roteamento excessivamente restritivo para o veículo.

Por exemplo:

  • Largura: muitos trailers dos EUA têm uma largura de 8' 6", que é convertida em 2.590,8 mm. O arredondamento para 2.591 mm indicaria que o veículo é maior que 8' 6", o que o classificaria como um veículo grande nas estradas dos EUA. Isso resultaria em um trajeto calculado de acordo com restrições significativamente diferentes do pretendido.
  • Altura: um trajeto que leva a uma ponte de 11 pés não seria adequado para um caminhão-trator típico com uma altura de 13,5 pés. No entanto, caminhões menores de cerca de 10 pés poderiam navegar pela passagem subterrânea. Portanto, é 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 imperial para métrico 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 todos os trailers. Em milímetros, arredondado para baixo.
totalWeightKg O peso bruto do veículo (incluindo trailers e carga). Em quilogramas, arredondado para baixo.
totalAxleCount O número total de eixos no veículo e em todos os trailers. Exata.
trailerInfo (opcional) Uma matriz de objetos, um para cada trailer. Omita para um veículo sem trailers, como um caminhão.
hazardousGoodsTypes (opcional) Uma matriz que especifica todos os materiais perigosos a bordo. EXPLOSIVOS, GASES, INFLAMÁVEIS, COMBUSTÍVEIS, ORGÂNICOS, VENENOS, CORROSIVOS, PERIGO DE ASPIRAÇÃO, PERIGO AMBIENTAL, OUTROS

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 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 trajeto, consulte Especificar recursos de trajeto a serem evitados.

A especificação de avoidTolls não garante trajetos 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 no fieldmask da solicitação de API Routes, os trajetos que contêm vias com pedágio serão anotados de acordo com esse campo.

Outros comportamentos de roteamento

Quando você define o travelMode como TRUCK, a API otimiza automaticamente o trajeto para a capacidade de manobra de veículos grandes. Os trajetos gerados evitam retornos e preferem fortemente estradas interestaduais e rodovias em vez de estradas 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 um trajeto específico para caminhões entre uma origem e um destino.

Exemplo de solicitação computeRoutes

Confira abaixo 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 computeRoutes

Este é um exemplo de resposta para a solicitação anterior mostrada acima. No objeto travelAdvisory, a sinalização 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 computeRoutes

Uma solicitação bem-sucedida para o endpoint computeRoutes retorna um objeto de resposta JSON que contém um ou mais trajetos possíveis.

Principais campos de resposta
  • Geometria de 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 em velocidades de viagem observadas de caminhões reais na pista. Ele também pode ser usado para calcular o 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. Esse é um token opaco que representa o trajeto calculado exato. Transmita esse token ao SDK do Navigation para garantir que o motorista receba 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 trajeto

Ao receber uma resposta, a primeira coisa que você precisa fazer é verificar se há sinalizações de segurança de trajeto. Se um trajeto fornecido contiver uma ou mais restrições que o tornem inadequado para o veículo, o campo travelAdvisory.routeRestrictionsPartiallyIgnored será definido como true.

Esse campo funciona como uma sinalização para responder à pergunta "Esse 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 é considerado totalmente compatível com os parâmetros fornecidos na solicitação.
  • true: o trajeto está sinalizado. O sistema não conseguiu encontrar um trajeto totalmente compatível e retornou um trajeto de "melhor esforço" que pode não ser seguro ou legal. Esse trajeto precisa ser usado com extrema cautela.

Calcular uma matriz de trajetos (computeRouteMatrix)

Use o endpoint computeRouteMatrix para comparar com eficiência os tempos e as distâncias de viagem 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 para sua finalidade, emita uma solicitação computeRoutes para receber os detalhes do trajeto e o token de rota 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 computeRouteMatrix

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

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

Próximas etapas