API Distance Matrix | Tempo e distância de viagem

O que você pode fazer com a API Distance Matrix?

Por que usar a API Distance Matrix?

Como usar a API Distance Matrix

Parâmetros de solicitação

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=<origin_location_1|origin_location_2|...|origin_location_n>&destinations=<destination_location_1|destination_location_2|...|destination_location_n>&key=<your_access_token>

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key=<your_access_token>

Parâmetros necessários

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom&destinations=St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom&key=<your_access_token>

{
    "destination_addresses": [
        "St John's Church, North End Rd, London SW6 1PB, United Kingdom"
    ],
    "origin_addresses": [
        "Westminster Abbey, 20 Deans Yd, London SW1P 3PA, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.3 km",
                        "value": 7346
                    },
                    "duration": {
                        "text": "23 mins",
                        "value": 1401
                    },
                    "origin": "Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom",
                    "destination": "St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Parâmetros opcionais

• modo (o padrão é dirigir) — especifica o modo de transporte a ser usado ao calcular a distância. Os valores válidos e outros detalhes da solicitação são especificados na Modos de viagem seção deste documento.
• idioma — um idioma usado para retornar resultados.
  
  • 
    Veja a lista de idiomas compatíveis.
    
  • 
    Se o idioma não for fornecido, a API tentará usar o idioma preferencial, conforme especificado no cabeçalho Accept-Language, ou o idioma nativo do domínio do qual a solicitação é enviada.
    
  • 
    A API faz o possível para fornecer um endereço que seja legível tanto para o usuário quanto para os habitantes locais. Para atingir esse objetivo, ele retorna endereços no idioma local, transliterados para um script legível pelo usuário, se necessário, observando o idioma preferido. Todos os outros endereços são retornados no idioma preferido. Os componentes de endereço são todos retornados no mesmo idioma, que é escolhido no primeiro componente.
    
  • 
    Se um nome não estiver disponível no idioma preferido, a API usará a correspondência mais próxima.
    
  • 
    O idioma preferido tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que eles são retornados. O geocodificador interpreta as abreviações de forma diferente dependendo do idioma, como as abreviações para tipos de ruas ou sinônimos que podem ser válidos em um idioma, mas não em outro. Por exemplo, utca e tér são sinônimos de rua em húngaro.
    

• evitar — introduz restrições à rota. Os valores válidos são especificados na Restrições seção deste documento. Somente uma restrição pode ser especificada.
• unidades — especifica o sistema de unidades a ser usado ao expressar a distância como texto. Veja o Sistemas de unidades seção deste documento para obter mais informações.
  
• arrival_time — especifica a hora de chegada desejada para solicitações de trânsito, em segundos desde a meia-noite de 1º de janeiro de 1970, UTC. Você pode especificar a hora de partida ou a hora de chegada, mas não ambas. Observe que arrival_time deve ser especificado como um número inteiro.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&arrival_time=now&transit_mode=bus&mode=transit&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "166.4 km",
                        "value": 166409
                    },
                    "duration": {
                        "text": "4 hour 2 mins",
                        "value": 14524
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

• departure_time — a hora desejada da partida. Você pode especificar a hora como um número inteiro em segundos desde a meia-noite de 1º de janeiro de 1970, UTC. Como alternativa, você pode especificar um valor de agora, que define a hora de partida para a hora atual (correta para o segundo mais próximo). O departure_time deve ser definido para a hora atual ou em algum momento no futuro. Não pode estar no passado. Os resultados de uma determinada solicitação podem variar com o tempo devido às mudanças na rede rodoviária, às condições médias de tráfego atualizadas e à natureza distribuída do serviço. Os resultados também podem variar entre rotas quase equivalentes a qualquer momento ou frequência. O horário de partida pode ser especificado em dois casos:
  
  • 
    Para solicitações em que o modo de viagem é de trânsito: opcionalmente, você pode especificar um dos horários de partida ou chegada. Se nenhuma hora for especificada, o padrão departure_time será agora (ou seja, o horário de partida será padronizado para o horário atual).
    
  • 
    Para solicitações em que o modo de viagem está dirigindo: você pode especificar o horário de partida para receber uma rota e a duração da viagem (campo de resposta: duration_in_traffic) que levem em consideração as condições do tráfego. O departure_time deve ser definido para a hora atual ou em algum momento no futuro. Não pode estar no passado.
    

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "2 hour 29 mins",
                        "value": 8968
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

• traffic_model (o padrão é best_guess) — especifica as suposições a serem usadas ao calcular o tempo no trânsito. Essa configuração afeta o valor retornado no campo duration_in_traffic na resposta, que contém o tempo previsto no tráfego com base nas médias históricas. O parâmetro traffic_model só pode ser especificado para solicitações em que o modo de viagem está acionando e quando a solicitação inclui um departure_time. Os valores disponíveis para esse parâmetro são:
  
  • 
    best_guess (padrão) indica que o duration_in_traffic retornado deve ser a melhor estimativa do tempo de viagem, considerando o que se sabe sobre as condições históricas do tráfego e o tráfego ao vivo. O tráfego ao vivo se torna mais importante quanto mais próximo o horário de partida estiver de agora.
    
  • 
    O pessimista indica que o duration_in_traffic retornado deve ser maior do que o tempo real de viagem na maioria dos dias, embora dias ocasionais com condições de tráfego particularmente ruins possam exceder esse valor. Afeta o campo na resposta distance_in_traffic_model, retornando a rota mais curta.
    
  • 
    otimista indica que a duration_in_traffic retornada deve ser menor do que o tempo real de viagem na maioria dos dias, embora dias ocasionais com condições de tráfego particularmente boas possam ser mais rápidos do que esse valor. Afeta o campo na resposta distance_in_traffic_model, retornando a rota mais curta.
    

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&traffic_model=pessimistic&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "4 hour 0 mins",
                        "value": 14400
                    },
                    "distance_in_traffic_model": {
                        "text": "118 miles",
                        "value": 189274
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

• transit_mode — especifica um ou mais modos preferenciais de trânsito. Esse parâmetro só pode ser especificado para solicitações em que o modo é de trânsito. O parâmetro suporta os seguintes argumentos:
  
  • 
    ônibus indica que a rota calculada deve preferir viajar de ônibus.
    
  • 
    metrô indica que a rota calculada deve preferir viajar de metrô.
    
  • 
    trem indica que a rota calculada deve preferir viajar de trem.
    
  • 
    bonde indica que a rota calculada deve preferir viajar de bonde e trem leve.
    
  • 
    ferrovia indica que a rota calculada deve preferir viajar de trem, bonde, metrô leve e metrô. Isso é equivalente a transit_mode=train|tram|subway.
    

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&transit_mode=bus|train|tram|subway&mode=transit&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "2 hour 29 mins",
                        "value": 8968
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Modos de viagem

• dirigir (padrão) indica o cálculo da distância usando a rede rodoviária.
  
• a caminhada solicita o cálculo da distância para caminhar por caminhos e calçadas para pedestres (quando disponível).
  
• o ciclismo solicita o cálculo da distância para andar de bicicleta por meio de ciclovias e ruas preferidas (quando disponível).
  
• cálculo da distância de solicitações de trânsito por meio de rotas de transporte público (quando disponível). Se você definir o modo de trânsito, precisará especificar um horário de partida ou um horário_chegada. Se nenhuma hora for especificada, o padrão departure_time será agora (ou seja, o horário de partida será padronizado para o horário atual). Você também precisa incluir um transit_mode.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=walking&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "5.7 km",
                        "value": 5699
                    },
                    "duration": {
                        "text": "1 hour 12 mins",
                        "value": 4379
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Informações de trânsito

• O parâmetro do modo de viagem é dirigir ou não está especificado (dirigir é o modo de viagem padrão).
  
• A solicitação inclui um parâmetro departure_time válido. O departure_time pode ser definido para o horário atual ou algum outro horário.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=driving&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "23 mins",
                        "value": 1395
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Restrições

• evitar=pedágios
  
• evitar = rodovias
  
• evitar=balsas
  
• evitar = interno
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=driving&departure_time=now&avoid=ferries&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "26 mins",
                        "value": 1568
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Sistemas de unidades

• units=metric (padrão) retorna distâncias em quilômetros e metros.
  
• units=imperial retorna distâncias em milhas e pés.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&departure_time=now&units=imperial&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "4.7 mi",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "26 mins",
                        "value": 1568
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Exemplo de resposta

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Elementos de resposta da matriz de distância

• status contém metadados sobre a solicitação. Veja Códigos de status abaixo.
  
• origin_addresses contêm uma matriz de endereços conforme retornados pela API de sua solicitação original. Eles são formatados pelo geocodificador e localizados de acordo com o parâmetro de idioma passado com a solicitação.
  
• destination_addresses contêm uma matriz de endereços retornados pela API a partir de sua solicitação inicial. Assim como os endereços de origem, eles são localizados, se apropriado.
  
• as linhas contêm uma matriz de elementos, que por sua vez contêm elementos de status, duração e distância.
  

Códigos de status

Códigos de status de nível superior

• OK indica que a resposta contém um resultado válido.
• INVALID_REQUEST indica que a solicitação fornecida era inválida.
• MAX_ELEMENTS_EXCEEDED indica que o produto de origem e destino excede o limite por consulta.
• OVER_DAILY_LIMIT indica qualquer um dos seguintes:
  
  • 
    A chave da API está ausente ou é inválida.
    
  • 
    O faturamento não foi ativado em sua conta.
    
  • 
    Um limite de uso autoimposto foi excedido.
    
  • 
    O método de pagamento fornecido não é mais válido (por exemplo, um cartão de crédito expirou).
    
• OVER_QUERY_LIMIT indica que o serviço recebeu muitas solicitações do seu aplicativo dentro do período permitido.
• REQUEST_DENIED indica que o serviço negou o uso do serviço Distance Matrix pelo seu aplicativo.
• UNKNOWN_ERROR indica que uma solicitação do Distance Matrix não pôde ser processada devido a um erro no servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.

Códigos de status em nível de elemento

• OK indica a resposta e contém um resultado válido.
  
• NOT_FOUND indica que a origem e/ou o destino desse emparelhamento não puderam ser geocodificados.
  
• ZERO_RESULTS indica que nenhuma rota foi encontrada entre a origem e o destino.
  
• MAX_ROUTE_LENGTH_EXCEEDED indica que a rota solicitada é muito longa e não pode ser processada.
  
• UNKNOWN_ERROR indica que uma solicitação do Distance Matrix não pôde ser processada devido a um erro no servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.
  

Mensagens de erro

Linhas

Elementos

• status: Consulte Códigos de status para obter uma lista de possíveis códigos de status.
  
• duração: o tempo necessário para percorrer essa rota, expresso em segundos (o campo de valor) e como texto.
  
• duration_in_traffic: o tempo necessário para percorrer essa rota, com base nas condições atuais e históricas do tráfego.
  
• distância: A distância total dessa rota, expressa em metros (valor) e como texto. O valor textual usa o sistema de unidades especificado com o parâmetro de unidade da solicitação original ou a região de origem.
  
• distance_in_traffic_model: A menor distância necessária para percorrer essa rota, com base nas condições atuais e históricas do tráfego.