Metodtips för Azure Kartor Route-tjänsten
Routningsriktningar och routningsmatris-API:er i Azure Kartor Route-tjänsten kan användas för att beräkna de uppskattade ankomsttiderna (ETA) för varje begärd väg. Väg-API:er beaktar faktorer som trafikinformation i realtid och historiska trafikdata, till exempel de typiska väghastigheterna på det begärda datumet och tiden. API:erna returnerar de kortaste eller snabbaste vägarna som är tillgängliga för flera mål i följd eller i optimerad ordning baserat på tid eller avstånd. Användare kan också begära specialiserade vägar och information för vandrare, cyklister och kommersiella fordon som lastbilar. I den här artikeln beskrivs metodtips för att anropa Tjänsten Azure Kartor Route, inklusive instruktioner:
- Välj mellan API:er för routningsriktningar och API:et för matrisroutning
- Begära historiska och förväntade restider baserat på trafikdata i realtid och historiska trafikdata
- Begär väginformation, till exempel tid och avstånd, för hela vägen och varje del av rutten
- Begär väg för ett nyttofordon, som en lastbil
- Begär trafikinformation längs en väg, till exempel trafikstockningar och avgiftsinformation
- Begär en väg som består av en eller flera stopp (waypoints)
- Optimera en väg med en eller flera stopp för att få den bästa ordningen för att besöka varje stopp (waypoint)
- Optimera alternativa vägar med hjälp av stödpunkter. Du kan till exempel erbjuda alternativa vägar som passerar en laddningsstation för elfordon.
- Använda routningstjänsten med Azure Kartor Web SDK
Förutsättningar
Mer information om routningstjänstens täckning finns i Routningstäckning.
Den här artikeln använder Postman-programmet för att skapa REST-anrop, men du kan välja vilken API-utvecklingsmiljö som helst.
Välj mellan vägbeskrivningar och matrisroutning
API:erna för vägbeskrivningar returnerar instruktioner, inklusive restid och koordinater för en vägsökväg. Med API:et routningsmatris kan du beräkna restiden och avstånden för en uppsättning vägar som definieras av ursprungs- och målplatser. För varje angivet ursprung beräknar Matris-API:et kostnaden (restid och avstånd) för routning från det ursprunget till varje angivet mål. Med dessa API:er kan du ange parametrar som önskad avgångstid, ankomsttider och fordonstyp, till exempel bil eller lastbil. De använder alla realtids- eller förutsägande trafikdata för att returnera de mest optimala vägarna.
Överväg att anropa Routningsriktnings-API:er om ditt scenario är att:
- Begär den kortaste eller snabbaste körvägen mellan två eller flera kända platser för att få exakta ankomsttider för dina leveransfordon.
- Begär detaljerad vägvägledning, inklusive routningsgeometri, för att visualisera vägar på kartan
- Med en lista över kundplatser beräknar du den kortaste möjliga vägen för att besöka varje kundplats och återgå till ursprunget. Det här scenariot kallas ofta för det resande försäljareproblemet. Du kan skicka upp till 150 vägpunkter (stopp) i en begäran.
- Skicka batchar med frågor till Batch-API:et Route Directions med bara ett enda API-anrop.
Överväg att anropa API för matrisroutning om ditt scenario är att:
- Beräkna restiden eller avståndet mellan en uppsättning ursprung och mål. Till exempel har du 12 förare och du måste hitta den närmaste tillgängliga föraren för att hämta matleveransen från restaurangen.
- Sortera potentiella vägar efter deras faktiska resavstånd eller tid. Matris-API:et returnerar endast restider och avstånd för varje kombination av ursprung och mål.
- Klusterdata baserat på restid eller avstånd. Ditt företag har till exempel 50 anställda och hittar alla anställda som bor inom 20 minuters körtid från ditt kontor.
Här är en jämförelse för att visa några funktioner i routningsriktningar och matris-API:er:
| Azure Kartor API | Maximalt antal frågor i begäran | Undvik områden | Lastbils- och elfordonsdirigering | Waypoints och Traveling Salesman-optimering | Stödpunkter |
|---|---|---|---|---|---|
| Hämta vägbeskrivningar | 1 | ✔ | ✔ | ||
| Vägbeskrivning efter väg | 1 | ✔ | ✔ | ✔ | ✔ |
| Batch för vägbeskrivning efter väg | 700 | ✔ | ✔ | ||
| Matris efter väg | 700 | ✔ |
Mer information om routningsfunktioner för elfordon finns i vår självstudie om hur du dirigerar elfordon med Hjälp av Azure Notebooks med Python.
Begära historiska data och realtidsdata
Som standard förutsätter routningstjänsten att reseläget är en bil och att avgångstiden är nu. Den returnerar väg baserat på trafikförhållanden i realtid såvida inte en begäran om vägberäkning anger något annat. Routningsmotorn faktorer fasta tidsberoende trafikbegränsningar, till exempel "Vänstersvängar tillåts inte mellan 16:00 och 18:00". Vägavstängningar, till exempel vägarbeten, beaktas om du inte specifikt begär en väg som ignorerar den aktuella livetrafiken. Om du vill ignorera den aktuella trafiken anger du traffic till false i din API-begäran.
Värdet för vägberäkningen travelTimeInSeconds innehåller fördröjningen på grund av trafik. Den genereras med hjälp av aktuella och historiska restidsdata, när avgångstiden är inställd på nu. Om din avgångstid anges i framtiden returnerar API:erna förutsagda restider baserat på historiska data.
Om du inkluderar parametern computeTravelTimeFor=all i din begäran har sammanfattningselementet i svaret följande fält, inklusive historiska trafikförhållanden:
| Element | Description |
|---|---|
| noTrafficTravelTimeInSeconds | Beräknad restid beräknad som om det inte finns några fördröjningar på vägen på grund av trafikförhållanden, till exempel på grund av överbelastning |
| historicTrafficTravelTimeInSeconds | Beräknad restid beräknad med tidsberoende historiska trafikdata |
| liveTrafficIncidentsTravelTimeInSeconds | Beräknad restid beräknad med hjälp av hastighetsdata i realtid |
I nästa avsnitt visas hur du gör anrop till routnings-API:erna med hjälp av de diskuterade parametrarna.
Exempelfråga
I det första exemplet under är avgångstiden inställd på framtiden, i skrivande stund.
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
Svaret innehåller ett sammanfattningselement, som i följande exempel. Eftersom avgångstiden är inställd på framtiden är värdet trafficDelayInSeconds noll. Värdet travelTimeInSeconds beräknas med hjälp av tidsberoende historiska trafikdata. Så i det här fallet är värdet travelTimeInSeconds lika med värdet 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
},
Exempelfråga
I nästa exempel har vi en begäran om routning i realtid, där avgångstiden är nu. Det anges inte uttryckligen i URL:en eftersom det är standardvärdet.
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
Svaret innehåller en sammanfattning som visas i följande exempel. På grund av överbelastning är värdet trafficDelaysInSeconds större än noll. Det är också större än 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
},
Begär väg- och beninformation
Som standard returnerar Route-tjänsten en matris med koordinater. Svaret innehåller koordinaterna som utgör sökvägen i en lista med namnet points. Routningssvaret omfattar även avståndet från början av vägen och den beräknade förflutna tiden. Dessa värden kan användas för att beräkna den genomsnittliga hastigheten för hela vägen.
Följande bild visar elementet points .
Expandera elementet point för att se listan över koordinater för sökvägen:
API:er för vägbeskrivningar stöder olika format av instruktioner som kan användas genom att ange parametern instructionsType . Om du vill formatera instruktioner för enkel datorbearbetning använder du instructionsType=coded. Använd instructionsType=tagged för att visa instruktioner som text för användaren. Instruktioner kan också formateras som text där vissa element i instruktionerna markeras och instruktionen visas med särskild formatering. Mer information finns i listan över instruktionstyper som stöds.
När instruktioner begärs returnerar svaret ett nytt element med namnet guidance. Elementet guidance innehåller två informationsdelar: sväng-för-sväng-riktningar och sammanfattade instruktioner.
Elementet instructions innehåller sväng-för-sväng-riktningar för resan och instructionGroups har sammanfattade instruktioner. Varje instruktionssammanfattning omfattar ett segment av resan som kan omfatta flera vägar. API:erna kan returnera information för avsnitt i en väg. till exempel koordinatintervallet för en trafikstockning eller den aktuella hastigheten för trafiken.
Begära en väg för ett nyttofordon
Azure Kartor Routnings-API:er har stöd för trafikdirigering av kommersiella fordon, som omfattar trafikdirigering av kommersiella lastbilar. API:erna överväger angivna gränser. Till exempel fordonets höjd och vikt och om fordonet transporterar farlig last. Om ett fordon till exempel transporterar brandfarligt undviker routningsmotorn vissa tunnlar som ligger nära bostadsområden.
Exempelfråga
Exempelbegäran nedan frågar en väg för en kommersiell lastbil. Lastbilen transporterar farligt avfall av klass 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
Routnings-API:et returnerar riktningar som passar lastbilens dimensioner och det farliga avfallet. Du kan läsa väginstruktionerna genom att expandera elementet guidance .
Exempelfråga
Om du ändrar den amerikanska Hazmat-klassen, från ovanstående fråga, resulterar det i en annan väg för att hantera den här ändringen.
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
Följande svar gäller för en lastbil som transporterar ett farligt material av klass 9, vilket är mindre farligt än ett klass 1-farligt material. När du expanderar elementet guidance för att läsa anvisningarna ser du att anvisningarna inte är desamma. Det finns fler väginstruktioner för lastbilen som transporterar farligt material av klass 1.
Begär trafikinformation längs en väg
Med API:erna för Vägriktning i Azure Kartor kan utvecklare begära information om varje avsnittstyp genom att inkludera parametern sectionType i begäran. Du kan till exempel begära hastighetsinformation för varje trafikstockningssegment. Se listan med värden för nyckeln sectionType för att lära dig mer om de olika detaljer som du kan begära.
Exempelfråga
Följande fråga anger sectionType till traffic. Den begär de avsnitt som innehåller trafikinformation från Seattle till 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
Svaret innehåller de avsnitt som är lämpliga för trafik längs de angivna koordinaterna.
Det här alternativet kan användas för att färglägga avsnitten när kartan återges, som i Följande bild:
Beräkna och optimera rutt med flera stopp
Azure Kartor tillhandahåller för närvarande två typer av vägoptimeringar:
Optimeringar baserat på den begärda vägtypen, utan att ändra ordning på vägpunkter. Mer information finns i RouteType.
Reseförsäljningsoptimering, vilket ändrar ordningen på vägpunkterna för att få den bästa ordningen att besöka varje stopp
För routning med flera stopp kan upp till 150 vägpunkter anges i en enda routningsbegäran. Koordinatplatserna för start och slut kan vara desamma, vilket skulle vara fallet med en tur och retur-resa. Men du måste ange minst en vägpunkt till för att göra vägberäkningen. Waypoints kan läggas till i frågan mellan ursprungs- och målkoordinaterna.
Om du vill optimera den bästa ordningen för att besöka de angivna vägpunkterna måste du ange computeBestOrder=true. Det här scenariot kallas även optimeringsproblem för resande säljare.
Exempelfråga
Följande fråga begär sökvägen för sex waypoints, med parametern inställd på computeBestOrderfalse. Det är också standardvärdet för parametern 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
Svaret beskriver sökvägslängden till 140 851 meter och att det skulle ta 9 991 sekunder att färdas den vägen.
Följande bild illustrerar sökvägen som är resultatet av den här frågan. Den här sökvägen är en möjlig väg. Det är inte den optimala sökvägen baserat på tid eller avstånd.
Den här vägvägspunktsordningen är: 0, 1, 2, 3, 4, 5 och 6.
Exempelfråga
Följande fråga begär sökvägen för samma sex waypoints, som i exemplet ovan. Den här gången är parametern inställd true på computeBestOrder (den resande försäljarens optimering).
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
Svaret beskriver sökvägens längd på 91 814 meter och att det skulle ta 7 797 sekunder att färdas den vägen. Ressträckan och restiden är båda lägre här eftersom API:et returnerade den optimerade vägen.
Följande bild illustrerar sökvägen som är resultatet av den här frågan.
Den optimala vägen har följande vägpunktsordning: 0, 5, 1, 2, 4, 3 och 6.
Dricks
Den optimerade orderinformationen för waypoint från routningstjänsten innehåller en uppsättning index. Dessa exkluderar ursprungsindexen och målindexen. Du måste öka dessa värden med 1 för att ta hänsyn till ursprunget. Lägg sedan till målet i slutet för att hämta den fullständiga ordnade waypoint-listan.
Beräkna och partiska alternativa vägar med hjälp av stödpunkter
Du kan ha situationer där du vill rekonstruera en väg för att beräkna noll eller fler alternativa vägar för en referensväg. Du kan till exempel visa kunder alternativa vägar som passerar din butik. I det här fallet måste du ändra en plats med hjälp av stödpunkter. Här följer stegen för att fördomsföra en plats:
- Beräkna en väg som den är och hämta sökvägen från vägsvaret
- Använd vägsökvägen för att hitta önskade platser längs eller nära vägsökvägen. Du kan till exempel använda begäran om punktsintresse eller köra frågor mot dina egna data i databasen.
- Sortera platserna baserat på avståndet från början av vägen
- Lägg till de här platserna som stödpunkter i en ny routningsbegäran till Post Route Directions(Post Route Directions). Mer information om stödpunkterna finns i dokumentationen för API:et Post Route Directions.
När du anropar Post Route Directions kan du ange minsta avvikelsetid eller avståndsbegränsningar, tillsammans med stödpunkterna. Använd dessa parametrar om du vill erbjuda alternativa vägar, men du vill också begränsa restiden. När dessa begränsningar används följer de alternativa vägarna referensvägen från ursprungspunkten för den angivna tiden eller avståndet. Med andra ord avviker de andra vägarna från referensvägen enligt de angivna begränsningarna.
Följande bild är ett exempel på återgivning av alternativa vägar med angivna avvikelsegränser för tid och avstånd.
Använda routningstjänsten i en webbapp
Azure Kartor Web SDK tillhandahåller en tjänstmodul. Den här modulen är ett hjälpbibliotek som gör det enkelt att använda Azure Kartor REST-API:er i webb- eller Node.js-program med hjälp av JavaScript eller TypeScript. Tjänstmodulen kan användas för att återge de returnerade vägarna på kartan. Modulen avgör automatiskt vilket API som ska användas med GET- och POST-begäranden.
Kommentar
Tillbakadragning av Azure Kartor Web SDK-tjänstmodul
Azure Kartor Web SDK-tjänstmodulen är nu inaktuell och dras tillbaka den 26-09-30. För att undvika avbrott i tjänsten rekommenderar vi att du migrerar till Azure Kartor JavaScript REST SDK senast 26-09-30. Mer information finns i Utvecklarguide för JavaScript/TypeScript REST SDK (förhandsversion).
Nästa steg
Mer information finns i: