Best practices voor Azure Kaarten Route-service

De API's routebeschrijvingen en routematrix in Azure Kaarten Route Service 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 snelheden op de aangevraagde dag van de week en het tijdstip van de dag. 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 gespecialiseerde routes en details aanvragen voor gebruikers, fietsen en commerciële voertuigen zoals vrachtwagens. In dit artikel delen we de best practices voor het aanroepen van Azure Kaarten Route Serviceen leert u hoe u het volgende kunt doen:

• Kiezen tussen de API's voor routebeschrijvingen en de API voor matrixroutering
• Historische en voorspelde reistijden aanvragen, op basis van real-time en historische verkeersgegevens
• Routedetails, zoals tijd en afstand, aanvragen voor de hele route en elk deel van de route
• Route aanvragen voor een commercieel voertuig, zoals een vrachtwagen
• Verkeersinformatie aanvragen langs een route, zoals jam en tolgegevens
• Een route aanvragen die bestaat uit een of meer stops (waypoints)
• Een route van een of meer stops optimaliseren om de beste volgorde te verkrijgen voor het bezoeken van elke stop (waypoint)
• Optimaliseer alternatieve routes met behulp van ondersteunende punten. U kunt bijvoorbeeld alternatieve routes aanbieden die door een laadstation voor elektrische voertuigen gaan.
• De Route Service gebruiken met de Azure Kaarten Web SDK

Vereisten

1. Een Azure Maps-account maken
2. Een primaire sleutel voor een abonnement verkrijgen, ook wel bekend als de primaire sleutel of de abonnementssleutel.

Zie Routeringsdekking voor meer informatie over de dekking van de Route Service.

In dit artikel wordt de Postman-app gebruikt om REST-aanroepen te maken, maar u kunt elke API-ontwikkelomgeving kiezen.

Kiezen tussen routebeschrijvingen en matrixroutering

De Route Directions-API's retourneren instructies met inbegrip van de reistijd en de coördinaten voor een routepad. Met de Routematrix-API kunt u de reistijd en afstanden berekenen voor een set routes die zijn gedefinieerd op basis van de herkomst- en doellocaties. Voor elke bepaalde oorsprong berekent de Matrix-API de kosten (reistijd en afstand) van de routering van die oorsprong naar elke bepaalde bestemming. Met al deze API's kunt u parameters opgeven, zoals de gewenste vertrektijd, aankomsttijden en het type voertuig, zoals auto of vrachtwagen. Ze gebruiken allemaal realtime of voorspellende verkeersgegevens om de meest optimale routes te retourneren.

Overweeg het aanroepen van Route Directions-API's als uw scenario het volgende doet:

• Vraag de kortste of snelste route aan tussen twee of meer bekende locaties om nauwkeurige aankomsttijden voor uw bezorgers te krijgen.
• Gedetailleerde route-richtlijnen aanvragen, inclusief routegeometrie, om routes op de kaart te visualiseren
• Bereken op basis van een lijst met klantlocaties de kortst mogelijke route om elke klantlocatie te bezoeken en terug te keren naar de oorsprong. Dit scenario wordt vaak het probleem van een reizende verkoper genoemd. U kunt maximaal 150 waypoints (stops) in één aanvraag doorgeven.
• Verzend batches met query's naar de Batch-API routebeschrijvingen met slechts één API-aanroep.

U kunt matrixrouterings-API aanroepen als u het volgende wilt doen:

• De reistijd of afstand tussen een set oorsprongen en bestemmingen berekenen. U hebt bijvoorbeeld 12 stuurprogramma's en u moet de dichtstbijzijnde beschikbare stuurprogramma vinden om de bezorging van het restaurant op te halen.
• Mogelijke routes sorteren op hun werkelijke reisafstand of -tijd. De Matrix-API retourneert alleen reistijden en afstanden voor elke combinatie van herkomst en bestemming.
• Cluster gegevens op basis van reistijd of afstanden. Uw bedrijf heeft bijvoorbeeld 50 werknemers en vindt alle werknemers die binnen 20 minuten in de rijtijd van uw kantoor wonen.

Hier is een vergelijking om enkele mogelijkheden van de API's Routebeschrijving en Matrix weer te geven:

Zie voor meer informatie over de routeringsmogelijkheden voor elektrische voertuigen onze zelfstudie over het routeren van elektrische voertuigen met behulp van Azure Notebooks met Python.

Historische en realtime gegevens aanvragen

De standaardinstelling Route-service dat de reismodus een auto is en de vertrektijd nu. Deze retourneert een route op basis van realtime verkeersomstandigheden, tenzij een aanvraag voor routeberekening anders aangeeft. Er zijn tijdafhankelijke verkeersbeperkingen vastgelegd, zoals 'Linker draaien zijn niet toegestaan tussen 16:00 uur en 18:00 uur' en worden in aanmerking genomen door de routeringsen engine. Wegafsluitingen, zoals wegwerkzaamheden, worden overwogen, tenzij u specifiek een route aanvraagt die het huidige liveverkeer negeert. Als u het huidige verkeer wilt negeren, stelt u traffic false in uw API-aanvraag in op .

De travelTimeInSeconds-waarde van de routeberekening bevat de vertraging die wordt veroorzaakt door verkeer. Deze wordt gegenereerd door gebruik te maken van de huidige en historische reistijdgegevens, wanneer de vertrektijd is ingesteld op nu. Als de 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 opgeeft, bevat het samenvattingselement in het antwoord de volgende aanvullende velden, waaronder historische verkeersomstandigheden:

In de volgende secties wordt gedemonstreerd hoe u de Route-API's aanroept met behulp van de besproken parameters.

Voorbeeldquery

In het eerste voorbeeld onder de vertrektijd is ingesteld op de toekomst, op het moment van schrijven.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Primary-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 het onderstaande. Omdat de vertrektijd is ingesteld op de toekomst, is de waarde trafficDelayInSeconds nul. De travelTimeInSeconds-waarde wordt berekend met behulp van tijdafhankelijke historische verkeersgegevens. In dit geval is de waarde travelTimeInSeconds 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 tweede voorbeeld hieronder hebben we een realtime routeringsaanvraag, waarbij de vertrektijd nu is. Deze wordt niet expliciet opgegeven in de URL, omdat dit de standaardwaarde is.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Primary-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 hieronder wordt weergegeven. Vanwege congestie is de waarde trafficDelaysInSeconds groter dan nul. Het is ook groter dan de 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 Route-service een matrix met coördinaten. Het antwoord bevat de coördinaten die samen het pad in een lijst met de naam points bevatten. Routereactie bevat 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 gegeven:

De Route Directions-API's ondersteunen verschillende indelingen van instructies die kunnen worden gebruikt door de parameter instructionsType op te geven. Als u instructies voor eenvoudige computerverwerking wilt opmaken, gebruikt u instructionsType=gecodeerd. Gebruik instructionsType=tagged om instructies weer te geven als tekst voor de gebruiker. Instructies kunnen ook worden opgemaakt als tekst waarbij bepaalde elementen van de instructies zijn gemarkeerd en de instructie een speciale opmaak krijgt. Zie de lijst met ondersteunde instructietypen voor meer informatie.

Wanneer instructies worden aangevraagd, retourneert het antwoord een nieuw element met de naam guidance . Het guidance element bevat twee soorten informatie: kant-en-weer-richting en samengevatte instructies.

Het instructions element bevat af-en-weer-instructies voor de reis en de instructionGroups bevat een overzicht van de instructies. Elke instructiesamenvatting heeft betrekking op een segment van de rit dat meerdere wegen kan omvatten. De API's kunnen details voor secties van een route retourneren. zoals het coördinatenbereik van een verkeersopstopping of de huidige snelheid van verkeer.

Een route aanvragen voor een commercieel voertuig

Azure Kaarten Routing-API's ondersteunen routering van commerciële voertuigen, die de routering van commerciële vrachtwagens beslaat. De API's overwegen opgegeven limieten. Zoals de hoogte en het gewicht van het voertuig en of het voertuig gevaarlijke lading vervoert. Als een voertuig bijvoorbeeld brandbaar is, vermijdt de routeringsen engine bepaalde tunnels in de buurt van woongebieden.

Voorbeeldquery

In de voorbeeldaanvraag hieronder wordt een query op een route voor een commerciële vrachtwagen opgevraagd. De vrachtwagen vervoert gevaarlijke afval van klasse 1.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Primary-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 routebeschrijvingen 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 breiden.

Voorbeeldquery

Als u de klasse US Wiltmat wijzigt op grond van de bovenstaande query, resulteert dit in een andere route om deze wijziging aan te kunnen.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Primary-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 onderstaande antwoord is voor een vrachtwagen met gevaarlijke stoffen van klasse 9, die minder gevaarlijk is dan gevaarlijke stoffen van klasse 1. Wanneer u het element uitv vouwt om de routebeschrijving te lezen, ziet u dat guidance de routebeschrijvingen niet hetzelfde zijn. Er zijn meer route-instructies voor de vrachtwagen met klasse 1 gevaarlijke stoffen.

Verkeersgegevens langs een route aanvragen

Met de Azure Kaarten Route Direction-API's kunnen ontwikkelaars details voor elk sectietype aanvragen door de parameter op te nemen sectionType in de aanvraag. U kunt bijvoorbeeld de snelheidsgegevens voor elk segment met files aanvragen. Raadpleeg de lijst met waarden voor de sectieTypesleutel voor meer informatie over de verschillende details die u kunt aanvragen.

Voorbeeldquery

Met de volgende query stelt u sectionType de in op traffic . Er worden de secties met verkeersgegevens van Seattle naar San Hadoe op gevraagd.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Primary-Subscription-key}&api-version=1.0&sectionType=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 onderstaande 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 de routepunten te wijzigen. U vindt de ondersteunde routetypen hier

• Reizende optimalisatie van verkopers, waarmee de volgorde van de waypoints wordt gewijzigd om de beste volgorde te verkrijgen om elke stop te bezoeken

Voor multi-stop-routering kunnen maximaal 150 routepunten worden opgegeven in één routeaanvraag. De begin- en eindcoördinatenlocaties kunnen hetzelfde zijn, zoals het geval is bij een retour. Maar u moet ten minste één extra waypoint verstrekken om de routeberekening te maken. Waypoints kunnen worden toegevoegd aan de query tussen de coördinaten van de oorsprong en het doel.

Als u de beste volgorde wilt optimaliseren om de opgegeven waypoints te bezoeken, moet u computeBestOrder=true opgeven. Dit scenario wordt ook wel het reizende optimalisatieprobleem voor verkopers genoemd.

Voorbeeldquery

Met de volgende query wordt het pad voor zes waypoints opgevraagd, met computeBestOrder de parameter ingesteld op false . Het is ook de standaardwaarde voor de computeBestOrder parameter .

https://atlas.microsoft.com/route/directions/json?api-version=1.0&subscription-key={Your-Azure-Maps-Primary-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 het zou 9991 seconden duren om dat pad te volgen.

In de onderstaande afbeelding ziet u het pad dat het resultaat is van deze query. Dit pad is een mogelijke route. Het is niet het optimale pad op basis van tijd of afstand.

Deze route waypoint-volgorde is: 0, 1, 2, 3, 4, 5 en 6.

Voorbeeldquery

Met de volgende query wordt het pad voor dezelfde zes waypoints opgevraagd, zoals in het bovenstaande voorbeeld. Deze keer wordt de computeBestOrder parameter ingesteld op true (de reizende salesman-optimalisatie).

https://atlas.microsoft.com/route/directions/json?api-version=1.0&subscription-key={Your-Azure-Maps-Primary-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 het zou 7797 seconden duren om dat pad te volgen. De reisafstand en de reistijd zijn hier beide lager omdat de API de geoptimaliseerde route heeft geretourneerd.

In de onderstaande afbeelding ziet u het pad dat het resultaat is van deze query.

De optimale route heeft de volgende routepuntvolgorde: 0, 5, 1, 2, 4, 3 en 6.

Alternatieve routes berekenen en vertekenen met behulp van 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 laten zien die uw winkel passeren. In dit geval moet u een locatie vertekenen met behulp van ondersteunende punten. Hier volgen de stappen voor het vooroordelen van een locatie:

1. Een route as-is berekenen en het pad uit het route-antwoord op halen
2. Gebruik het routepad om de gewenste locaties langs of in de buurt van het routepad te vinden. U kunt bijvoorbeeld Azure Kaarten Point of Interest-API gebruiken of een query uitvoeren op uw eigen gegevens in uw database.
3. De locaties orden op basis van de afstand van het begin van de route
4. Voeg deze locaties toe als ondersteunende punten in een nieuwe routeaanvraag aan de Post Route Directions-API. Zie de Post Route Directions API-documentatievoor meer informatie over de ondersteunende punten.

Wanneer u de POST Route Directions-APIaanroept, 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 ook de reistijd wilt beperken. Wanneer deze beperkingen worden gebruikt, volgen de alternatieve routes de referentieroute vanaf het beginpunt voor de opgegeven tijd of afstand. Met andere woorden, de andere routes verschillen van de referentieroute op basis van de opgegeven beperkingen.

De onderstaande 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 die het eenvoudig maakt om de Azure Kaarten REST API's te gebruiken in web- 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.

Volgende stappen

Zie voor meer informatie: