Práticas recomendadas para o serviço Azure Maps Route

As APIs de Direções de Rota e Matriz de Rotas no serviço de Rota do Azure Maps podem ser usadas para calcular os tempos de chegada estimados (ETAs) para cada rota solicitada. As APIs de rota consideram fatores como informações de trânsito em tempo real e dados históricos de tráfego, como as velocidades típicas da estrada na data e hora solicitadas. As APIs retornam as rotas mais curtas ou mais rápidas disponíveis para vários destinos ao mesmo tempo, em sequência ou em ordem otimizada, com base no tempo ou na distância. Os usuários também podem solicitar rotas especializadas e detalhes para caminhantes, ciclistas e veículos comerciais, como caminhões. Este artigo discute as práticas recomendadas para chamar o serviço Rota do Azure Maps, incluindo instruções:

• Escolha entre as APIs de Direções de Rota e a API de Roteamento de Matriz
• Solicitar tempos de viagem históricos e previstos, com base nos dados de tráfego históricos e em tempo real
• Solicite detalhes da rota, como tempo e distância, para todo o percurso e cada trecho do percurso
• Solicitar rota para um veículo comercial, como um caminhão
• Solicite informações de trânsito ao longo de uma rota, como engarrafamentos e informações sobre pedágio
• Solicite uma rota que consista em uma ou mais paradas (waypoints)
• Otimizar um percurso de uma ou mais paragens para obter a melhor ordem para visitar cada paragem (waypoint)
• Otimize rotas alternativas usando pontos de apoio. Por exemplo, ofereça rotas alternativas que passem por uma estação de carregamento de veículos elétricos.
• Usar o serviço Rota com o SDK da Web do Azure Maps

Pré-requisitos

• Uma conta do Azure Maps
• Uma chave de subscrição

Para obter mais informações sobre a cobertura do serviço Rota, consulte Cobertura de roteamento.

Você pode usar qualquer ambiente de desenvolvimento de API, como Postman ou bruno , para executar os exemplos de solicitação HTTP mostrados neste artigo ou para criar chamadas REST.

Escolha entre Direções de Rota e Roteamento em Matriz

As APIs de Direções de Rota retornam instruções, incluindo o tempo de viagem e as coordenadas de um caminho de rota. A API Route Matrix permite calcular o tempo de viagem e as distâncias para um conjunto de rotas definidas por locais de origem e destino. Para cada origem, a API Matrix calcula o custo (tempo de viagem e distância) do roteamento dessa origem para cada destino específico. Essas APIs permitem que você especifique parâmetros como o horário de partida desejado, os horários de chegada e o tipo de veículo, como carro ou caminhão. Todos eles usam dados de tráfego em tempo real ou preditivos de acordo para retornar as rotas mais ideais.

Considere chamar APIs de Direções de Rota se o seu cenário for para:

• Solicite a rota de condução mais curta ou mais rápida entre dois ou mais locais conhecidos, para obter horários de chegada precisos para os seus veículos de entrega.
• Solicite orientação detalhada de rotas, incluindo geometria de rotas, para visualizar rotas no mapa
• Dada uma lista de localizações de clientes, calcule o caminho mais curto possível para visitar cada local de cliente e retornar à origem. Este cenário é comumente conhecido como o problema do caixeiro-viajante. Você pode passar até 150 waypoints (paradas) em uma solicitação.
• Envie lotes de consultas para a API de lote de direções de rota usando apenas uma única chamada de API.

Considere chamar a API de Roteamento de Matriz se o seu cenário for:

• Calcule o tempo de viagem ou a distância entre um conjunto de origens e destinos. Por exemplo, você tem 12 motoristas e precisa encontrar o motorista disponível mais próximo para pegar a entrega de comida no restaurante.
• Classifique as rotas potenciais pela distância ou tempo real de viagem. A API Matrix retorna apenas tempos de viagem e distâncias para cada combinação de origem e destino.
• Dados de cluster com base no tempo de viagem ou distâncias. Por exemplo, sua empresa tem 50 funcionários, encontre todos os funcionários que vivem dentro de 20 minutos de carro do seu escritório.

Aqui está uma comparação para mostrar alguns recursos das APIs de Direções de Rota e Matriz:

Para saber mais sobre os recursos de roteamento de veículos elétricos, consulte nosso tutorial sobre como rotear veículos elétricos usando o Azure Notebooks com Python.

Solicite dados históricos e em tempo real

Por padrão, o serviço de rota assume que o modo de viagem é um carro e o horário de partida é agora. Ele retorna a rota com base nas condições de tráfego em tempo real, a menos que uma solicitação de cálculo de rota especifique o contrário. Os fatores do mecanismo de roteamento fixam restrições de tráfego dependentes do tempo, como "Curvas à esquerda não são permitidas entre 16:00 e 18:00". Fechamentos de estradas, como obras rodoviárias, são considerados, a menos que você solicite especificamente uma rota que ignore o tráfego atual ao vivo. Para ignorar o tráfego atual, defina traffic como false em sua solicitação de API.

O valor de cálculo de rota travelTimeInSeconds inclui o atraso devido ao tráfego. Ele é gerado usando os dados de tempo de viagem atuais e históricos, quando o horário de partida está definido para agora. Se o seu horário de partida for definido no futuro, as APIs retornam os tempos de viagem previstos com base em dados históricos.

Se você incluir o parâmetro computeTravelTimeFor=all em sua solicitação, o elemento de resumo na resposta terá os seguintes campos, incluindo condições históricas de tráfego:

As próximas seções demonstram como fazer chamadas para as APIs de rota usando os parâmetros discutidos.

Consulta de exemplo

No primeiro exemplo abaixo, a hora de partida é definida para o futuro, no momento da escrita.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&query=51.368752,-0.118332:51.385426,-0.128929&travelMode=car&traffic=true&departAt=2025-03-29T08:00:20&computeTravelTimeFor=all

A resposta contém um elemento de resumo, como o exemplo a seguir. Como o horário de partida é definido para o futuro, o valor trafficDelayInSeconds é zero. O valor travelTimeInSeconds é calculado usando dados históricos de tráfego dependentes do tempo. Portanto, neste caso, o valor travelTimeInSeconds é igual ao valor historicTrafficTravelTimeInSeconds .

"summary": {
    "lengthInMeters": 2131,
    "travelTimeInSeconds": 248,
    "trafficDelayInSeconds": 0,
    "departureTime": "2025-03-29T08:00:20Z",
    "arrivalTime": "2025-03-29T08:04:28Z",
    "noTrafficTravelTimeInSeconds": 225,
    "historicTrafficTravelTimeInSeconds": 248,
    "liveTrafficIncidentsTravelTimeInSeconds": 248
},

Consulta de exemplo

No próximo exemplo, temos uma solicitação de roteamento em tempo real, onde o horário de partida é agora. Não é explicitamente especificado no URL porque é o valor padrão.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&query=47.6422356,-122.1389797:47.6641142,-122.3011268&travelMode=car&traffic=true&computeTravelTimeFor=all

A resposta contém um resumo, conforme mostrado no exemplo a seguir. Devido ao congestionamento, o valor trafficDelaysInSeconds é maior que zero. Também é maior do que historicTrafficTravelTimeInSeconds.

"summary": {
    "lengthInMeters": 16637, 
    "travelTimeInSeconds": 2905, 
    "trafficDelayInSeconds": 1604, 
    "departureTime": "2020-02-28T01:00:20+00:00",
    "arrivalTime": "2020-02-28T01:48:45+00:00", 
    "noTrafficTravelTimeInSeconds": 872, 
    "historicTrafficTravelTimeInSeconds": 1976, 
    "liveTrafficIncidentsTravelTimeInSeconds": 2905 
},

Solicitar detalhes da rota e do trecho

Por padrão, o serviço Route retorna uma matriz de coordenadas. A resposta contém as coordenadas que compõem o caminho em uma lista chamada points. A resposta da rota também inclui a distância desde o início da rota e o tempo decorrido estimado. Estes valores podem ser utilizados para calcular a velocidade média de todo o percurso.

A imagem a seguir mostra o points elemento .

Expanda o point elemento para ver a lista de coordenadas do caminho:

As APIs de Direções de Rota suportam diferentes formatos de instruções que podem ser usadas especificando o parâmetro instructionsType . Para formatar instruções para facilitar o processamento do computador, use instructionsType=coded. Use instructionsType=tagged para exibir instruções como texto para o usuário. Além disso, as instruções podem ser formatadas como texto, onde alguns elementos das instruções são marcados, e a instrução é apresentada com formatação especial. Para obter mais informações, consulte a lista de tipos de instrução suportados.

Quando as instruções são solicitadas, a resposta retorna um novo elemento chamado guidance. O guidance elemento contém duas informações: direções passo a passo e instruções resumidas.

O instructions elemento contém direções passo a passo para a viagem, e o instructionGroups tem instruções resumidas. Cada resumo de instruções cobre um segmento da viagem que pode cobrir várias estradas. As APIs podem retornar detalhes para seções de uma rota. tais como, o alcance de coordenadas de um engarrafamento ou a velocidade atual do tráfego.

Solicitar uma rota para um veículo comercial

As APIs de Roteamento do Azure Maps dão suporte ao roteamento de veículos comerciais, abrangendo o roteamento de caminhões comerciais. As APIs consideram limites especificados. Por exemplo, a altura e o peso do veículo e se o veículo transporta cargas perigosas. Por exemplo, se um veículo estiver transportando inflamáveis, o motor de roteamento evita certos túneis que estão perto de áreas residenciais.

Consulta de exemplo

A solicitação de exemplo abaixo consulta uma rota para um caminhão comercial. O camião transporta resíduos perigosos de classe 1.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&vehicleWidth=2&vehicleHeight=2&vehicleCommercial=true&vehicleLoadType=USHazmatClass1&travelMode=truck&instructionsType=text&query=51.368752,-0.118332:41.385426,-0.128929

A API de rota retorna direções que acomodam as dimensões do caminhão e dos resíduos perigosos. Você pode ler as instruções de rota expandindo o guidance elemento .

Consulta de exemplo

Alterar a classe Hazmat dos EUA, a partir da consulta acima, resulta em uma rota diferente para acomodar essa alteração.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&vehicleWidth=2&vehicleHeight=2&vehicleCommercial=true&vehicleLoadType=USHazmatClass9&travelMode=truck&instructionsType=text&query=51.368752,-0.118332:41.385426,-0.128929

A resposta seguinte aplica-se a um camião que transporta matérias perigosas da classe 9, que são menos perigosas do que as matérias perigosas da classe 1. Quando você expande o guidance elemento para ler as instruções, observe que as direções não são as mesmas. Existem mais instruções de rota para o camião que transporta matérias perigosas de classe 1.

Solicite informações de trânsito ao longo de uma rota

Com as APIs de Direção de Rota do Azure Maps, os desenvolvedores podem solicitar detalhes para cada tipo de seção incluindo o sectionType parâmetro na solicitação. Por exemplo, você pode solicitar as informações de velocidade para cada segmento de engarrafamento. Consulte a lista de valores para a chave sectionType para saber mais sobre os vários detalhes que você pode solicitar.

Consulta de exemplo

A consulta a seguir define como sectionType traffic. Ele solicita as seções que contêm informações de tráfego de Seattle para San Diego.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&sectionType=traffic&query=47.6062,-122.3321:32.7157,-117.1611

A resposta contém as seções que são adequadas para o tráfego ao longo das coordenadas dadas.

Esta opção pode ser usada para colorir as seções ao renderizar o mapa, como na imagem a seguir:

Calcular e otimizar uma rota com várias paragens

Atualmente, o Azure Maps fornece duas formas de otimizações de rota:

• Otimizações com base no tipo de rota solicitado, sem alterar a ordem dos pontos de passagem. Para obter mais informações, consulte RouteType.

• Otimização do caixeiro-viajante, que altera a ordem dos pontos de passagem para obter a melhor ordem para visitar cada parada

Para roteamento com várias paradas, até 150 waypoints podem ser especificados em uma única solicitação de rota. Os locais de coordenadas iniciais e finais podem ser os mesmos, como seria o caso de uma viagem de ida e volta. Mas você precisa fornecer pelo menos mais um waypoint para fazer o cálculo da rota. Pontos de passagem podem ser adicionados à consulta entre as coordenadas de origem e destino.

Se você quiser otimizar a melhor ordem para visitar os pontos de passagem fornecidos, então você precisa especificar computeBestOrder=true. Este cenário também é conhecido como o problema de otimização do caixeiro-viajante.

Consulta de exemplo

A consulta a seguir solicita o caminho para seis waypoints, com o computeBestOrder parâmetro definido como false. É também o valor padrão para o computeBestOrder parâmetro.

https://atlas.microsoft.com/route/directions/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&computeBestOrder=false&query=47.606544,-122.336502:47.759892,-122.204821:47.670682,-122.120415:47.480133,-122.213369:47.615556,-122.193689:47.676508,-122.206054:47.495472,-122.360861

A resposta descreve que o comprimento do caminho é de 140.851 metros, e que seriam necessários 9.991 segundos para percorrer esse caminho.

A imagem a seguir ilustra o caminho resultante dessa consulta. Este caminho é um caminho possível. Não é o caminho ideal com base no tempo ou na distância.

Esta ordem de waypoint de rota é: 0, 1, 2, 3, 4, 5 e 6.

Consulta de exemplo

A consulta a seguir solicita o caminho para os mesmos seis pontos de passagem, como no exemplo acima. Desta vez, o computeBestOrder parâmetro definido como true (a otimização do caixeiro-viajante).

https://atlas.microsoft.com/route/directions/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&computeBestOrder=true&query=47.606544,-122.336502:47.759892,-122.204821:47.670682,-122.120415:47.480133,-122.213369:47.615556,-122.193689:47.676508,-122.206054:47.495472,-122.360861

A resposta descreve que o comprimento do caminho é de 91.814 metros, e que levaria 7.797 segundos para percorrer esse caminho. A distância de viagem e o tempo de viagem são menores aqui porque a API retornou a rota otimizada.

A imagem a seguir ilustra o caminho resultante dessa consulta.

A rota ideal tem a seguinte ordem de waypoint: 0, 5, 1, 2, 4, 3 e 6.

Calcular e enviesar rotas alternativas usando pontos de apoio

Você pode ter situações em que deseja reconstruir uma rota para calcular zero ou mais rotas alternativas para uma rota de referência. Por exemplo, você pode mostrar aos clientes rotas alternativas que passam pela sua loja de varejo. Neste caso, você precisa enviesar um local usando pontos de apoio. Aqui estão os passos para enviesar um local:

1. Calcular uma rota como está e obter o caminho da resposta da rota
2. Use o caminho da rota para encontrar os locais desejados ao longo ou perto do caminho da rota. Por exemplo, você pode usar a solicitação de Ponto de Interesse ou consultar seus próprios dados em seu banco de dados.
3. Ordene os locais com base na distância desde o início do percurso
4. Adicione esses locais como pontos de suporte em uma nova solicitação de rota para Postar direções de rota. Para saber mais sobre os pontos de suporte, consulte a documentação da API Post Route Directions.

Ao chamar Post Route Directions, você pode definir o tempo mínimo de desvio ou as restrições de distância, juntamente com os pontos de suporte. Use esses parâmetros se quiser oferecer rotas alternativas, mas também quiser limitar o tempo de viagem. Quando estas restrições são utilizadas, as rotas alternativas seguem a rota de referência a partir do ponto de origem para o tempo ou distância determinados. Por outras palavras, as outras rotas divergem da rota de referência pelas restrições dadas.

A imagem a seguir é um exemplo de renderização de rotas alternativas com limites de desvio especificados para o tempo e a distância.

Usar o serviço Roteamento em um aplicativo Web

O SDK da Web do Azure Maps fornece um módulo de Serviço. Este módulo é uma biblioteca auxiliar que facilita o uso das APIs REST do Azure Maps em aplicativos Web ou Node.js, usando JavaScript ou TypeScript. O módulo Serviço pode ser usado para renderizar as rotas retornadas no mapa. O módulo determina automaticamente qual API usar com solicitações GET e POST.

Próximos passos

Para saber mais, consulte: