Melhores práticas para o serviço Roteiros do Azure Mapas
As APIs de Trajeto de Roteiros e Matriz de Roteiros no serviço Roteiros do Azure Mapas podem ser usadas para calcular os ETAs (tempos de chegada estimados) de cada roteiro solicitado. As APIs de Rotas consideram fatores como informações de tráfego em tempo real e dados de tráfego históricos, como as velocidades de estrada típicas no dia e hora solicitados. As APIs retornam as rotas mais curtas ou mais rápidas disponíveis para vários destinos de cada vez em sequência ou em ordem otimizada com base em tempo ou distância. Os usuários também podem solicitar rotas especializadas e detalhes para pedestres, bicicletas e veículos comerciais, como caminhões. Este artigo discute as melhores práticas para chamar o serviço Roteiros do Azure Mapas, incluindo instruções:
- Escolha entre as APIs de Trajeto de Rota e a API de Roteamento de Matriz
- Solicitar tempos de viagem históricos e previstos, com base em dados de tráfego históricos e em tempo real
- Solicitar detalhes da rota, como a hora e a distância, para a rota inteira e cada trecho da rota
- Solicitar rota para um veículo comercial, como um caminhão
- Solicitar informações de tráfego ao longo de uma rota, como congestionamentos e informações de pedágio
- Solicitar uma rota que consiste em uma ou mais paradas (pontos de passagem)
- Otimizar uma rota a partir de uma ou mais paradas para obter a melhor ordem para visitar cada parada (ponto de passagem)
- Otimizar rotas alternativas usando pontos de suporte. Por exemplo, ofereça rotas alternativas que passam por uma estação de carregamento de veículo elétrico.
- Usar o serviço Roteiros com o SDK Azure Mapas Web
Pré-requisitos
Para obter mais informações sobre a cobertura do serviço de rota, consulte Cobertura de roteamento.
Este artigo usa o aplicativo Postman para criar chamadas REST, mas você pode escolher qualquer ambiente de desenvolvimento de API.
Escolha entre Trajeto de Rota e Roteamento de Matriz
As APIs de Trajeto de Rota retornam instruções, incluindo o tempo de viagem e as coordenadas de um caminho de rota. A API Matriz de Rotas permite calcular o tempo de viagem e as distâncias de um conjunto de rotas que são definidas por locais de origem e destino. Para cada origem, a API de Matriz calcula o custo (tempo de viagem e distância) do roteamento dessa origem para cada destino determinado. Essas APIs permitem especificar parâmetros como o horário de partida desejado, horários de chegada e o tipo de veículo, como carro ou caminhão. Todos eles usam dados de tráfego de previsão ou em tempo real de forma adequada para retornar as rotas ideais.
Indicamos chamar APIs de Trajeto de Rota caso o seu cenário seja:
- Solicitar a rota de condução mais curta ou mais rápida entre dois ou mais locais conhecidos, para obter tempos de chegada precisos para seus veículos de entrega.
- Solicitar orientação de rota detalhada, incluindo a geometria de rota, para visualizar rotas no mapa
- Dada uma lista de locais de clientes, calcular a rota mais curta possível para visitar cada local do cliente e retornar à origem. Esse cenário é normalmente conhecido como o Problema do Caixeiro Viajante. Você pode passar até 150 pontos de passagem (paradas) em uma solicitação.
- Envie lotes de consultas para a API de lotes de Trajeto de Rota usando uma única chamada à API.
Indicamos chamar a API de Roteamento de Matriz caso o seu cenário seja:
- Calcular tempo e distância de viagem 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 alimentos de um restaurante.
- Classificar possíveis rotas por sua distância ou tempo real de viagem. A API de matriz retorna apenas os tempos de viagem e as distâncias para cada combinação de origem e destino.
- Dados de cluster com base no tempo de viagem ou em distâncias. Por exemplo, sua empresa tem 50 funcionários, encontre todos os funcionários que residem a uma distância de 20 minutos de carro do seu escritório.
Veja uma comparação para mostrar alguns recursos das APIs de Trajeto de Rota e Matriz:
| API do Azure Mapas | Número máximo de consultas na solicitação | Evitar áreas | Roteamento de caminhão e de veículo elétrico | Otimização de pontos de passagem e Caixeiro Viajante | Pontos de suporte |
|---|---|---|---|---|---|
| Obter Trajeto de Rota | 1 | ✔ | ✔ | ||
| POST - Trajeto de rota | 1 | ✔ | ✔ | ✔ | ✔ |
| POST - Lote de Trajeto de rota | 700 | ✔ | ✔ | ||
| Matrix de rota POST | 700 | ✔ |
Para saber mais sobre as funcionalidades de roteamento de veículos elétricos, confira nosso tutorial sobre como rotear veículos elétricos usando Azure Notebooks com Python.
Solicitar dados históricos e em tempo real
Por padrão, o serviço Roteiros assume que o modo de viagem é um carro e a hora 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. O mecanismo de roteamento leva em consideração as restrições de tráfego fixas dependentes do tempo, como "Não são permitidas conversões à esquerda das 16h e às 18h". O fechamento de estradas, como obras, são considerados a menos que você solicite especificamente uma rota que ignore o tráfego atual em tempo real. Para ignorar o tráfego atual, defina traffic como false em sua solicitação de API.
O valor travelTimeInSeconds de cálculo de rota inclui o atraso devido ao tráfego. Isso é gerado usando dados atuais e históricos de tempo de viagem, quando a hora de partida está definida como agora. Se a hora de partida for definida no futuro, as APIs retornarão os tempos de viagem previstos com base nos 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 de tráfego históricas:
| Elemento | Descrição |
|---|---|
| noTrafficTravelTimeInSeconds | Tempo de viagem estimado calculado como se não houvesse atrasos na rota devido às condições de tráfego, por exemplo, devido a congestionamento |
| historicTrafficTravelTimeInSeconds | Tempo de viagem estimado calculado usando dados de tráfego históricos dependentes de tempo |
| liveTrafficIncidentsTravelTimeInSeconds | Tempo de viagem estimado calculado usando dados de velocidade em tempo real |
As próximas seções demonstram como fazer chamadas para as APIs de rotas usando os parâmetros discutidos.
Exemplo de consulta
No primeiro exemplo abaixo, a hora de partida é definida para o futuro, no momento da gravação.
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 mostrado a seguir. Como a hora de partida é definida para o futuro, o valor de trafficDelayInSeconds é zero. O valor de travelTimeInSeconds é calculado usando dados de tráfego históricos dependentes de tempo. Portanto, nesse caso, o valor de travelTimeInSeconds é igual ao valor de 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
},
Exemplo de consulta
No próximo exemplo, temos uma solicitação de roteamento em tempo real, em que a hora de partida é agora. Ele não é especificado explicitamente na 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, como o mostrado no exemplo a seguir. Devido ao congestionamento, o valor de trafficDelaysInSeconds é maior que zero. Ele também é maior 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
},
Detalhes da rota e do segmento da solicitação
Por padrão, o serviço Roteiros retorna uma matriz de coordenadas. A resposta contém as coordenadas que compõem o caminho em uma lista chamada points. A resposta de rota também inclui a distância desde o início da rota e o tempo decorrido estimado. Esses valores podem ser usados para calcular a velocidade média de toda a rota.
A imagem a seguir mostra o elemento points.
Expanda o elemento point para ver a lista de coordenadas para o caminho:
As APIs de Trajeto de Rota dão suporte a formatos diferentes de instruções que podem ser usadas especificando o parâmetro instructionsType. Para formatar instruções para facilitar o processamento do computador, use o 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 em que alguns elementos das instruções são marcados e a instrução é apresentada com formatação especial. Para obter mais informações, confira a lista de tipos de instruções compatíveis.
Quando as instruções são solicitadas, a resposta retorna um novo elemento chamado guidance. O elemento guidance contém duas informações: instruções conversão-a-conversão e instruções resumidas.
O elemento instructions contém direções conversão-a-conversão para a viagem e instructionGroups tem instruções resumidas. Cada resumo de instrução aborda um segmento da viagem que pode abranger várias estradas. As APIs podem retornar detalhes para seções de uma rota. como o intervalo de coordenadas de um congestionamento de tráfego ou a velocidade atual do tráfego.
Solicitar uma rota para um veículo comercial
As APIs de rota do Azure Mapas são compatíveis com veículos comerciais, abrangendo o roteamento de caminhões comerciais. As APIs consideram os limites especificados. Por exemplo, a altura e o peso do veículo e se o veículo está transportando carga perigosa. Por exemplo, se um veículo estiver transportando uma carga inflamável, o mecanismo de roteamento evitará determinados túneis próximos a áreas residenciais.
Exemplo de consulta
A solicitação de exemplo abaixo consulta uma rota para um caminhão comercial. O caminhão está carregando material de 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 instruções que levam em conta as dimensões do caminhão e os resíduos perigosos. Você pode ler as instruções de rota expandindo o elemento guidance.
Exemplo de consulta
A alteração da Classe US Hazmat da consulta acima, resulta em uma rota diferente para refletir 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 a seguir é para um caminhão transportando um material perigoso de classe 9, que é menos perigoso do que um material perigoso de classe 1. Ao expandir o elemento guidance para ler as direções, observe que as direções não são as mesmas. Há mais instruções de rota para o caminhão transportando materiais perigosos de classe 1.
Solicitar informações de tráfego ao longo de uma rota
Com as APIs de direção de rota do Azure Mapas, os desenvolvedores podem solicitar detalhes para cada tipo de seção, incluindo o parâmetro sectionType na solicitação. Por exemplo, você pode solicitar as informações de velocidade para cada segmento de obstrução de tráfego. Consulte a lista de valores para a chave sectionType para saber mais sobre os vários detalhes que você pode solicitar.
Exemplo de consulta
A consulta a seguir. define sectionType como traffic. Ela solicita as seções que contêm informações de tráfego de Seattle a San Diego.
https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0§ionType=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 nas coordenadas fornecidas.
Essa opção pode ser usada para colorir as seções ao renderizar o mapa, como na imagem a seguir:
Calcular e otimizar uma rota de parada múltipla
Atualmente, o Azure Mapas fornece duas formas de otimizações de rota:
Otimizações baseadas no tipo de rota solicitado, sem alterar a ordem de pontos de passagem. Para obter mais informações, confira RouteType.
Otimização de Caixeiro Viajante, que altera a ordem dos pontos de passagem para obter a melhor ordem para visitar cada parada
Para roteamento de várias paradas, até 150 pontos de passagem podem ser especificados em uma única solicitação de rota. Os locais de coordenadas inicial e final podem ser os mesmos, como seria o caso com uma viagem de ida e volta. Mas você precisa fornecer pelo menos mais um ponto de passagem para fazer o cálculo da rota. Pontos de passagem podem ser adicionado à consulta entre as coordenadas de origem e destino.
Se você quiser otimizar a melhor ordem para visitar os pontos de passagem determinados, precisará especificar computeBestOrder=true. Esse cenário também é conhecido como o problema de otimização do Caixeiro Viajante.
Exemplo de consulta
A consulta a seguir solicita o caminho para seis pontos de passagem, com o parâmetro computeBestOrder definido como false. Ele também é o valor padrão para o parâmetro computeBestOrder.
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 o comprimento do caminho de 140.851 metros e que levaria 9.991 segundos para percorrer esse caminho.
A imagem a seguir ilustra o caminho resultante dessa consulta. Esse caminho é uma rota possível. Não é o caminho ideal com base no tempo ou na distância.
Essa ordem de pontos de passagem é: 0, 1, 2, 3, 4, 5 e 6.
Exemplo de consulta
A consulta a seguir solicita o caminho para os mesmos seis pontos de passagem, como no exemplo acima. Desta vez, o parâmetro computeBestOrder 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 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 pontos de passagem: 0, 5, 1, 2, 4, 3 e 6.
Dica
As informações de ordem de pontos de passagem otimizadas do serviço de roteamento fornece um conjunto de índices. Eles excluem os índices de origem e destino. Você precisa incrementar esses valores em 1 para considerar a origem. Em seguida, adicione seu destino ao final para obter a lista completa de pontos de passagem ordenada.
Calcular e criar rotas alternativas usando pontos de suporte
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. Nesse caso, você precisará criar um local alternativo usando pontos de suporte. Aqui estão as etapas para criar um local alternativo:
- Calcular uma rota da forma em que está e obter o caminho da resposta da rota
- Use o caminho da rota para localizar os locais desejados ao longo ou próximo ao caminho da rota. Por exemplo, você pode usar a solicitação Ponto de Interesse ou consultar seus próprios dados no banco de dados.
- Ordenar os locais com base na distância do início da rota
- Adicione esses locais como pontos de suporte em uma nova solicitação de roteiro para a API Postar Trajeto de Roteiros. Para saber mais sobre os pontos de suporte, consulte a documentação da API Trajeto de Rota - POST.
Ao chamar Postar Trajetos de Roteiros, você pode definir o tempo de desvio mínimo ou as restrições de distância, juntamente com os pontos de suporte. Use esses parâmetros se desejar oferecer rotas alternativas, mas também se deseja limitar o tempo de viagem. Quando essas restrições são usadas, as rotas alternativas seguem a rota de referência a partir do ponto de origem por um determinado tempo ou distância. Em outras palavras, as outras rotas divergem da rota de referência de acordo com as restrições determinadas.
A imagem a seguir é um exemplo de renderização de rotas alternativas com limites de desvio especificados para tempo e distância.
Usar o serviço de roteamento em um aplicativo Web
O SDK da Web do Azure Mapas fornece um módulo Serviço. Esse módulo é uma biblioteca auxiliar que torna mais fácil usar os serviços da API REST do Azure Mapas 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.
Observação
Desativação do módulo de serviço SDK da Web do Azure Mapas
Atualmente, o módulo de serviço SDK da Web do Azure Mapas foi preterido e será desativado em 30/09/26. Para evitar interrupções de serviço, recomendamos migrar para o REST SDK do JavaScript do Azure Mapas até 30/09/26. Para obter mais informações, confira Guia de desenvolvedores do REST SDK do JavaScript/TypeScript (versão prévia).
Próximas etapas
Para saber mais, consulte: