Method: computeRouteMatrix

Recebe uma lista de origens e destinos e retorna um fluxo com informações de trajeto para cada combinação de origem e destino.

OBSERVAÇÃO: esse método exige a especificação de uma máscara de campo de resposta na entrada. É possível fornecer a máscara de campo de resposta usando o parâmetro de URL $fields ou fields ou o cabeçalho HTTP/gRPC X-Goog-FieldMask. Consulte os cabeçalhos e parâmetros de URL disponíveis. O valor é uma lista separada por vírgulas de caminhos de campo. Consulte esta documentação detalhada sobre como criar os caminhos de campo.

Por exemplo, neste método:

  • Máscara de campo de todos os campos disponíveis (para inspeção manual): X-Goog-FieldMask: *
  • Máscara de campo de durações de trajetos, distâncias, status do elemento, condição e índices de elementos (um exemplo de configuração de produção): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

É fundamental que você inclua status em sua máscara de campo. Caso contrário, todas as mensagens serão exibidas corretamente. O Google não recomenda o uso da máscara de campo de resposta curinga (*) pelos seguintes motivos:

  • Selecionar apenas os campos necessários ajuda nosso servidor a salvar ciclos de computação, o que nos permite retornar o resultado com uma latência menor.
  • Selecionar apenas os campos necessários para o job de produção garante um desempenho de latência estável. Podemos adicionar mais campos de resposta no futuro, e esses novos campos podem exigir tempo de computação extra. Se você selecionar todos os campos ou todos os campos no nível superior, poderá haver uma queda no desempenho, porque qualquer campo novo adicionado será automaticamente incluído na resposta.
  • Selecionar apenas os campos necessários resulta em uma resposta menor e, portanto, em maior capacidade de rede.

Solicitação HTTP

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

O URL usa a sintaxe de transcodificação gRPC.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
Campos
origins[]

object (RouteMatrixOrigin)

Obrigatório. Matriz de origens, que determina as linhas da matriz de resposta. Várias restrições de tamanho se aplicam à cardinalidade de origens e destinos:

  • A soma do número de origens + o número de destinos especificados como placeId ou address não pode ser maior que 50.
  • O produto de número de origens × número de destinos não pode ser maior que 625.
  • O produto de número de origens × número de destinos não poderá ser maior que 100 se routesPreference estiver definida como TRAFFIC_AWARE_OPTIMAL.
  • O produto do número de origens × número de destinos não poderá ser maior que 100 se TravelMode estiver definido como TRANSIT.
destinations[]

object (RouteMatrixDestination)

Obrigatório. Matriz de destinos, que determina as colunas da matriz de resposta.

travelMode

enum (RouteTravelMode)

Opcional. Especifica o meio de transporte.

routingPreference

enum (RoutingPreference)

Opcional. Especifica como calcular a rota. O servidor tenta usar a preferência de roteamento selecionada para calcular a rota. Se a preferência de roteamento resultar em um erro ou em uma latência extralonga, um erro será retornado. Só é possível especificar essa opção quando travelMode é DRIVE ou TWO_WHEELER. Caso contrário, a solicitação vai falhar.

departureTime

string (Timestamp format)

Opcional. A hora de partida. Se você não definir esse valor, ele será usado como padrão para o horário em que a solicitação foi feita. OBSERVAÇÃO: só é possível especificar um departureTime no passado quando RouteTravelMode está definido como TRANSIT.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

arrivalTime

string (Timestamp format)

Opcional. O horário de chegada. OBSERVAÇÃO: só poderá ser definido quando RouteTravelMode for definido como TRANSIT. É possível especificar departureTime ou arrivalTime, mas não ambos.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

languageCode

string

Opcional. O código de idioma BCP-47, como "pt-BR" ou "en-US". Para saber mais, consulte Identificador de localidade Unicode. Consulte Compatibilidade de idiomas para ver a lista de idiomas compatíveis. Quando você não fornece esse valor, o idioma de exibição é inferido a partir do local da primeira origem.

regionCode

string

Opcional. O código de região, especificado como um valor ccTLD ("domínio de nível superior") de dois caracteres. Para mais informações, consulte Domínios de nível superior com códigos de país.

units

enum (Units)

Opcional. Especifica as unidades de medida para os campos de exibição.

extraComputations[]

enum (ExtraComputation)

Opcional. Uma lista de cálculos extras que podem ser usados para concluir a solicitação. Observação: esses cálculos extras podem retornar campos extras na resposta. Esses campos extras também precisam ser especificados na máscara de campo a ser retornada na resposta.

trafficModel

enum (TrafficModel)

Opcional. Especifica as suposições a serem usadas no cálculo do tempo no trânsito. Essa configuração afeta o valor retornado no campo de duração no RouteMatrixElement, que contém o tempo previsto no trânsito com base nas médias históricas. RoutingPreference para TRAFFIC_AWARE_OPTIMAL e RouteTravelMode para DRIVE. O padrão será BEST_GUESS se o tráfego for solicitado e TrafficModel não for especificado.

transitPreferences

object (TransitPreferences)

Opcional. Especifica preferências que influenciam o trajeto retornado para rotas TRANSIT. OBSERVAÇÃO: só é possível especificar um transitPreferences quando RouteTravelMode está definido como TRANSIT.

Corpo da resposta

Contém informações de rota calculadas para um par origem/destino na API v2.computeRouteMatrix. Esse proto pode ser transmitido para o cliente.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
Campos
status

object (Status)

Código de status de erro para este elemento.

condition

enum (RouteMatrixElementCondition)

Indica se o trajeto foi encontrado ou não. Independente do status.

distanceMeters

integer

A distância de viagem do trajeto, em metros.

duration

string (Duration format)

O tempo necessário para navegar no trajeto. Se você definir routingPreference como TRAFFIC_UNAWARE, esse valor será igual a staticDuration. Se você definir routingPreference como TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL, esse valor será calculado considerando as condições de trânsito.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

staticDuration

string (Duration format)

A duração do percurso pelo trajeto sem considerar as condições de trânsito.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

travelAdvisory

object (RouteTravelAdvisory)

Informações adicionais sobre o trajeto. Por exemplo: informações de restrição e pedágios

fallbackInfo

object (FallbackInfo)

Em alguns casos, quando o servidor não consegue computar a rota com as preferências informadas para esse par de origem/destino específico, ele pode voltar a usar um modo de cálculo diferente. Quando o modo substituto é usado, esse campo contém informações detalhadas sobre a resposta substituta. Caso contrário, este campo não será definido.

localizedValues

object (LocalizedValues)

Representações de texto das propriedades da RouteMatrixElement.

originIndex

integer

Índice baseado em zero da origem na solicitação.

destinationIndex

integer

Índice baseado em zero do destino na solicitação.

RouteMatrixOrigin

Uma única origem para ComputeRouteMatrixRequest

Representação JSON
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
Campos
waypoint

object (Waypoint)

Obrigatório. Ponto de referência da origem

routeModifiers

object (RouteModifiers)

Opcional. Modificadores para cada trajeto que usa esse nome como origem

RouteMatrixDestination

Um único destino para ComputeRouteMatrixRequest

Representação JSON
{
  "waypoint": {
    object (Waypoint)
  }
}
Campos
waypoint

object (Waypoint)

Obrigatório. Ponto de referência do destino

ExtraComputation

Cálculos extras a serem executados ao concluir a solicitação.

Enums
EXTRA_COMPUTATION_UNSPECIFIED Não utilizado. As solicitações que tiverem esse valor falharão.
TOLLS Informações de pedágio para os elementos da matriz.

RouteMatrixElementCondition

A condição do trajeto que está sendo retornado.

Enums
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED Usado somente quando o status do elemento não está OK.
ROUTE_EXISTS Um trajeto foi encontrado, e as informações correspondentes foram preenchidas para o elemento.
ROUTE_NOT_FOUND Nenhum trajeto foi encontrado. Os campos que contêm informações do trajeto, como distanceMeters ou duration, não serão preenchidos no elemento.

LocalizedValues

Representações de texto de determinadas propriedades.

Representação JSON
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
Campos
distance

object (LocalizedText)

Distância de viagem representada em forma de texto.

duration

object (LocalizedText)

Duração representada em formato de texto, considerando as condições de trânsito. Observação: se as informações de trânsito não foram solicitadas, esse valor é igual ao de "staticDuration".

staticDuration

object (LocalizedText)

Duração representada em forma de texto sem considerar as condições de trânsito.

transitFare

object (LocalizedText)

Tarifa de transporte público representada em formato de texto.