Calcular uma matriz de rota

Você pode calcular a distância e a duração de um trajeto para várias origens e destinos usando o método ComputeRouteMatrix da API Routes Preferred. ComputeRouteMatrix é compatível com 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 stream 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 os elementos sejam retornados antes do cálculo da matriz inteira, reduzindo a latência.
  • ComputeRouteMatrix tem opções refinadas para 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 uma 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 via para waypoints.
  • Você pode solicitar que as informações sobre pedágios sejam retornadas, além da distância do trajeto e do HEC.

Ativar o método ComputeRouteMatrix

Antes de usar o método ComputeRouteMatrix no seu código, você precisa ativá-lo. 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 pelo endpoint v1 da Routes Preferred.

Para informações mais detalhadas, consulte a documentação a seguir:

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 no repositório googleapis:

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

    Observe que alguns sistemas de compilação, como o Go, podem fazer isso automaticamente.

  2. Usando a linguagem e o conjunto de ferramentas de build que preferir, gere o código protobuffer relevante.

  3. Gere a solicitação. Duas partes obrigatórias dos metadados precisam ser enviadas 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 necessários da resposta. Por exemplo, X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status. Você pode 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. A desativação dos campos desnecessários pode reduzir a latência, porque eles podem exigir mais cálculos. Sua latência permanecerá estável se você especificar os campos necessários e novos campos que exigem mais computação forem adicionados posteriormente.

  4. Envie sua solicitação para routespreferred.googleapis.com:443.É necessário usar o protocolo TLS.

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

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 zero origens). No entanto, se um erro se aplicar a apenas alguns elementos do stream (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 uma origin_index e uma destination_index. Para as origens e os destinos especificados pela solicitação, a origem do trajeto é equivalente a origins[origin_index] para um determinado elemento, e o destino do trajeto é equivalente a destinations[destination_index]. Essas matrizes são indexadas em zero. É importante armazenar os pedidos das listas de origem e destino.

Calculando tarifas de pedágio

Para informações sobre como calcular taxas de pedágio, consulte Calcular tarifas de pedágio.

Para exemplos do cálculo de tarifas de pedágio, consulte Como calcular exemplos de matriz de rota.