Procedure consigliate per il servizio di pianificazione percorso di Mappe di Azure
Le API Route Directions e Route Matrix nel servizio di pianificazione percorso di Mappe di Azure possono essere usate per calcolare i tempi di arrivo stimati (ETA) per ogni percorso richiesto. Le API di pianificazione percorso considerano i fattori, ad esempio le informazioni sul traffico in tempo reale e i dati sul traffico cronologici, ad esempio le velocità tipiche della strada sulla data e l'ora richieste. Le API restituiscono i percorsi più brevi o più veloci disponibili per più destinazioni alla volta in sequenza o in ordine ottimizzato, in base al tempo o alla distanza. Gli utenti possono anche richiedere itinerari specializzati e dettagli per pedoni, ciclisti e veicoli commerciali come i camion. Questo articolo illustra le procedure consigliate per chiamare il servizio di pianificazione percorso di Mappe di Azure, tra cui le procedure seguenti:
- Scegliere tra le API Route Directions e Matrix Routing
- Richiedere tempi di viaggio stimati e cronologici, in base ai dati di traffico in tempo reale e storici
- Richiedi i dettagli del percorso, come tempo e distanza, per l'intero itinerario e per ogni tappa
- Richiedere un percorso per un veicolo commerciale, ad esempio un camion
- Richiedere informazioni sul traffico lungo un percorso, ad esempio ingorghi e informazioni sui pedaggi
- Richiedere un percorso costituito da una o più fermate (punti del tragitto)
- Ottimizzare un percorso di una o più fermate per ottenere l'ordine migliore per visitare ogni fermata (punto del tragitto)
- Ottimizzare i percorsi alternativi usando i punti di supporto. Ad esempio, offrire itinerari alternativi che passano da una stazione di ricarica del veicolo elettrico.
- Usare il servizio di pianificazione percorso con l'SDK Web di Mappe di Azure
Prerequisiti
Per altre informazioni sulla copertura del servizio di pianificazione percorso, vedere Copertura per la pianificazione percorso.
È possibile usare qualsiasi ambiente di sviluppo api, ad esempio Postman o bruno , per eseguire gli esempi di richiesta HTTP illustrati in questo articolo o per compilare chiamate REST.
Scegliere tra Route Directions e Matrix Routing
Le API Route Directions restituiscono istruzioni che includono il tempo di percorrenza e le coordinate di un percorso. L'API Route Matrix permette di calcolare i tempi di percorrenza e le distanze di una serie di percorsi definiti dalle località di origine e di destinazione. Per ogni origine specificata, l'API Matrix calcola il costo (tempo di viaggio e distanza) della pianificazione percorso da tale origine a ogni destinazione indicata. Queste API consentono di specificare parametri quali l'ora di partenza desiderata, gli orari di arrivo e il tipo di veicolo, ad esempio auto o camion. Tutte le API utilizzano i dati sul traffico in tempo reale o predittivi per fornire i percorsi più ottimali.
Valutare la possibilità di chiamare l'API Route Directions se lo scenario è:
- Richiedere il percorso di guida più breve o più veloce tra due o più località conosciute, per ottenere tempi di arrivo precisi per i veicoli di consegna.
- Richiedere indicazioni dettagliate sul percorso, inclusa la relativa geometria, per visualizzare i percorsi sulla mappa
- Dato un elenco di località dei clienti, calcolare il percorso più breve possibile per visitare ogni località del cliente e tornare all'origine. Questo scenario è comunemente noto come problema del venditore in trasferta. È possibile passare fino a 150 punti del tragitto (fermate) in una richiesta.
- Inviare batch di query all'API Route Directions Batch usando solo una singola chiamata API.
Valutare la possibilità di chiamare l'API Matrix Routing se lo scenario è:
- Calcolare il tempo di viaggio o la distanza tra un set di origini e destinazioni. Ad esempio, si dispone di 12 autisti e si deve trovare l'autista disponibile più vicino per ritirare il cibo consegnato dal ristorante.
- Ordinare i possibili percorsi in base alla distanza o al tempo di viaggio effettivo. L'API Matrix restituisce solo i tempi di viaggio e le distanze per ogni combinazione di origine e destinazione.
- Dati del cluster in base al tempo di viaggio o alle distanze. Ad esempio, l'azienda ha 50 dipendenti, trova tutti i dipendenti che vivono entro 20 minuti dal tuo ufficio.
Ecco un confronto per mostrare alcune funzionalità delle API Route Directions e Matrix:
| API di Mappe di Azure | Numero massimo di query nella richiesta | Evitare aree | Pianificazione percorso dei camion e dei veicoli elettrici | Ottimizzazione dei punti del tragitto e dei venditori in trasferta | Punti di supporto |
|---|---|---|---|---|---|
| Get Route Directions | 1 | ✔ | ✔ | ||
| Post Route Directions | 1 | ✔ | ✔ | ✔ | ✔ |
| Post Route Directions Batch | 700 | ✔ | ✔ | ||
| Post Route Matrix | 700 | ✔ |
Per altre informazioni sulle funzionalità di pianificazione percorso dei veicoli elettrici, vedere l'esercitazione su come instradare i veicoli elettrici usando Azure Notebooks con Python.
Richiedere dati cronologici e in tempo reale
Per impostazione predefinita, il servizio di pianificazione percorso presuppone che la modalità di viaggio sia l'automobile e che l'orario di partenza sia ora. Restituisce il percorso in base alle condizioni del traffico in tempo reale, a meno che non venga specificata diversamente una richiesta di calcolo del percorso. Il motore di pianificazione percorso tiene conto delle limitazioni al traffico dipendenti dall'orario, come ad esempio ‘Le svolte a sinistra non sono consentite tra le 16:00 e le 18:00’. Le chiusure di strade, come i lavori stradali, vengono prese in considerazione a meno che non si richieda espressamente un percorso che ignori il traffico in corso. Per ignorare il traffico attuale, impostare traffic su false nella richiesta API.
Il valore del calcolo del percorso travelTimeInSeconds include il ritardo dovuto al traffico. Viene generato utilizzando i dati relativi ai tempi di viaggio attuali e cronologici, quando l'orario di partenza è impostato su ora. Se l'orario di partenza è fissato nel futuro, le API restituiscono i tempi di viaggio previsti in base ai dati cronologici.
Se si include il parametro computeDeviceTimeFor=all nella richiesta, l'elemento di riepilogo nella risposta include i campi seguenti, incluse le condizioni del traffico cronologico:
| Elemento | Descrizione |
|---|---|
| noTrafficTravelTimeInSeconds | Tempo di viaggio stimato calcolato come se non ci fossero ritardi sul percorso a causa delle condizioni del traffico, ad esempio a causa di una congestione |
| historicTrafficTravelTimeInSeconds | Tempo di viaggio stimato calcolato usando i dati cronologici dipendenti dal tempo |
| liveTrafficIncidentsTravelTimeInSeconds | Tempo di viaggio stimato calcolato usando i dati sulla velocità in tempo reale |
Le sezioni successive illustrano come effettuare chiamate alle API di percorso usando i parametri descritti.
Query di esempio
Nel primo esempio seguente, l'orario di partenza è impostato sul futuro, al momento della scrittura.
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
La risposta contiene un elemento di riepilogo, come nell'esempio seguente. Poiché l'orario di partenza è impostato nel futuro, il valore trafficDelayInSeconds è zero. Il valore travelTimeInSeconds viene calcolato usando dati di traffico cronologici dipendenti dal tempo. In questo caso, quindi, il valore travelTimeInSeconds è uguale al valore 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
},
Query di esempio
Nell'esempio successivo è disponibile una richiesta di pianificazione percorso in tempo reale, in cui l'orario di partenza è ora. Non è specificato in modo esplicito nell'URL perché è il valore predefinito.
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
La risposta contiene un riepilogo, come illustrato nell'esempio seguente. A causa della congestione, il valore trafficDelaysInSeconds è maggiore di zero. È anche maggiore di 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
},
Richiedere i dettagli del percorso e delle tappe
Per impostazione predefinita, il servizio di pianificazione percorso restituisce una matrice di coordinate. La risposta contiene le coordinate che costituiscono il percorso in un elenco denominato points. La risposta del percorso include anche la distanza dall'inizio del percorso e il tempo stimato trascorso. Questi valori possono essere usati per calcolare la velocità media per l'intero percorso.
L'immagine seguente mostra l'elemento points.
Espandere l'elemento point per visualizzare l'elenco delle coordinate per il percorso:
Le API Route Directions supportano formati diversi di istruzioni che possono essere usate specificando il parametro instructionsType. Per formattare istruzioni per semplificare l'elaborazione del computer, usare instructionsType=coded. Usare instructionsType=tagged per visualizzare le istruzioni come testo per l'utente. Inoltre, le istruzioni possono essere formattate come testo in cui alcuni elementi delle istruzioni sono contrassegnati e l'istruzione viene presentata con formattazione speciale. Per altre informazioni, vedere l'elenco dei tipi di istruzioni supportati.
Quando vengono richieste istruzioni, la risposta restituisce un nuovo elemento denominato guidance. L'elemento guidance contiene due informazioni: indicazioni stradali di tipo navigatore e istruzioni riepilogate.
L'elemento instructions contiene indicazioni stradali di tipo navigatore per il viaggio e instructionGroups include le istruzioni riepilogate. Ogni riepilogo delle istruzioni copre un segmento del viaggio che potrebbe coprire più strade. Le API possono restituire i dettagli per le sezioni di un percorso. ad esempio, l'intervallo di coordinate di un ingorgo del traffico o la velocità attuale del traffico.
Richiedere un percorso per veicolo commerciale
Le API di pianificazione percorso di Mappe di Azure supportano la pianificazione percorso dei veicoli commerciali, coprendo quella dei camion. Le API tengono conto dei limiti specificati. Ad esempio, l'altezza e il peso del veicolo, e se il veicolo trasporta carico di tipo pericoloso. Ad esempio, se un veicolo trasporta sostanze infiammabili, il motore di pianificazione percorso evita alcuni tunnel che si trovano in prossimità di aree residenziali.
Query di esempio
La richiesta di esempio seguente esegue una query su un percorso per un camion commerciale. Il camion trasporta materiale di rifiuti pericolosi di 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
L'API Route restituisce indicazioni stradali che supportano le dimensioni del camion e i rifiuti pericolosi. È possibile leggere le istruzioni del percorso espandendo l'elemento guidance.
Query di esempio
Cambiando la classe US Hazmat, dalla query di cui sopra, si ottiene un percorso diverso per adattarsi a questa modifica.
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
La risposta seguente è per un camion che trasporta un materiale pericoloso classe 9, che è meno pericoloso di un materiale pericoloso di classe 1. Quando si espande l'elemento guidance per leggere le indicazioni stradali, si noti che esse non sono uguali. Sono disponibili altre istruzioni di percorso per gli camion che trasportano materiale pericoloso di classe 1.
Richiedere informazioni sul traffico lungo un percorso
Con le API Route Direction di Mappe di Azure, gli sviluppatori possono richiedere i dettagli per ogni tipo di sezione includendo il parametro sectionType nella richiesta. Ad esempio, puoi richiedere le informazioni sulla velocità per ogni segmento di ingorgo. Per informazioni sui vari dettagli che è possibile richiedere, vedere l'elenco dei valori per la chiave sectionType.
Query di esempio
La query seguente imposta sectionType su traffic. Richiede le sezioni che contengono informazioni sul traffico da 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
La risposta contiene le sezioni appropriate per il traffico lungo le coordinate indicate.
Questa opzione può essere usata per colorare le sezioni durante il rendering della mappa, come illustrato nell'immagine seguente:
Calcolare e ottimizzare un percorso con più fermate
Mappe di Azure offre attualmente due forme di ottimizzazioni del percorso:
Ottimizzazioni in base al tipo di percorso richiesto, senza modificare l'ordine dei punti del tragitto. Per altre informazioni, vedere RouteType.
Ottimizzazione del venditore in trasferta, che cambia l'ordine dei punti del tragitto per ottenere l'organizzazione migliore per visitare ogni fermata
Per la pianificazione percorso con più soste, è possibile specificare fino a 150 punti del tragitto in una singola richiesta di percorso. Le coordinate di partenza e di arrivo possono essere le stesse, come nel caso di un viaggio di andata e ritorno. Tuttavia, è necessario specificare almeno un altro punto del tragitto per eseguire il calcolo del percorso. I punti del tragitto possono essere aggiunti alla query tra le coordinate di origine e di destinazione.
Se si vuole ottimizzare l'ordine migliore per visitare i punti del tragitto specificati, è necessario indicare computeBestOrder=true. Questo scenario è noto anche come problema di ottimizzazione del venditore in trasferta.
Query di esempio
La query seguente richiede il percorso per sei punti del tragitto, con il parametro computeBestOrder impostato su false. È anche il valore predefinito per il parametro 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
La risposta descrive la lunghezza del percorso di 140.851 metri e che ci vorranno 9.991 secondi per percorrerlo.
L'immagine seguente illustra il percorso risultante da questa query. Questo percorso è uno dei possibili. Non è il percorso ottimale in base al tempo o alla distanza.
Questo ordine del punto del tragitto del percorso è: 0, 1, 2, 3, 4, 5 e 6.
Query di esempio
La query seguente richiede il percorso per gli stessi sei punti del tragitto, come nell'esempio precedente. Questa volta, il parametro computeBestOrder impostato su true (ottimizzazione del venditore in trasferta).
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
La risposta descrive la lunghezza del percorso di 91.814 metri e che ci vorranno 7.797 secondi per percorrerlo. La distanza e il tempo di percorrenza sono entrambi inferiori perché l'API ha restituito il percorso ottimizzato.
L'immagine seguente illustra il percorso risultante da questa query.
Il percorso ottimale presenta il seguente ordine dei punti del tragitto: 0, 5, 1, 2, 4, 3 e 6.
Suggerimento
Le informazioni sull'ordine dei punti del tragitto ottimizzati dal servizio pianificazione percorso forniscono una serie di indici. Questi escludono gli indici di origine e di destinazione. È necessario incrementare questi valori di 1 per tenere conto dell'origine. Quindi, aggiungere la propria destinazione alla fine per ottenere un elenco completo di punti del tragitto ordinati.
Calcolare e fare riferimento a percorsi alternativi utilizzando punti di supporto
Potrebbero verificarsi situazioni in cui si vuole ricostruire un percorso per calcolare zero o più percorsi alternativi per un itinerario di riferimento. Ad esempio, è possibile mostrare i percorsi alternativi dei clienti che passano dal proprio punto vendita al dettaglio. In questo caso, è necessario creare una posizione di riferimento utilizzando dei punti di supporto. Ecco i passaggi per fare riferimento a una posizione:
- Calcolare un percorso così come è e ottenere il percorso dalla risposta di percorso
- Usare il percorso per trovare le posizioni desiderate lungo o vicino al percorso. Ad esempio, è possibile usare la richiesta Point of Interest o eseguire query sui propri dati nel database.
- Ordinare le posizioni in base alla distanza dall'inizio del percorso
- Aggiungere queste posizioni come punti di supporto in una nuova richiesta di percorso a Post Route Directions. Per altre informazioni sui punti di supporto, vedere la documentazione dell'API Post Route Directions.
Quando si chiama Post Route Directions, è possibile impostare il tempo minimo di deviazione o i vincoli di distanza, insieme ai punti di supporto. Usare questi parametri se si desidera offrire percorsi alternativi, ma si vuole anche limitare il tempo di viaggio. Quando vengono usati questi vincoli, i percorsi alternativi seguono il percorso di riferimento dal punto di origine per il tempo o la distanza specificati. In altre parole, gli altri percorsi differiscono dal percorso di riferimento in base ai vincoli specificati.
L'immagine seguente è un esempio di rendering di percorsi alternativi con limiti di deviazione specificati per il tempo e la distanza.
Usare il servizio di pianificazione percorso in un'app Web
L'SDK Web di Mappe di Azure offre un modulo di servizio. Questo modulo è una libreria helper che semplifica l'uso delle API REST di Mappe di Azure in applicazioni Web o Node.js, mediante JavaScript o TypeScript. Il modulo Servizi può essere usato per eseguire il rendering dei percorsi restituiti sulla mappa. Il modulo determina automaticamente l'API da usare con le richieste GET e POST.
Nota
Ritiro del modulo del servizio Web SDK di Mappe di Azure
Il modulo del servizio Web SDK di Mappe di Azure è ora deprecato e verrà ritirato il 30/9/26. Per evitare interruzioni del servizio, è consigliabile eseguire la migrazione all'SDK REST JavaScript di Mappe di Azure entro il 30/9/26. Per altre informazioni, vedere Guida per gli sviluppatori dell'SDK REST JavaScript/TypeScript (anteprima).
Passaggi successivi
Per altre informazioni, vedere: