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 é 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 que começa em cada origem e termina em cada destino. Cada elemento do stream corresponde às informações de uma única rota.

O método ComputeRouteMatrix tem várias vantagens em relação ao serviço de matriz de distâncias:

  • O streaming permite que os elementos sejam retornados antes que toda a matriz seja calculada, reduzindo a latência.
  • ComputeRouteMatrix tem opções refinadas para o cálculo de tráfego, permitindo que você tome decisões de compensação entre 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.
  • É possível solicitar 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 código, é necessário ativá-lo. Para mais informações sobre como ativar os métodos da API Routes Preferred, consulte Primeiros passos.

Usar o método ComputeRouteMatrix

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

Consulte a seguinte documentação para mais informações:

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 seu 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. Sua 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 como calcular 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, se 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 stream serão retornados em alguma 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 com zero. É importante armazenar as ordens das listas de origem e destino.

Cálculo de pedágios

Para saber como calcular as taxas de pedágio, consulte Calcular taxas de pedágio.

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