Best practices voor Azure Kaarten Route-service
De Routebeschrijvingen en Routematrix-API's in Azure Kaarten Routeservice kunnen worden gebruikt om de geschatte aankomsttijden (ETA's) voor elke aangevraagde route te berekenen. Route-API's houden rekening met factoren zoals realtime verkeersinformatie en historische verkeersgegevens, zoals de typische wegsnelheden op de aangevraagde datum en tijd. De API's retourneren de kortste of snelste routes die beschikbaar zijn voor meerdere bestemmingen tegelijk in een reeks of in een geoptimaliseerde volgorde, op basis van tijd of afstand. Gebruikers kunnen ook speciale routes en details aanvragen voor wandelaars, fietsers en bedrijfsvoertuigen, zoals vrachtwagens. In dit artikel worden aanbevolen procedures besproken voor het aanroepen van de Azure Kaarten Route-service, waaronder procedures:
- Kiezen tussen de API's voor routebeschrijvingen en de routerings-API voor matrix
- Historische en voorspelde reistijden aanvragen, op basis van real-time en historische verkeersgegevens
- Routegegevens, zoals tijd en afstand, aanvragen voor de hele route en elk been van de route
- Route aanvragen voor een bedrijfsvoertuig, zoals een vrachtwagen
- Verkeersinformatie langs een route aanvragen, zoals jam- en tolgegevens
- Een route aanvragen die bestaat uit een of meer stops (waypoints)
- Optimaliseer een route van een of meer stops om de beste volgorde te verkrijgen om elke stop te bezoeken (waypoint)
- Alternatieve routes optimaliseren met ondersteunende punten. Bied bijvoorbeeld alternatieve routes aan die een laadstation voor elektrische voertuigen passeren.
- De Route-service gebruiken met de Azure Kaarten Web SDK
Vereisten
Zie Routeringsdekking voor meer informatie over de dekking van de Route-service.
In dit artikel wordt de Postman-toepassing gebruikt om REST-aanroepen te bouwen, maar u kunt elke API-ontwikkelomgeving kiezen.
Kiezen tussen routebeschrijvingen en matrixroutering
De Route routebeschrijving-API's retourneren instructies, waaronder de reistijd en de coördinaten voor een routepad. Met de Route Matrix-API kunt u de reistijd en afstanden berekenen voor een set routes die zijn gedefinieerd door de oorspronkelijke en doellocaties. Voor elke opgegeven oorsprong berekent de Matrix-API de kosten (reistijd en afstand) van routering van die oorsprong naar elke opgegeven bestemming. Met deze API's kunt u parameters opgeven, zoals de gewenste vertrektijd, aankomsttijden en het voertuigtype, zoals auto of vrachtwagen. Ze gebruiken allemaal realtime- of voorspellende verkeersgegevens dienovereenkomstig om de meest optimale routes te retourneren.
Overweeg routebeschrijving-API's aan te roepen als uw scenario het volgende doet:
- Vraag de kortste of snelste rijroute tussen twee of meer bekende locaties aan om nauwkeurige aankomsttijden voor uw bezorgwagens te krijgen.
- Gedetailleerde routerichtlijnen, inclusief routegeometrie, aanvragen om routes op de kaart te visualiseren
- Op basis van een lijst met klantlocaties berekent u de kortst mogelijke route om elke klantlocatie te bezoeken en terug te keren naar de oorsprong. Dit scenario wordt meestal het probleem van de reizende verkoper genoemd. U kunt maximaal 150 waypoints (stops) doorgeven in één aanvraag.
- Verzend batches met query's naar de Batch-API routebeschrijving met slechts één API-aanroep.
Overweeg om matrixrouterings-API aan te roepen als uw scenario het volgende doet:
- Bereken de reistijd of afstand tussen een reeks oorsprongen en bestemmingen. U hebt bijvoorbeeld 12 chauffeurs en u moet de dichtstbijzijnde beschikbare chauffeur vinden om de voedselbezorging van het restaurant op te halen.
- Sorteer potentiële routes op de werkelijke reisafstand of -tijd. De Matrix-API retourneert alleen reistijden en afstanden voor elke combinatie van oorsprong en bestemming.
- Clustergegevens op basis van reistijd of afstanden. Uw bedrijf heeft bijvoorbeeld 50 werknemers, alle werknemers die binnen 20 minuten rijden van uw kantoor wonen.
Hier volgt een vergelijking om enkele mogelijkheden van de Routebeschrijvingen en matrix-API's weer te geven:
| Azure Kaarten-API | Maximum aantal query's in de aanvraag | Gebieden vermijden | Vrachtwagen- en elektrische voertuigroutering | Optimalisatie van Waypoints en Reizende verkoper | Ondersteunende punten |
|---|---|---|---|---|---|
| Routebeschrijving ophalen | 1 | ✔ | ✔ | ||
| Routebeschrijving posten | 1 | ✔ | ✔ | ✔ | ✔ |
| Routebeschrijving na batch | 700 | ✔ | ✔ | ||
| Post-routematrix | 700 | ✔ |
Zie onze zelfstudie over het routeren van elektrische voertuigen met Behulp van Azure Notebooks met Python voor meer informatie over routeringsmogelijkheden voor elektrische voertuigen.
Historische en realtime gegevens aanvragen
Standaard gaat de Route-service ervan uit dat de reismodus een auto is en dat de vertrektijd nu is. Deze retourneert route op basis van realtime verkeersomstandigheden, tenzij een routeberekeningsaanvraag anders aangeeft. De routeringsengine factoren vaste tijdafhankelijke verkeersbeperkingen, zoals 'Linkse bochten zijn niet toegestaan tussen 16:00 en 18:00'. Wegsluitingen, zoals wegenwerken, worden overwogen, tenzij u specifiek een route aanvraagt die het huidige live verkeer negeert. Als u het huidige verkeer wilt negeren, stelt u deze false in traffic uw API-aanvraag in.
De routeberekeningswaarde travelTimeInSeconds bevat de vertraging vanwege verkeer. Deze wordt gegenereerd met behulp van de huidige en historische reistijdgegevens, wanneer de vertrektijd is ingesteld op nu. Als uw vertrektijd in de toekomst is ingesteld, retourneren de API's voorspelde reistijden op basis van historische gegevens.
Als u de parameter computeTravelTimeFor=all in uw aanvraag opneemt, bevat het samenvattingselement in het antwoord de volgende velden, waaronder historische verkeersvoorwaarden:
| Element | Beschrijving |
|---|---|
| noTrafficTravelTimeInSeconds | Geschatte reistijd berekend alsof er geen vertragingen op de route zijn vanwege verkeersomstandigheden, bijvoorbeeld vanwege congestie |
| historicTrafficTravelTimeInSeconds | Geschatte reistijd berekend met tijdafhankelijke historische verkeersgegevens |
| liveTrafficIncidentsTravelTimeInSeconds | Geschatte reistijd berekend met realtime snelheidsgegevens |
In de volgende secties ziet u hoe u aanroepen naar de Route-API's uitvoert met behulp van de besproken parameters.
Voorbeeldquery
In het eerste voorbeeld hieronder wordt de vertrektijd ingesteld op de toekomst, op het moment van schrijven.
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
Het antwoord bevat een samenvattingselement, zoals in het volgende voorbeeld. Omdat de vertrektijd is ingesteld op de toekomst, is de waarde trafficDelayInSeconds nul. De travelTimeInSeconds-waarde wordt berekend met tijdafhankelijke historische verkeersgegevens. In dit geval is de travelTimeInSeconds-waarde dus gelijk aan de waarde 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
},
Voorbeeldquery
In het volgende voorbeeld hebben we een realtime routeringsaanvraag, waar de vertrektijd nu is. Deze is niet expliciet opgegeven in de URL omdat dit de standaardwaarde is.
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
Het antwoord bevat een samenvatting, zoals wordt weergegeven in het volgende voorbeeld. Vanwege congestie is de waarde trafficDelaysInSeconds groter dan nul. Het is ook groter dan historischeTrafficTravelTimeInSeconds.
"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
},
Route- en beengegevens aanvragen
Standaard retourneert de Route-service een matrix met coördinaten. Het antwoord bevat de coördinaten waaruit het pad bestaat in een lijst met de naam points. Routereactie omvat ook de afstand van het begin van de route en de geschatte verstreken tijd. Deze waarden kunnen worden gebruikt om de gemiddelde snelheid voor de hele route te berekenen.
In de volgende afbeelding ziet u het points element.
Vouw het point element uit om de lijst met coördinaten voor het pad weer te geven:
De Route Directions-API's ondersteunen verschillende indelingen van instructies die kunnen worden gebruikt door de parameter instructionsType op te geven. Als u instructies wilt opmaken voor eenvoudige computerverwerking, gebruikt u instructionsType=coded. Gebruik instructionsType=tagged om instructies weer te geven als tekst voor de gebruiker. Ook kunnen instructies worden opgemaakt als tekst waarbij sommige elementen van de instructies worden gemarkeerd en de instructie wordt weergegeven met speciale opmaak. Zie de lijst met ondersteunde instructietypen voor meer informatie.
Wanneer er instructies worden aangevraagd, retourneert het antwoord een nieuw element met de naam guidance. Het guidance element bevat twee stukjes informatie: kant-en-klare aanwijzingen en samengevatte instructies.
Het instructions element bevat stapsgewijze aanwijzingen voor de reis en de instructionGroups instructies zijn samengevat. Elk instructieoverzicht heeft betrekking op een segment van de reis die meerdere wegen kan bedekken. De API's kunnen details retourneren voor secties van een route. zoals het coördinaatbereik van een verkeersopstopping of de huidige snelheid van het verkeer.
Een route aanvragen voor een bedrijfsvoertuig
Azure Kaarten Routing-API's ondersteunen routering van bedrijfsvoertuigen, met betrekking tot de routering van commerciële vrachtwagens. De API's beschouwen opgegeven limieten. Zoals de hoogte en het gewicht van het voertuig en als het voertuig gevaarlijke lading vervoert. Als een voertuig bijvoorbeeld brandbaar is, vermijdt de routeringsmotor bepaalde tunnels die zich in de buurt van woonwijken bevinden.
Voorbeeldquery
Met de onderstaande voorbeeldaanvraag wordt een route voor een commerciële vrachtwagen opgevraagd. De vrachtwagen draagt klasse 1 gevaarlijk afvalmateriaal.
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
De Route-API retourneert aanwijzingen die geschikt zijn voor de afmetingen van de vrachtwagen en het gevaarlijke afval. U kunt de route-instructies lezen door het element uit te guidance vouwen.
Voorbeeldquery
Als u de Us Hazmat-klasse wijzigt, resulteert dit uit de bovenstaande query in een andere route om aan deze wijziging tegemoet te komen.
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
Het volgende antwoord is voor een vrachtwagen met een klasse 9 gevaarlijk materiaal, dat minder gevaarlijk is dan een gevaarlijk materiaal van klasse 1. Wanneer u het guidance element uitvouwt om de aanwijzingen te lezen, ziet u dat de aanwijzingen niet hetzelfde zijn. Er zijn meer route-instructies voor de vrachtwagen met klasse 1 gevaarlijk materiaal.
Verkeersinformatie langs een route aanvragen
Met de Api's voor Routerichting van Azure Kaarten kunnen ontwikkelaars details aanvragen voor elk sectietype door de sectionType parameter in de aanvraag op te geven. U kunt bijvoorbeeld de snelheidsgegevens voor elk verkeers jamsegment aanvragen. Raadpleeg de lijst met waarden voor de sectionType-sleutel voor meer informatie over de verschillende details die u kunt aanvragen.
Voorbeeldquery
Met de volgende query wordt ingesteld sectionType op traffic. Het vraagt de secties die verkeersinformatie van Seattle naar San Diego bevatten.
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
Het antwoord bevat de secties die geschikt zijn voor verkeer langs de opgegeven coördinaten.
Deze optie kan worden gebruikt om de secties te kleuren bij het weergeven van de kaart, zoals in de volgende afbeelding:
Een multi-stop-route berekenen en optimaliseren
Azure Kaarten biedt momenteel twee soorten routeoptimalisaties:
Optimalisaties op basis van het aangevraagde routetype, zonder de volgorde van waypoints te wijzigen. Zie RouteType voor meer informatie.
Reizende verkoopmanoptimalisatie, die de volgorde van de waypoints wijzigt om de beste volgorde te verkrijgen om elke stop te bezoeken
Voor routering met meerdere stops kunnen maximaal 150 waypoints worden opgegeven in één routeaanvraag. De begin- en eindcoördinaatlocaties kunnen hetzelfde zijn, net als bij een retour. Maar u moet ten minste één waypoint opgeven om de routeberekening uit te voeren. Waypoints kunnen worden toegevoegd aan de query tussen de coördinaten van de oorsprong en de bestemming.
Als u de beste volgorde wilt optimaliseren om de opgegeven waypoints te bezoeken, moet u computeBestOrder=true opgeven. Dit scenario wordt ook wel het probleem met de optimalisatie van de reizende verkoper genoemd.
Voorbeeldquery
De volgende query vraagt het pad voor zes waypoints aan, waarbij de computeBestOrder parameter is ingesteld op false. Dit is ook de standaardwaarde voor de computeBestOrder parameter.
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
Het antwoord beschrijft de padlengte van 140.851 meter en dat het 9.991 seconden duurt om dat pad te reizen.
In de volgende afbeelding ziet u het pad dat het resultaat is van deze query. Dit pad is één mogelijke route. Het is niet het optimale pad op basis van tijd of afstand.
Deze routerichtingspuntvolgorde is: 0, 1, 2, 3, 4, 5 en 6.
Voorbeeldquery
Met de volgende query wordt het pad voor dezelfde zes waypoints aangevraagd, zoals in het bovenstaande voorbeeld. Deze keer is de computeBestOrder parameter ingesteld op true (de optimalisatie van de reizende verkoper).
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
Het antwoord beschrijft de padlengte van 91.814 meter en dat het 7.797 seconden duurt om dat pad te reizen. De reisafstand en de reistijd zijn hier beide lager omdat de API de geoptimaliseerde route heeft geretourneerd.
In de volgende afbeelding ziet u het pad dat het resultaat is van deze query.
De optimale route heeft de volgende waypointvolgorde: 0, 5, 1, 2, 4, 3 en 6.
Tip
De geoptimaliseerde waypoint-orderinformatie van de routeringsservice biedt een set indexen. Deze sluiten de oorsprong en de doelindexen uit. U moet deze waarden verhogen met 1 om rekening te houden met de oorsprong. Voeg vervolgens uw bestemming toe aan het einde om de volledige geordende waypoint-lijst op te halen.
Alternatieve routes berekenen en voortekenen met ondersteunende punten
Mogelijk hebt u situaties waarin u een route wilt reconstrueren om nul of meer alternatieve routes voor een referentieroute te berekenen. U kunt bijvoorbeeld alternatieve routes voor klanten weergeven die uw winkel passeren. In dit geval moet u een locatie vertekenen met behulp van ondersteunende punten. Hier volgen de stappen om een locatie te vertekenen:
- Een route als zodanig berekenen en het pad ophalen uit het routeantwoord
- Gebruik het routepad om de gewenste locaties langs of in de buurt van het routepad te vinden. U kunt bijvoorbeeld de aanvraag Point of Interest gebruiken of uw eigen gegevens in uw database opvragen.
- De locaties bestellen op basis van de afstand van het begin van de route
- Voeg deze locaties toe als ondersteunende punten in een nieuwe routeaanvraag voor routebeschrijvingen na de route. Zie de DOCUMENTATIE van de Post Route Directions-API voor meer informatie over de ondersteunende punten.
Bij het aanroepen van routebeschrijvingen na route kunt u de minimale afwijkingstijd of de afstandsbeperkingen instellen, samen met de ondersteunende punten. Gebruik deze parameters als u alternatieve routes wilt aanbieden, maar u wilt ook de reistijd beperken. Wanneer deze beperkingen worden gebruikt, volgen de alternatieve routes de referentieroute vanaf het oorspronkelijke punt voor de opgegeven tijd of afstand. Met andere woorden, de andere routes afwijken van de referentieroute volgens de opgegeven beperkingen.
De volgende afbeelding is een voorbeeld van het weergeven van alternatieve routes met opgegeven afwijkingslimieten voor de tijd en de afstand.
De routeringsservice gebruiken in een web-app
De Azure Kaarten Web SDK biedt een servicemodule. Deze module is een helperbibliotheek waarmee u de Azure Kaarten REST API's eenvoudig kunt gebruiken in webtoepassingen of Node.js toepassingen, met behulp van JavaScript of TypeScript. De servicemodule kan worden gebruikt om de geretourneerde routes op de kaart weer te geven. De module bepaalt automatisch welke API moet worden gebruikt met GET- en POST-aanvragen.
Notitie
Buitengebruikstelling van Azure Kaarten Web SDK-servicemodule
De Azure Kaarten Web SDK-servicemodule is nu afgeschaft en wordt buiten gebruik gesteld op 30-9-26. Om serviceonderbrekingen te voorkomen, wordt u aangeraden om te migreren naar de Azure Kaarten JavaScript REST SDK voor 30-9-26. Zie de ontwikkelaarshandleiding voor JavaScript/TypeScript REST SDK (preview) voor meer informatie.
Volgende stappen
Zie voor meer informatie: