Calcular uma matriz de rota

É possível 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. O 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 que começa em cada origem e termina 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 à API Distance Matrix (legada):

  • O streaming permite que os elementos sejam retornados antes que toda a matriz seja calculada, reduzindo a latência.
  • O 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.
  • É possível especificar o sentido (direção do trajeto) e informações sobre o lado da via para os pontos de referência.
  • Você pode pedir que as informações de pedágio sejam retornadas, junto com a distância da rota e o HEC.

Ativar o método ComputeRouteMatrix

Antes de usar o método ComputeRouteMatrix no seu código, é necessário ativá-lo. Para mais informações sobre como ativar os métodos da API Routes Preferred, consulte Como começar.

Usar o método ComputeRouteMatrix

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

Consulte a documentação a seguir para 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 no 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 sua linguagem e conjunto de ferramentas de build preferidos, gere o código protobuffer relevante.

  3. Gere sua 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ê quer na 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 que você quer na máscara de campo no código de produção.

      Para mais informações sobre como criar a string de máscara de campo, consulte https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto. Desativar campos desnecessários pode reduzir a latência, já que eles podem exigir mais computação. A latência vai permanecer estável se você especificar os campos necessários e novos campos que exigem mais computação forem adicionados depois.

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

Para exemplos de uso do método ComputeRouteMatrix, consulte Exemplos de cálculo de uma matriz de rotas (Beta).

Uma característica distintiva do método ComputeRouteMatrix é que códigos de erro podem ser retornados para todo o fluxo ou para elementos individuais. Por exemplo, a conexão de stream retorna um erro se a solicitação estiver malformada (por exemplo, tiver zero origens). 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 fluxo serão retornados em qualquer ordem. Por isso, cada elemento contém um origin_index e um destination_index. Para as origens e 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]. Esses arrays são indexados em zero. É importante armazenar as ordens das listas de origem e destino.

Como calcular as taxas de pedágio

Para informações sobre o cálculo de pedágios, consulte Calcular pedágios.

Para exemplos de cálculo de pedágios, consulte Exemplos de cálculo de uma matriz de rotas.