Calcular uma matriz de rota

Você pode calcular a distância e a duração de uma rota para várias origens e destinos usando o método ComputeRouteMatrix da API Routes Preferred. ComputeRouteMatrix oferece suporte a chamadas gRPC de streaming e chamadas HTTP REST.

Com uma lista de pares de origem e destino, ComputeRouteMatrix calcula a distância e a duração de um trajeto, começando em cada origem e terminando em cada destino. Cada elemento do fluxo corresponde às informações de um único trajeto.

O método ComputeRouteMatrix tem várias vantagens em relação ao serviço Distance Matrix:

  • O streaming permite que elementos sejam retornados antes do cálculo da matriz inteira, reduzindo a latência.
  • O ComputeRouteMatrix tem opções refinadas para o cálculo de tráfego, permitindo que você tome decisões de compensação de qualidade e latência.
  • As solicitações são executadas com prioridade mais alta na infraestrutura do Google, o que resulta em maior disponibilidade.
  • Você pode especificar informações de direção (direção da viagem) e lado da estrada para os waypoints.
  • Você pode solicitar a devolução das informações de pedágio, incluindo a distância do trajeto e o HEC.

Ativar o método ComputeRouteMatrix

Antes de usar o método ComputeRouteMatrix no seu código, ative-o. Para mais informações sobre como ativar os métodos da API Routes Preferred, consulte Primeiros passos.

Como usar o método ComputeRouteMatrix

O método ComputeRouteMatrix está disponível no endpoint v1 do Routes Preferred.

Consulte a documentação a seguir para conferir informações mais detalhadas:

gRPC: https://developers.google.com/maps/documentation/routes_preferred/reference/rpc/google.maps.routes.v1

REST: https://developers.google.com/maps/documentation/routes_preferred/reference/rest/v1/TopLevel/computeRouteMatrix

As etapas genéricas a seguir descrevem como usar o gRPC para chamar o método ComputeRouteMatrix:

  1. Confira os protobuffers necessários do repositório googleapis:

    https://github.com/googleapis/googleapis/tree/master/google/maps/routes

    Alguns sistemas de build, como o Go, podem fazer isso automaticamente.

  2. Usando a linguagem de sua preferência e o conjunto de ferramentas de build, gere o código protobuffer relevante.

  3. Gere a solicitação. Dois metadados obrigatórios precisam ser enviados com a solicitação:

    • X-Goog-Api-Key precisa ser definido como sua chave de API.

    • X-Goog-Fieldmask precisa ser definido como uma lista separada por vírgulas dos campos que você precisa para a resposta. Por exemplo, X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status. É possível usar o caractere curinga (*) para indicar todos os campos, mas isso não é recomendado. Use o caractere curinga para testar e entender a resposta da API, mas liste explicitamente os campos desejados na máscara de campo no código de produção.

      Para mais informações sobre como construir a string da máscara de campo, consulte https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto (link em inglês). Desativar os campos que você não precisa pode reduzir a latência, porque eles podem exigir mais cálculos. Se você especificar os campos necessários, a latência permanecerá estável, e novos campos que exigirem mais computação serão adicionados posteriormente.

  4. Envie sua solicitação para routespreferred.googleapis.com:443.Use o protocolo TLS.

Para exemplos de uso do método ComputeRouteMatrix, consulte Como calcular uma matriz de rota (Beta) exemplos.

Uma característica distinta do método ComputeRouteMatrix é que os códigos de erro podem ser retornados para todo o stream ou para elementos individuais. Por exemplo, a conexão de stream retornará um erro se a solicitação for malformada (por exemplo, se tiver origens zero). No entanto, se um erro se aplicar a apenas alguns elementos do fluxo (por exemplo, definir um ID de lugar inválido para uma origem), somente os elementos afetados pelo erro vão conter códigos de erro.

Não há garantia de que os elementos retornados pelo stream serão retornados em qualquer ordem. Por isso, cada elemento contém um origin_index e um destination_index. Para as origens e os destinos especificados pela solicitação, a origem da rota é equivalente a origins[origin_index] para um determinado elemento, e o destino da rota é equivalente a destinations[destination_index]. Essas matrizes são indexadas zero. É importante armazenar os pedidos da lista de origem e destino.

Como calcular taxas de pedágio

Consulte Calcular taxas de pedágio para mais informações sobre esse assunto.

Para ver exemplos de cálculo de taxas de pedágio, consulte Como calcular uma matriz de trajeto (em inglês).