Linjetrafik

Översikt över API:et för reguljära rutter

Planera och optimera rutter för fordonsflottor med hänsyn till tidsfönster, kapacitetsbegränsningar, trafikförhållanden och förarens raster. Skicka in ett problem och få en optimerad lösning.

API:et är utformat för att förbättra ruttplanering och schemaläggning för fordonsflottor, med hänsyn till viktiga begränsningar såsom tidsfönster för tjänster, kapacitetsbegränsningar och trafikförhållanden. Genom att utnyttja API:et kan företag avsevärt förbättra leveranseffektiviteten, sänka driftskostnaderna och spara värdefull tid tack vare optimerade lösningar för ruttplanering och schemaläggning.

I grund och botten löser API:et problemet med fordonsruttplanering (VRP) för upphämtning och leverans. Detta problem innebär att man beräknar de mest effektiva rutterna för en fordonsflotta som ska besöka flera platser för att utföra upphämtnings- och leveransuppdrag, samtidigt som man tar hänsyn till begränsningar som tidsfönster, fordonskapacitet och tillgänglighet.

Dessutom stöder API:et dynamiska schemaläggningsjusteringar eller omoptimering. Om du behöver ändra ett befintligt schema, oavsett om det beror på nya beställningar, avbokningar eller andra förändringar, kan du skapa en uppdaterad bild av ditt schema genom att ange uppdragens status och fordonens positioner. API:et omoptimerar då schemat för att återspegla dessa förändringar, vilket säkerställer en kontinuerlig effektivitet i din verksamhet.

För information om hur du snabbt kommer igång och börjar använda API:et, se Kom igång. I avsnittet Handledningar finns dessutom flera korta handledningar.

Utsläppshistorik
  • I version 1.1 har stöd för ruttmallar lagts till.
  • I version 1.2 har stöd för flexibel konfiguration av fordonets kapacitet lagts till.
Börja här

Snabbstart

Scheduled Routes är ett asynkront API: skicka in ett rutt- och schemaläggningsproblem, få ett referens-ID och kontrollera sedan det ID:t tills den optimerade lösningen är klar.

1. Logga in

Skicka förfrågningar med en API-åtkomsttoken i Authorization-rubriken.

2. Skicka in ett ärende

Användning POST /raas/optimization med en problem nyttolast.

3. Hämta lösningen

Användning GET /raas/optimization/{id} tills svaret returneras.

Säkerhet

Autentisering

Förfrågningarna använder en åtkomsttoken av typen ”bearer” i Authorization rubrik. Ersätt YOUR_ACCESS_TOKEN med din genererade API-åtkomsttoken.

HTTP-rubrik
Authorization: Bearer YOUR_ACCESS_TOKEN
Exempel som är lämpliga för publicering

Den ursprungliga källdokumentationen innehöll exempel på bärartoken och testinloggningsuppgifter. Denna WordPress-kompatibla fil behåller exemplen och steg-för-steg-beskrivningarna, men använder platshållare som YOUR_ACCESS_TOKEN, YOUR_EMAIL, och YOUR_PASSWORD så att inloggningsuppgifter inte publiceras av misstag.

API:ets livscykel #

API:et erbjuder två viktiga metoder för att hantera optimering av ruttplanering och schemaläggning:

  • POST-optimering — Skicka in ett optimeringsproblem gällande ruttplanering och schemaläggning. Efter att du har skickat in en POST-begäran får du ett unikt referens-ID.
  • Optimering GET — Hämta status för ett inlämnat problem med hjälp av det unika referens-ID som erhållits via POST-metoden. Om optimeringslösningen är klar kan du hämta lösningen på optimeringsproblemet.
Begrepp

Så här fungerar optimering #

Gör så här för att lösa ett optimeringsproblem gällande ruttplanering och schemaläggning för en fordonsflotta:

  1. Definiera problemet. Börja med att beskriva ditt problem enligt det format som anges i avsnittet ”Problem ”.
  2. Skicka in problemet. Använd POST-metoden, enligt beskrivningen i avsnittet Kom igång, för att skicka ditt problem till API:et.
  3. Hämta lösningen. Hämta lösningen på ditt optimeringsproblem med hjälp av GET-metoden. Lösningens format beskrivs i avsnittet Lösning.

För mer information om olika termer som används i API:et, se ordlistan. För en lista över vanliga frågor, se FAQ.

POST /raas/optimering #

INLÄGG https://iq.ui.scheduledroutes.ddswireless.net

Använd den här metoden för att skicka in ditt optimeringsproblem för rutt- och schemaläggning till API:et. När en POST-begäran om optimering har skickats in returnerar API:et ett unikt referens-ID i bekräftelsemeddelandet. Använd detta unika ID för att hämta den faktiska lösningen med hjälp av GET-metoden för optimering (se nästa avsnitt).

Exempel på en begäran (cURL)

Ett exempel på hur man skickar in ett optimeringsproblem med POST-metoden, med ett exempel på token och nyttolast. I det här exemplet finns det inmatade problemet i en fil som heter payload.json. Byt ut exempel-token YOUR_ACCESS_TOKEN med din egen token. Schemat för ingångsproblemet definieras i Problem avsnitt.

POSTbash · curl
curl -X POST "https://iq.scheduledroutes.ddswireless.net/raas/optimization" 
     -H "Content-Type: application/json" 
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
     -d @payload.json

Svarsschema

När du har skickat in POST-metoden får du ett svarsmeddelande med följande format:

json · svar
{
 "id": "string",
 "message": "string",
 "status": "string",
 "error" : "string"
}

Om inlämningen går igenom, kommer status kommer att bli 202, tillsammans med message med texten ”godkänd” och id som representerar det unika referensnumret för den asynkrona operationen. Detta ID används för att spåra operationens status och hämta resultaten senare.

Om ett fel uppstår, kommer status visar en felkod, den id kommer att vara noll eller tom, den message kommer att bli ett ”misslyckande”, och error beskriver felet. Mer information finns i POST-statuskoderna nedan.

Exempel på en begäran (Windows PowerShell)

Skriptet nedan visar hur man skapar en POST-förfrågan med hjälp av ett exempel på en datamängd i Windows PowerShell. Det förutsätter att datamängden finns lagrad i en fil med namnet payload.json, och API-åtkomsttoken sparas i token.txt. Vid körning skrivs det genererade ID:t till id.txt. För att starta PowerShell skriver du bara in ”PowerShell” i Start-menyn eller i kommandoraden.

POSTpowershell
$token = Get-Content token.txt -Raw
$headers = @{
    Authorization = "Bearer $token"
    "Content-Type" = "application/json"
}
$body = Get-Content payload.json -Raw
$response = Invoke-RestMethod -Uri "https://iq.scheduledroutes.ddswireless.net/raas/optimization" -Method Post -Headers $headers -Body $body
$response.id | Out-File -Encoding utf8 id.txt
Write-Output $response

POST-statuskoder

KodBeskrivningYtterligare anmärkningar
202Begäran har godkänts för behandling.Ett referens-ID returneras som du kan använda i en GET-förfrågan för att hämta lösningen när den är klar.
400Valideringen av inmatade uppgifter misslyckades (ogiltig begäran).Parameter saknas eller är ogiltig, eller så är värdetypen felaktig. Kontrollera indata och försök igen.
403Obehörig begäran.Detta inträffar när autentiseringen misslyckas.
404Den begärda sökvägen hittades inte.Detta inträffar när en felaktig sökväg används.
429För många förfrågningar.Begränsningen har överskridits (antal förfrågningar per minut eller kvoten har nåtts).
500Internt tjänstefel.Det är ett problem hos oss. Kontakta support@ddswireless.com.

GET /raas/optimering/{id} #

GET https://iq.ui.scheduledroutes.ddswireless.net/{id}

Använd den här metoden för att hämta den optimerade lösningen för de optimeringsuppgifter som skapats med hjälp av POST-metoden för optimering. För detta ändamål måste du ange det referens-ID som du fick från POST-metoden.

Exempel på en begäran (cURL)

Ett exempel på hur man hämtar ett svar från API:et med hjälp av GET-metoden och ett ID. Ersätt ID i URL:en med det ID du fick från POST-metoden, och kom ihåg att använda din egen API-åtkomsttoken.

HÄMTAbash · curl
curl -X GET "https://iq.scheduledroutes.ddswireless.net/raas/optimization/ID" 
     -H "Content-Type: application/json" 
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Till exempel, om ID är lika med 5, använd detta:

HÄMTAbash · curl
curl -X GET "https://iq.scheduledroutes.ddswireless.net/raas/optimization/5" 
     -H "Content-Type: application/json" 
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Svarsschema

json · svar
 {
  status: "string",
  message: "string",
  error: "string",
 "solution": {
      "statistics": {},
      "routes": []
      "unassigned": [],
      }  
}

Om lösningen är klar, statistics, routes, och unassigned kommer att fyllas i utifrån den erhållna lösningen. I övrigt gäller samma sak som för POST-metoden, status, message, och error visar status eller fel.

Schemat för utdatalösningen definieras i avsnittet Lösning.

Exempel på en begäran (Windows PowerShell)

Skriptet nedan visar hur man skapar en GET-förfrågan med hjälp av ett ID som genererats med POST-metoden. Det förutsätter att ID:t lagras i en fil med namnet id.txt, och API-åtkomsttoken sparas i token.txt. Vid körning skrivs det genererade svaret till response.txt.

HÄMTApowershell
$token = Get-Content token.txt -Raw
$id = Get-Content id.txt -Raw
$headers = @{
    Authorization = "Bearer $token"
    "Content-Type" = "application/json"
}

$url = "https://iq.scheduledroutes.ddswireless.net/raas/optimization/$id"

$response = Invoke-RestMethod -Uri $url -Method Get -Headers $headers
$response | ConvertTo-Json -Depth 10 | Out-File -Encoding utf8 response.txt

Hämta statuskoder

KodBeskrivningYtterligare anmärkningar
200Begäran har genomförts.Svaret returneras via statistics, routes, och unassigned.
202Begäran har godkänts men är ännu inte slutförd.Statusen är "Väntar". Kom tillbaka senare för att se om en lösning finns tillgänglig.
400Det gick inte att behandla begäran (ogiltig begäran).Det gick inte att generera en genomförbar lösning på grund av ogiltiga indata eller parametrar.
401Obehörig begäran.Användarautentisering krävs. Inga giltiga inloggningsuppgifter har mottagits.
500Internt tjänstefel.Det uppstod ett problem hos oss. Kontakta oss support@ddswireless.com. Fält som statistics, routes, och unassigned kommer att vara tom.
Exempel

Kodformat

Använd samma flöde för slutpunkten i det format du föredrar. I dessa exempel följs begäranformatet från API-referensen och platshållare som är säkra att publicera används.

Skicka in ett optimeringsproblem

cURL
curl -X POST "https://iq.scheduledroutes.ddswireless.net/raas/optimization" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d @payload.json
Python
import json
import requests

url = "https://iq.scheduledroutes.ddswireless.net/raas/optimization"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
}

with open("payload.json", "r", encoding="utf-8") as payload_file:
    payload = json.load(payload_file)

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
print(response.json())
PowerShell
$token = Get-Content token.txt -Raw
$headers = @{
    Authorization = "Bearer $token"
    "Content-Type" = "application/json"
}
$body = Get-Content payload.json -Raw
$response = Invoke-RestMethod -Uri "https://iq.scheduledroutes.ddswireless.net/raas/optimization" -Method Post -Headers $headers -Body $body
$response.id | Out-File -Encoding utf8 id.txt
Write-Output $response

Hämta ett optimeringsresultat

cURL
curl -X GET "https://iq.scheduledroutes.ddswireless.net/raas/optimization/ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Python
import requests

optimization_id = "ID"
url = f"https://iq.scheduledroutes.ddswireless.net/raas/optimization/{optimization_id}"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
}

response = requests.get(url, headers=headers, timeout=60)
response.raise_for_status()
print(response.json())
Referens

Objekt

Begäran fokuserar på problem. Responsobjektet är centrerat på solution. De ursprungliga fältreferenserna, exemplen, diagrammen, anmärkningarna och reglerna återges nedan.

Begär objekt

Problem, fordonspark/fordon/skift/rast, uppdrag/uppgift/upphämtning/leverans, mål och konfiguration.

Svarobjekt

Lösning, Rutt/Hållplats, Statistik och Ej tilldelad.

Stödmaterial

Handledningar, ordlista och vanliga frågor.

Problemobjektet #

Den Problem Enheten utgör ett problem inom ruttplanering och schemaläggning. Som framgår av figuren nedan består den av fyra huvudkomponenter: fleet, jobs, objective, och configuration. Bland dessa, fleet och jobs är obligatoriska, medan objective och configuration är valfria.

Diagram över objektets struktur
Ange platser

För att ange en plats eller adress i API:et ska du använda WGS84-geokoordinater med minst fem decimaler för att säkerställa noggrannheten. Till exempel adressen "1600 Amphitheatre Parkway, Mountain View, Kalifornien" har koordinaten latitud 37.423021 och longitud -122.083739. Du kan ange det som "location": {"lat": 37.423021, "lng": -122.083739} eller som [37.423021, -122.083739].

Tidsstämplar och tidszoner

API:et använder ISO 8601-formatet för tidsstämplar, inklusive uppgifter om tidszon, för att ange lokal tid för det område där du behöver optimerad ruttplanering och schemaläggning. Till exempel, 2024-07-31T14:45:30-08:00 avser den 31 juli 2024 kl. 14:45:30 PST, vilket är 8 timmar efter universell koordinatid (UTC).

I indata måste du konsekvent använda samma lokala tidszon. Om flera tidszoner upptäcks kommer API:et att returnera ett fel. Tiderna för schemalagda stopp i utdatasvaret kommer att anges i samma format som det som specificerats i indata. Om du till exempel anger 2024-07-31T14:45:30-08:00 i din inmatning kommer de optimerade restiderna i utdata också att använda -08:00; om du använder +05:30 i indata kommer utdata att använda +05:30.

Valfria attribut

Alla valfria attribut kan utelämnas i datan. Tomma arrayer (t.ex. []) kan även användas för valfria attribut som accepterar en array.

Skicka inte konfidentiella uppgifter

Se till att inga konfidentiella eller personuppgifter ingår i de data som skickas till API:et. Undvik till exempel att använda verkliga identifierare, såsom registreringsnummer, som fordonets ID eller som ID för jobb/uppdrag.

Komponentöversikt

flottaObligatoriskt

Anger en lista över fordon tillsammans med tillhörande information, såsom arbetsscheman, start- och slutplatser, raster, kapacitet och kompetens. För varje fordon kan du ange ett eller flera arbetsscheman (start- och sluttider samt platser), en eller flera raster (tidsfönster, plats och varaktighet), en eller flera kapacitetstyper med tillgängliga enheter (flerdimensionella enheter som volym, massa eller storlek) samt en eller flera kompetenser som gör att fordonet kan utföra vissa uppdrag. Du kan till exempel tilldela ”svetsmaskin” och ”syretank” som kompetenser för ett fordon och ”lyft” som kompetens för ett annat; om ett jobb kräver en lyft kommer endast det fordon som är utrustat med denna kompetens att utföra det. Du kan också ställa in gränser såsom maximalt antal stopp och maximal körsträcka (i mil).

jobbKrav

Anger en lista över uppdrag som fordonen ska utföra i fleet. Varje uppdrag kan bestå av en rad olika uppgifter, som kan vara enbart upphämtningar, enbart leveranser eller både upphämtningar och leveranser. När det gäller ”besöksuppdrag” där du måste besöka en plats för att utföra arbete (t.ex. reparationer eller installation av ett modem) ska du behandla dem som en leveransuppgift, med eller utan kapacitetskrav. För varje uppgift kan du definiera attribut såsom plats, tidsfönster, varaktighet, kapacitetskrav och nödvändiga färdigheter. Om optimeringsverktyget inte kan hitta en lämplig beräknad ankomsttid för en uppgift inom det angivna tidsfönstret förblir uppgiften otilldelad. För flexibla eller icke-tidsberoende uppgifter ska du ange ett bredare tidsfönster (maximalt 24 timmar).

syfteValfritt

Fastställer optimeringsmålet eller strategin. För närvarande stöds tre mål:

  • Minimera total restid — standardstrategin; minimerar flottans totala restid samtidigt som de angivna uppdragen utförs.
  • Minimera antalet rutter — minskar antalet fordon som behövs för att utföra uppdragen. Detta kan dock leda till en längre total körtid eller en större arbetsbelastning på de enskilda fordonen som en nackdel.
  • Fördela arbetsbelastningen mellan rutterna — fördelar arbetsbelastningen jämnt mellan alla fordon i fordonsparken. Denna fördelning kan leda till en längre total körtid.
konfigurationValfritt

Justerar API-inställningarna eller ändrar standardalternativen. Du kan till exempel ange om en sammanfattning av optimeringsstatistik (t.ex. total restid och sträcka) eller en lista över icke tilldelade uppgifter ska inkluderas i API-svaret.

Schema för inmatningsförfrågan #

Schemat för den inmatningsförfrågan som används för att lösa ett ruttoptimeringsproblem ser ut enligt följande. För att skicka in ett problem måste denna förfrågan inkluderas i POST-metoden enligt beskrivningen i avsnitt et Kom igång.

json · begärandestruktur
 "problem": {
      "fleet": required 
        [
          "shifts": [optional]
          "capacities": [required]
          "limits": {optional}
          "skills" : [optional]
          "id": required
          "routeTemplateId" : optional
          "maxInstances": optional   
        ],
      "jobs": required
        [
          "pickups": [...] 
          "deliveries": [...]
          "id" : required
        ]
      "objective": optional
      "configuration": {optional}
      "version": optional
    }

I ett ruttoptimeringsproblem är målet att en fordonsflotta ska utföra en uppsättning uppdrag på ett effektivt sätt. Med hjälp av schemat ovan kan du definiera din fordonsflotta och dina uppdrag. I den aktuella versionen av API:et kan varje uppdrag vara:

  1. Endast upphämtningsuppdrag — innebär att man hämtar varor längs rutten och levererar dem till rutten slutdestination.
  2. Endast leveransuppdrag — kräver leverans av varor som lastas på fordonet i början av rutten.
  3. Hämtning och leverans (P/D) i ett – kombinerar båda åtgärderna, det vill säga att hämta något på en plats och leverera det till en annan.
Krav för tjänsten

Minst ett uppdrag och ett fordon måste tilldelas för ärendet. Uppdrag av typen ”besök” som kräver att man tar sig till en plats (t.ex. reparationer, modeminstallationer) ska betraktas som leveransuppdrag, med eller utan kapacitetskrav.

Dessutom:

  1. Om bara pickups Om ett objekt tillhandahålls för ett uppdrag betraktas det som ett uppdrag som endast gäller avhämtning.
  2. Om bara deliveries Om ett objekt tillhandahålls för ett uppdrag betraktas det som ett renodlat leveransuppdrag.
  3. När båda pickups och deliveries om dessa tjänster tillhandahålls klassificeras det som ett hämtnings- och leveransuppdrag.
Regler för upphämtning och leverans

API:et stöder inte uppdrag med flera upphämtningar och flera leveranser. Med andra ord, när det gäller ett uppdrag av typen ”upphämtning och leverans”:

  • Den pickups matrisen får endast innehålla en hämtningsuppdrag.
  • Den deliveries matrisen får endast innehålla en leveransuppdrag.

API:et stöder inte heller uppdrag utan upphämtningar och utan leveranser. Klassificeringsregler:

  • Om bara pickups är definierad klassificeras jobbet som en förankrad i pickupen jobb.
  • Om bara deliveries är definierad klassificeras jobbet som en leveransbaserad jobb.
  • Om både upphämtning och leverans har angetts är det den som har ett tidsfönster som gäller.
  • Om både upphämtning och leverans har tidsfönster betraktas uppdraget som upphämtningsbaserat.

För varje uppdrag kan olika attribut och begränsningar definieras, till exempel kapacitetskrav, tidsfönster för utförandet och nödvändiga kompetenser. Besöksuppgifter, där du måste besöka specifika platser för att utföra uppgifter (t.ex. reparationer), kan ses som en specialiserad form av leveransuppgift (med eller utan kapacitetskrav). Uppgifter tilldelas fordon vars kapacitet eller kompetens stämmer överens med uppgiftens krav. Om en uppgift till exempel kräver en lyft eller stege kommer endast fordon utrustade med en lyft eller stege att användas för att utföra den uppgiften.

problem — fältreferens

problem Obligatoriskt Anger det optimeringsproblem för ruttplanering och schemaläggning som du vill lösa. Det består av följande attribut.

fleet

flotta ( obligatoriskt ) Anger information om flottan. Det är en matris med flottorobjekt. Varje flottorobjekt består av följande attribut:

idheltalObligatoriskt

Ett unikt identifieringsnummer för fordonet.

skiftarrayValfritt

En matris med skift-objekt. Varje skift-objekt innehåller uppgifter om start- och slutplats samt start- och sluttid för skiftet, liksom en matris med rast-objekt som vart och ett innehåller start- och slutplats samt start- och sluttid för rasten. Flera skift-objekt kan definieras, men de får inte överlappa varandra. Element i varje skift-objekt:

börja

Arbetstidens starttid och startplats.

  • time — valfritt. Anger starttiden för skiftet. Om ingen tid anges används standardvärdet 00:00:00 (midnatt) samma dag.
  • location — valfritt. Startplatsens geografiska koordinater (latitud och longitud). Ange som en matris [A,B] (A = latitud, B = longitud) eller som {"lat": A,"lng": B}.
slut

Arbetstidens slut och platsen där skiftet avslutas.

  • time — valfritt. Anger tidpunkten för skiftets slut. Om ingen tid anges används standardvärdet 23:59:00 samma dag.
  • location — valfritt. Geokoordinaterna för slutplatsen. Ange som [A,B] eller {"lat": A,"lng": B}.
avbrott array Valfritt
  • serviceWindow — krävs om breaks används. Den tidsperiod under vilken avbrottet kan inträffa.
  • duration — krävs om breaks används. Ett heltal som anger pausens längd i sekunder.
  • location — valfritt. Brottsstället, som [A,B] eller {"lat": A,"lng": B}. Om platsen inte anges är rasten ”flexibel”, vilket innebär att den kan tas var som helst när det passar föraren.

Exempel — shifts

json
"shifts": [{
  "start": {
    "time": "2020-07-04T09:00:00-08:00",
    "location": {"lat": 52.46642, "lng": 13.28124}
  },
  "end": {
    "time": "2020-07-04T18:00:00-08:00",
    "location": [54.21981, 14.01237]
  },
  "breaks": [
    {
      "serviceWindow": ["2020-07-04T12:00:05-08:00","2020-07-04T14:05:05-08:00"],
      "duration": 1200,
      "location": {"lat": 53.70645, "lng": 12.34156}
    },
    {
      "serviceWindow": ["2020-07-04T16:00:00-08:00","2020-07-04T16:45:00-08:00"],
      "duration": 600,
      "location": {"lat": 51.46642, "lng": 12.28124}
    }
    ]
  }]
kapacitetermatrisObligatoriskt

En matris med kapacitetsobjekt. Varje kapacitetsobjekt är ett nyckel-värde-objekt som definieras med följande nycklar:

  • name — krävs. En sträng som anger namnet på kapacitetstypen (t.ex. ”rullstol”, ”låda”, ”säte”, ”soptunna”).
  • units — krävs. Ett heltal som anger antalet tillgängliga enheter av den aktuella kapacitetstypen.

Om ett fordon till exempel har plats för 2 passagerare och 20 paket kan du ange dess kapacitet på följande sätt:

json
    "capacities": [
        {
        "name": "seat",
        "units": 2,
        },
        {
        "name": "package",
        "units": 20,
        }        
      ]
färdighetersträngmatrisValfritt

En lista över fordonets funktioner eller utrustning, där varje post representeras av en godtycklig sträng som är specifik för din applikation. Detta gör att du kan anpassa fordonets funktioner så att de passar de krav som ställs i de uppdrag de ska utföra. Exempel: "skills": ["lift","fridge","oxygen tank"]

gränserobjektValfritt

Anger vilka begränsningar som gäller för fordonet.

  • maxDistance — valfritt. Ett heltal som anger fordonets maximala avståndsbegränsning i mil.
  • maxStops — valfritt. Ett heltal som anger det maximala antalet stopp (upphämtnings- eller leveransuppdrag) som fordonet kan utföra under ett arbetspass.
  • lifoDepth — valfritt. Ett heltal som anger fordonets LIFO-djup (Last In First Out).
json
  "limits": {
    "lifoDepth" : 1,
    "maxDistance": 3000,
    "maxStops" : 20,
  }
senastKändaPlatsobjektEndast omoptimering

Anger fordonets senast kända position vid den angivna tidpunkten. Denna information är avgörande för att kunna omoptimera en pågående rutt med hänsyn till nya förändringar, såsom fordon som gått sönder, försenade uppdrag, nya uppdrag eller inställda uppdrag. När du omoptimerar ett befintligt schema måste du ange positionen för alla berörda fordon.

json
"lastKnownLocation": {
      "location": {"lat":53.45612, "lng":12.65421},
      "time" : "2020-07-04T12:00:05-08:00"
      }
routeTemplateIdheltalValfritt

En unik identifierare som används för att definiera en ruttmall. API:et stöder begreppet ”ruttmallar”, vilket gör det möjligt att definiera specifikationer för en viss fordonstyp och be API:et att generera ett visst antal sådana fordon för optimering. En ruttmall innehåller samma information som en rutt eller ett fordon, men du kan ange en ”storleksparameter” som kallas maxInstances för detta. Anta till exempel att du har 100 fordon. Du kan definiera 2 eller 3 ruttmallar:

  1. Skift kl. 06.00–18.00, kapacitet 4, storlek = 60
  2. Skift kl. 13.00–01.00, kapacitet 4, storlek = 50
  3. Skift kl. 06.00–20.00, kapacitet 10, storlek = 35

Det innebär att API:et automatiskt kan skapa upp till 60 fordon med mall 1 efter behov, 5 med mall 2 och 35 med mall 3.

maxInstancesheltalValfritt

Om routeTemplateId tillhandahålls, maxInstances anger hur många ruttmallar som ska genereras utifrån den angivna ruttmallen.

Regler för id, routeTemplateId och maxInstances
  • Exakt ett av id eller routeTemplateId måste användas, aldrig båda.
  • id och maxInstances kan inte användas tillsammans.
  • Om båda routeTemplateId och maxInstances om dessa finns tillgängliga, använder API:et ruttmall för att skapa rutter.

jobs

jobb Minst ett krävs En matris med jobbojekt. Varje jobbojekt har följande attribut:

idheltalObligatoriskt

En unik identifierare för uppdraget.

pickupermatris av uppgiftsobjektValfritt

En matris med uppgiftsobjekt, där varje objekt definierar en hämtningsuppgift.

leveransermatris av uppgiftsobjektValfritt

En matris med uppgiftsobjekt, där varje objekt definierar en leverans- (eller avlämnings-) uppgift.

Inställningar för hämtning och leverans
  • API:et stöder inte uppdrag med flera upphämtningar och flera leveranser.
  • API:et stöder inte uppdrag utan upphämtningar och utan leveranser.
  • Om bara pickups om detta anges klassificeras jobbet som ett uppdragsbaserat arbete.
  • Om bara deliveries om detta anges klassificeras jobbet som ett leveransbaserat arbete.
  • Om ett uppdrag omfattar både upphämtning och leverans bestäms utgångspunkten av den uppgift som anger ett tidsfönster.
  • Om båda uppgifterna har tidsfönster behandlas jobbet som ett hämtningsbaserat jobb.

Uppgiftsobjektet

Varje uppgiftsobjekt består av följande attribut:

idheltalObligatoriskt

En unik identifierare för uppgiften.

platsobjekt eller arrayObligatoriskt

Ett nyckel-värde-objekt som anger geografiska koordinater (latitud och longitud) för den plats där uppgiften ska utföras. Ange som en matris [A,B] (A = latitud, B = longitud) eller som {"lat": A,"lng": B}.

json
"location": {"lat": 52.46642, "lng": 13.28124}
"location": [52.46642, 13.28124]
serviceWindowsarrayValfritt / Obligatoriskt

Anger tidsfönstret för utförandet av uppgiften (obligatoriskt eller valfritt beroende på användningsfall; se avhämtningar och leveranser ovan). Tidsfönstret är en matris av formen [A, B] där A och B är start- och sluttiderna. API:et försöker beräkna en beräknad ankomsttid (ETA) inom det angivna tidsfönstret; om detta inte är möjligt markeras uppgiften som icke tilldelad. Tiderna A och B anger den tidigaste och senaste tidpunkt då en uppgift måste vara slutförd av ett fordon. För flexibla eller icke-tidsbegränsade uppdrag, använd ett godtyckligt stort tidsfönster (max 24 timmar) för att ge API:et större flexibilitet vid schemaläggning av andra uppdrag. Den nuvarande versionen av API:et stöder endast ett servicetidsfönster per uppdrag. För uppdrag som endast avser upphämtning eller leverans krävs ett servicetidsfönster.

json
"serviceWindows": ["2024-08-30T09:00:00-08:00",
                   "2024-08-30T21:00:00-08:00"]
varaktighetheltal eller objektObligatoriskt

Anger uppgiftens varaktighet i sekunder. Det kan vara antingen ett heltal eller ett nyckel-värde-objekt med följande nycklar:

  • fixed — den fasta varaktigheten (i sekunder) för uppgiften (t.ex. för att hitta en parkeringsplats eller för att sänka hissen).
  • service — hur lång tid (i sekunder) det tar att utföra uppgiften.
json
"duration": 1950
   OR
"duration": {"fixed":150, "service": 1800}
efterfråganmatrisValfritt

En rad kapacitetskrav för uppgiften. Strukturen för varje kravobjekt är identisk med den för kapacitetsobjektet i flottentiteten. Varje kapacitetspost består av en name (sträng) och dess units (heltal). De angivna namnen måste stämma överens med de som definierats i kapacitetsobjektet för flottan. Om ett uppdrag till exempel kräver kapacitet för två platser och 20 paket:

json
"demand": [
    {
    "name": "seat",
    "units": 2,
    },
    {
    "name": "package",
    "units": 20,
    }        
  ]
färdighetersträngmatrisValfritt

En uppsättning färdigheter eller utrustning som krävs för att utföra uppgiften, där varje färdighet representeras av en godtycklig sträng som är specifik för din applikation. Endast fordon vars färdighetsuppsättning stämmer överens med uppgiftens färdighetsuppsättning kommer att beaktas för att utföra uppgiften. Dessa färdigheter matchas mot de färdigheter som definierats i flottentiteten. Exempel: "skills": ["lift", "ladder", "welding machine"]

statussträngEndast omoptimering

En sträng som anger uppgiftens status: pending, in_progress, eller performed. Detta är avgörande för att kunna optimera en pågående rutt på nytt. För nya uppdrag eller uppdrag som ännu inte har utförts ska du ställa in det på pending. Om uppgiften redan är utförd, ställ in den på performed. Om fordonet redan har anlänt till platsen och uppdraget pågår, ställ in det på in_progress. Standardvärdet är pending. Exempel: "status": "pending"

fordons-idheltalEndast omoptimering

Anger det tilldelade fordons-ID:t för redan schemalagda uppdrag. Detta är avgörande för att kunna omoptimera en pågående rutt. Standardvärdet är noll. För nya uppdrag ska värdet sättas till noll. För befintliga uppdrag som redan tilldelats ett fordon ska detta attribut sättas till det tilldelade fordons-ID:t. Exempel: "vehicleId": 12

etatidsstämpelEndast omoptimering

Anger aktuell beräknad ankomsttid (ETA) för redan schemalagda uppdrag. Detta är avgörande för att kunna omoptimera en pågående rutt. Standardvärdet är 0. För nya eller utförda uppdrag ska värdet sättas till 0; för befintliga väntande uppdrag ska det sättas till den befintliga beräknade ankomsttiden. Exempel: "eta": "2021-07-04T12:13:00-08:00"

objective

syfte heltal Valfritt   Anger optimeringsmålet (strategin). Standardvärdet är 1.

VärdeStrategi
1Minimera total restid (standard)
2Minimera antalet rutter
3Fördela arbetsbelastningen mellan rutterna

Exempel: "objective": 1

configuration

konfiguration ( valfritt ) Används för att ange ytterligare inställningar eller konfigurationer.

polylinetypsträngValfritt

Anger vilken typ av utgående polylinje som returneras för varje planerad rutt. En av följande none, plain, encoded. Om none, ingår inga polylinjer. Om plainreturneras en ordnad lista över korsningar som man ska passera mellan varje par på varandra följande hållplatser. Om encodedkomprimeras polylinjen till ett strängformat som du kan använda i navigations-API:er från tredje part, till exempel Google Maps, för steg-för-steg-vägbeskrivningar. Standardvärdet är none.

outförda uppgifterbooleanValfritt

En flagga som anger om icke tilldelade uppgifter ska inkluderas i svaret. Standardvärdet är False. Om API:et av någon anledning inte kan tilldela en uppgift till en rutt kommer den att visas som otilldelad.

statistikbooleanValfritt

En flagga som anger om optimeringsstatistiken ska inkluderas i den slutliga lösningen. Standardvärdet är True.

enhetersträngValfritt

Anger enheterna för utdatastatistiken och flottans gränsvärden. Antingen metric eller imperial. Standardvärdet är metric.

maxRideTablearrayValfritt

Anger den maximala körtiden för alla uppdrag. Den definieras av en statisk tabell där varje rad är en matris som innehåller tre tidsvärden (i minuter): [A, B, C]. Det innebär att om den direkta restiden för ett uppdrag är mellan A och B, så är den maximala tiden ombord lika med ”rideTime + C”. Till exempel en enkel tabell med två rader: "maxRideTable":[[0, 10, 30], [11, 20, 40]]. Standardinställningen är [[0, 300, 720]]. Överlappningar och luckor är inte tillåtna i denna tabell, och uppdateringsfrekvensen är per minut.

enforceLockedTasksbooleanValfritt

Styr hur optimeringsmotorn hanterar tidigare tilldelade uppdrag vid omoptimering. Standardinställningen är false.

När inställningen är true, behandlas alla uppdrag som redan tilldelats ett fordon i omoptimeringsuppsättningen som låsta och måste förbli på sitt nuvarande fordon. Motorn kommer endast att optimera och tilldela nya uppdrag som ännu inte har tilldelats ett fordon.

När inställningen är false... får motorn ändra befintliga tilldelningar under omoptimeringen. Tidigare tilldelade uppdrag kan tas bort från sitt ursprungliga fordon om tilldelningen inte längre är giltig eller optimal. Ett uppdrag som till exempel ursprungligen var schemalagt till kl. 08.00 kan tas bort under en omoptimering kl. 10.00, eftersom uppgiften inte längre kan slutföras inom de givna ramarna.

fordonskapacitetobjektValfritt

Definitioner av fordonets kapacitet kan namnges och sedan användas i avsnittet om fordonsparken. Detta är särskilt användbart vid komplexa definitioner när ett fordon kan ha många olika konfigurationer. Om ett fordon till exempel rymmer antingen (10 ”gående” och 0 ”rullstolsburna” passagerare) ELLER (8 ”gående” och 1 ”rullstolsburen” passagerare) kan du definiera "vehicleCapacities":{"flexBus": [[{"name": "ambulatory", "units": 10}], [{"name": "ambulatory", "units": 8},{"name":"wheelchair", "units": 1}]]}. I flottans egenskaper kan du sedan använda fleet[<index>].capacities: "flexBus" för varje flexBus i fordonsflottan. Namngivna fordonskapaciteter kan också sparas i din personliga kundprofil, där de blir tillgängliga för användning utan att du behöver ange dem i konfigurationsavsnittet. Om en namngiven fordonskapacitet finns både i din personliga profil och i lastkapaciteten, har definitionen i lastkapaciteten företräde.

freezeWindowLengthheltal (minuter)Valfritt

Längden på frysfönstret i minuter. Ett frysfönster är ett begrepp som endast gäller optimering inom samma dag och är användbart vid omoptimering av ett problem. Om du till exempel redan har optimerat ett problem men vill göra ändringar mitt under dagen kan du skicka in problemet på nytt (med lämpliga task.status (för att återspegla vad som redan har gjorts) och ställa in ett fryst fönster på 60 minuter. Detta anger för optimeraren att tidsperioden som sträcker sig 60 minuter från ”nu” är undantagen: inga uppgifter får läggas till eller tas bort från någon rutt inom det frysta fönstret.

lifoBegränsadeKapaciteterarrayValfritt

En rad olika lagertyper som omfattas av LIFO-principen (Last In, First Out). Exempel: "lifoConstrainedCapacities": ['wheelchair', 'scooter']

Exempel — configuration

json
"configuration": 
{
      "polylineType": "plain",
      "unassignedTasks": False,
      "statistics": True,
}

version

version Valfritt   Anger vilken version av API:et som används. Standardvärdet är 1.0.

Fler exempel

För att se olika exempel på en Problem och lär dig hur du använder API:et i olika användningsfall (t.ex. omoptimering), se Handledningar.

Identifierare och tidsbegränsningar

1. Unika identifierare. Alla uppdrag måste ha unika ID-nummer. Alla arbetsuppgifter måste ha unika ID-nummer. Alla fordon måste ha unika ID-nummer. Ett uppdrag kan dela sitt ID-nummer med en arbetsuppgift eller ett fordon – detta är tillåtet.

2. Tidsbrist. Varje problem kan innehålla flera tidsrelaterade faktorer, till exempel tidsfönster för uppgifter och fordonsskift. API:et beräknar den kortaste tiden utifrån alla värden. Om den kortaste tiden till exempel är 2024-09-18T04:32:00-08:00beräknas maxvärdet genom att man tar midnatt den dag då minvärdet inträffar och lägger till 33 timmar till den tidpunkten. I det här exemplet är alltså den högsta tillåtna tiden 2024-09-19T09:00:00-08:00. Om någon tid i uppgiften (t.ex. fordonets skift eller arbetsfönster) överskrider detta, kommer API:et att returnera ett 400 fel.

Lösningen

Objektet Solution #

När du har skickat in ett problem med POST-metoden får du ett unikt referens-ID. Använd detta referens-ID med GET-metoden för att hämta status för det inskickade problemet. Om optimeringslösningen är klar kan du komma åt den i solution svarets enhet. Som framgår av figuren nedan, solution Enheten består av tre huvuddelar:

statistik

Innehåller olika mätvärden som ger en översikt över hela lösningen för alla rutter, vilket gör att du kan utvärdera dess effektivitet (till exempel den totala sträckan för alla optimerade rutter). Genom att analysera dessa statistiska uppgifter kan du mäta kvaliteten och effektiviteten hos den framtagna lösningen.

rutter

Innehåller de optimerade rutterna tillsammans med deras hållplatser och beräknade ankomsttider (ETA). Den kan även innehålla en linje som visar varje rutt.

ej tilldelad

Innehåller en lista över icke tilldelade uppgifter. Om API:et inte kan tilldela en uppgift till en rutt under optimeringen listas den som icke tilldelad. Listan kan innehålla orsaker till varför varje uppgift förblir icke tilldelad, vilket ger en inblick i de begränsningar eller problem som hindrade tilldelningen.

Diagram över Solution-objektets struktur

Schema för utdatalösning #

Mallen för det svar som API:et returnerar ser ut enligt följande:

json · lösning
 "solution": {
      "statistics": {},
      "routes": []
      "unassigned": [],
      }

Den solution Enheten representerar lösningen på problemet med ruttoptimering och består av de attribut som beskrivs nedan.

statistics

Innehåller statistik för hela lösningen. Den består av följande egenskaper:

avstånd
  • totalDistance — den totala sträckan som hela fordonsflottan har tillryggalagt, inklusive sträckan från varje fordons startpunkt till dess slutpunkt.
  • revenueDistance — den totala sträckan som hela fordonsflottan har tillryggalagt, inklusive sträckan från första hållplatsen till sista hållplatsen för varje fordon. Detta omfattar inte sträckan från fordonets startplats till första hållplatsen eller från sista hållplatsen till fordonets slutdestination.
fordon
  • used — antalet begagnade fordon som ingår i lösningen för att utföra de schemalagda uppdragen/uppgifterna.
  • unused — antalet outnyttjade fordon.
jobb
  • scheduledTasks — antalet schemalagda uppgifter.
  • unassignedTasks — antalet icke tilldelade uppgifter.
gånger
  • totalHours — det totala antalet körtimmar för hela fordonsflottan, inklusive den tid som går åt för att köra från varje fordons startplats till dess slutdestination.
  • revenueHours — det totala antalet intäktsgenererande körtimmar för hela fordonsflottan, inklusive den tid det tar från första till sista hållplatsen för varje fordon. Detta omfattar inte tiden för resan från fordonets startplats till den första hållplatsen eller från den sista hållplatsen till fordonets slutdestination.

Exempel — statistics

json
"statistics": {
    "distance": {
        "totalDistance": 42,
        "revenueDistance": 25
    },
    "vehicles": {
        "used": 2,
        "unused": 0
    },
    "jobs": {
        "scheduledTasks": 3,
        "unassignedTasks": 0
    },
    "times": {
        "totalHours": 11.6,
        "revenueHours": 10.8
    }
}

routes

Visar en översikt över den planerade rutten för varje fordon. Varje planerad rutt innehåller:

fordons-idheltal

ID-numret för det tilldelade fordonet.

skiftmatris

En matris med skift-objekt. API:et stöder flera skift för varje fordon. Varje skift-objekt består av:

  • index — skiftets index (heltal).
  • stops — en lista över alla hållplatser som fordonet ska stanna vid under detta skift.

Varje hållplats har följande egenskaper:

  • ordinal — hållplatsens placering i fordonets tidtabell, angiven med dess index (heltal).
  • jobId — det jobb-ID som hör till detta stopp (heltal).
  • taskId — uppgifts-ID för detta stopp (heltal).
  • type — vilken typ av uppdrag som utförs vid detta stopp (”upphämtning” eller ”leverans”).
  • location — Geokoordinaterna för hållplatsens läge.
  • eta — beräknad ankomsttid för hållplatsen (i samma tidszon som den inmatade datan).
  • timeToNext — körtiden till nästa stopp. Om du till exempel släpper av en passagerare kl. 09.00 och ditt nästa uppdrag är kl. 10.00, visar detta att körtiden från det aktuella stoppet till nästa stopp är 20 minuter.
  • distanceToNext — körsträckan till nästa hållplats. Beroende på vilka enheter som valts i inställningarna kan detta anges i mil eller meter.
  • waitTime — hur länge föraren bör vänta vid nästa hållplats om hen börjar köra nu.
  • polyline — den polylinje som förbinder hållplatsen med den föregående hållplatsen. Om ”plain” anges i konfigurationen består polylinjen av en ordnad lista över korsningar som ska passeras mellan den föregående hållplatsen och den aktuella hållplatsen. Om ”encoded” anges kodas den vanliga polylinjen och returneras som en kodad sträng.
  • break — om det schemalagda stoppet avser en paus, anger det pausens ID. Övriga stopp har inte detta element. API:et kräver inte att pauser (eller uppdrag) listas i kronologisk ordning.

Exempel — routes

json
       "routes": [
            {
                "vehicleId": 1,
                "shifts": [
                    {
                        "index": 1,
                        "stops": [
                            {
                                "break": 1,
                                "start": "2023-10-01T10:00:00-08:00",
                                "end": "2023-10-01T10:15:00-08:00",
                                "timeToNext": 15,
                                "distanceToNext": 7.3,
                                "waitTime": 0,
                                "polyline": null,
                                "ordinal": 1
                            },
                            {
                                "jobId": 4,
                                "taskId": 5,
                                "type": "pickup",
                                "location": [
                                    50.70816,
                                    -120.37796
                                ],
                                "eta": "2023-10-01T10:30:00-08:00",
                                "timeToNext": 13,
                                "distanceToNext": 5.6,
                                "waitTime": 112,
                                "polyline": null,
                                "ordinal": 2
                            },
                            {
                                "jobId": 4,
                                "taskId": 6,
                                "type": "delivery",
                                "location": [
                                    50.66559,
                                    -120.36924
                                ],
                                "eta": "2023-10-01T12:45:00-08:00",
                                "timeToNext": 4,
                                "distanceToNext": 1.7,
                                "waitTime": 71,
                                "polyline": null,
                                "ordinal": 3
                            },
                            {
                                "break": 2,
                                "start": "2023-10-01T14:00:00-08:00",
                                "end": "2023-10-01T14:15:00-08:00",
                                "timeToNext": 7,
                                "distanceToNext": 3.2,
                                "waitTime": 217,
                                "polyline": null,
                                "ordinal": 4
                            }
                        ]
                    }
                ]
            },
            {
                "vehicleId": 2,
                "shifts": [
                    {
                        "index": 1,
                        "stops": [
                            {
                                "break": 1,
                                "start": "2023-10-01T11:00:00-08:00",
                                "end": "2023-10-01T11:15:00-08:00",
                                "timeToNext": 3,
                                "distanceToNext": 1.2,
                                "waitTime": 267,
                                "polyline": null,
                                "ordinal": 1
                            },
                            {
                                "jobId": 10,
                                "taskId": 11,
                                "type": "pickup",
                                "location": [
                                    50.65187,
                                    -120.40052
                                ],
                                "eta": "2023-10-01T15:45:00-08:00",
                                "timeToNext": 12,
                                "distanceToNext": 6.4,
                                "waitTime": 0,
                                "polyline": null,
                                "ordinal": 2
                            },
                            {
                                "jobId": 10,
                                "taskId": 12,
                                "type": "delivery",
                                "location": [
                                    50.69262,
                                    -120.35412
                                ],
                                "eta": "2023-10-01T16:22:00-08:00",
                                "timeToNext": 6,
                                "distanceToNext": 2.7,
                                "waitTime": 91,
                                "polyline": null,
                                "ordinal": 3
                            }
                        ]
                    }
                ]
            }
        ]

unassigned

Listan över icke tilldelade uppgifter (valfritt) innehåller uppgifter som inte kan tilldelas på grund av särskilda begränsningar. Varje post består av ett jobb-ID, ett uppgifts-ID och eventuella skäl till att uppgiften inte tilldelats (en kod samt en beskrivning):

id
  • job — jobb-ID (heltal) för den icke tilldelade uppgiften.
  • task — ID-numret (heltal) för den icke tilldelade uppgiften.
anledning

En rad möjliga orsaker till de ouppfyllda uppgifterna.

  • code — koden (heltal) för den möjliga orsaken.
  • description — beskrivningen (sträng) av den möjliga orsaken.
json
{
  "unassigned": [
    {
      "id": {
        "job": 2,
        "task": 1
      },
      "reason": [
        {
          "code": 2,
          "description": "Not enough capacity for this job"
        }
      ]
    },
    {
      "id": {
        "job": "31",
        "task": "2"
      },
      "reason": [
        {
          "code": 5,
          "description": "The service time of the job is out of the shift hours"
        }
      ]
    }
  ]
}

Fel och statuskoder #

Som beskrivs i avsnittet ”Kom igång” stöder API:et både POST- och GET-metoder. Beroende på vilken metod som används returneras en statuskod i svaret. Nedan följer beskrivningar av statuskoderna för dessa två metoder.

POST-statuskoder

KodBeskrivningYtterligare anmärkningar
202Begäran har godkänts för behandling.Ett referens-ID returneras, vilket kan användas i en GET-förfrågan för att hämta lösningen när den är klar.
400Valideringen av inmatade uppgifter misslyckades (ogiltig begäran).En eller flera parametrar saknas, är ogiltiga eller har angetts felaktigt. Korrigera uppgifterna och skicka in begäran på nytt.
403Ogiltiga inloggningsuppgifter eller otillräckliga behörigheter.Begäran har mottagits, men klienten har inte behörighet på grund av saknade eller felaktiga behörigheter.
404Den begärda sökvägen hittades inte.Det här felet uppstår när den begärda URL-sökvägen inte stämmer överens med någon giltig slutpunkt.
429För många förfrågningar.QPM (förfrågningar per minut) eller begärandekvoten har överskridits. Klienten måste minska frekvensen på sina förfrågningar.
500Internt tjänstefel.Det uppstod ett problem på serversidan med API:et. Kontakta support@ddswireless.com för hjälp.

Hämta statuskoder

KodBeskrivningYtterligare anmärkningar
200Begäran har genomförts.Problemet har lösts. Resultaten returneras via statistics, routes, och unassigned.
202Begäran har godkänts men är ännu inte slutförd (status: väntande).Lösningen är inte klar än. Du får återkomma senare.
400Det gick inte att behandla begäran (ogiltig begäran).Det gick inte att ta fram någon genomförbar lösning för de angivna platserna eller parametrarna.
401Obehörig begäran.Begäran kräver användarautentisering. Servern har inte mottagit giltiga inloggningsuppgifter.
500Internt tjänstefel.Det uppstod ett problem på serversidan med vårt API. Vänligen kontakta support@ddswireless.com. Fälten statistics, routes, och unassigned kommer att vara tom.
Handledningar

Guider / Handledningar #

Här hittar du olika exempel som visar hur API:et används. API:et stöder främst två huvudsakliga användningsområden:

  1. Planering och schemaläggning — skapar ett optimerat schema för en fordonsflottas körningar, med hänsyn till begränsningar som rör uppdrag och fordon.
  2. Omoptimering — innebär att ett befintligt eller pågående schema justeras för att ta hänsyn till förändringar som nya uppdrag, avbokningar eller fordon som gått sönder.

Ta en titt på exemplen nedan för att se hur dessa användningsfall har implementerats:

  • Exempel 1 – Planering av ett enkelt scenario för upphämtning och leverans (avlämning).
  • Exempel 2 – Ett enkelt scenario för omoptimering där nya jobb läggs till i ett befintligt schema.
  • Exempel 3 – Omoptimering med avbrutna jobb.
  • Exempel 4 – Omoptimering med trasiga fordon.
Anmärkning

De platser som nämns i följande exempel är fiktiva och slumpmässigt genererade och motsvarar inga verkliga platser.

Exempel 1 · Planering

Planera ett enkelt scenario för upphämtning och leverans

En vagnpark bestående av två fordon som utför tre hämtnings- och leveransuppdrag, optimerad för att minimera den totala körtiden.

I det här exemplet består vår fordonsflotta av två fordon, och vi har tre upphämtnings- och leveransuppdrag som måste utföras av dessa två fordon. Här är uppgifterna för varje fordon:

Fordon 1

  • Arbetstidsuppgifter: Skiftet börjar den 1 oktober 2024 kl. 08:00 PST på platsen (50.67293, -120.34195) och slutar kl. 18:00 på samma plats. Tidszonen är PST, så starttiden registreras som 2024-10-01T08:00:00-08:00 och sluttiden som 2024-10-01T18:00:00-08:00.
  • Raster: Två raster, vardera på 15 minuter. Första rasten mellan kl. 10.00 och 10.30 på platsen (50.6531, -120.38393); andra rasten mellan kl. 14.00 och 14.30 på platsen (50.6531, -120.38393).
  • Kapacitet: 15 passagerare och 5 lastplatser.
  • Utrustning: Utrustad med hiss och luftkonditionering.

Fordon 2

  • Arbetstidsuppgifter: Skiftet börjar den 1 oktober 2024 kl. 08:00 PST vid koordinaterna (50.7117, -120.39286) och slutar kl. 18:00 vid koordinaterna (50.67698, -120.32012).
  • Raster: En rast på 15 minuter mellan kl. 11.00 och 11.30 på platsen (50.6531, -120.38393).
  • Kapacitet: 10 passagerare och 8 bagageplatser.
  • Utrustning: Endast utrustad med hiss.

Vi har även tre uppdrag inom ”hämtning och leverans” i Kamloops, BC, Kanada. Här är detaljerna för varje uppdrag:

Jobb 1

  • Upphämtning: Plats (50.65391, -120.37365). Tidsfönster: kl. 09.00–09.30 (uppdraget är knutet till upphämtningstidpunkten och upphämtningen måste ske inom detta tidsfönster). Varaktighet: 10 minuter. Krav: 1 passagerarplats, 2 lastplatser, fordon utrustat med lyftanordning.
  • Leverans: Plats (50.69409, -120.35425). Tid: 5 minuter.

Job 2

  • Upphämtning: Plats (50.70816, -120.37796). Tid: 5 minuter. Krav: 1 sittplats, fordon utrustat med både lyftanordning och luftkonditionering.
  • Leverans: Plats (50.66559, -120.36924). Tidsfönster kl. 12:45–13:30 (uppdraget är leveransbundet och leveransen måste genomföras inom detta tidsfönster). Varaktighet: 5 minuter.

Job 3

  • Upphämtning: Plats (50.70393, -120.37263). Tidsfönster: 14:00–14:30 (uppdraget är kopplat till upphämtningsplatsen). Varaktighet: 10 minuter. Krav: 1 passagerarplats, 3 lastplatser, ingen särskild utrustning krävs.
  • Leverans: Plats (50.69028, -120.39028). Tid: 5 minuter.

Vårt mål är att fördela dessa uppdrag på de angivna fordonen så att den totala restiden minimeras. Med andra ord är vårt optimeringsmål lika med 1. Ingångsproblemet ser ut som följer:

Indata (nyttolast)

json · nyttolast
{
    "problem": {
        "fleet": [
            {
                "id": 1,
                "shifts": [
                    {
                        "start": {
                            "time": "2023-10-01T08:00:00-08:00",
                            "location": {
                                "lat": 50.67293,
                                "lng": -120.34195
                            }
                        },
                        "end": {
                            "time": "2023-10-01T18:00:00-08:00",
                            "location": {
                                "lat": 50.67293,
                                "lng": -120.34195
                            }
                        },
                        "breaks": [
                            {
                                "serviceWindow": [
                                    "2023-10-01T10:00:00-08:00",
                                    "2023-10-01T10:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            },
                            {
                                "serviceWindow": [
                                    "2023-10-01T14:00:00-08:00",
                                    "2023-10-01T14:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            }
                        ]
                    }
                ],
                "capacities": [
                    {
                        "name": "seat",
                        "units": 15
                    },
                    {
                        "name": "cargo",
                        "units": 5
                    }
                ],
                "skills": [
                    "lift",
                    "air_conditioner"
                ]
            },
            {
                "id": 2,
                "shifts": [
                    {
                        "start": {
                            "time": "2023-10-01T08:00:00-08:00",
                            "location": {
                                "lat": 50.7117,
                                "lng": -120.39286
                            }
                        },
                        "end": {
                            "time": "2023-10-01T18:00:00-08:00",
                            "location": {
                                "lat": 50.67698,
                                "lng": -120.32012
                            }
                        },
                        "breaks": [
                            {
                                "serviceWindow": [
                                    "2023-10-01T11:00:00-08:00",
                                    "2023-10-01T11:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            }
                        ]
                    }
                ],
                "capacities": [
                    {
                        "name": "seat",
                        "units": 10
                    },
                    {
                        "name": "cargo",
                        "units": 8
                    }
                ],
                "skills": [
                    "lift"
                ]
            }
        ],
        "jobs": [
            {
                "id": 1,
                "pickups": [
                    {
                        "id": 2,
                        "location": [
                            50.65391,
                            -120.37365
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T09:00:00-08:00",
                                "2023-10-01T09:30:00-08:00"
                            ]
                        ],
                        "duration": 600,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 2
                            }
                        ],
                        "skills": [
                            "lift"
                        ]
                    }
                ],
                "deliveries": [
                    {
                        "id": 3,
                        "location": [
                            50.69409,
                            -120.35425
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 2
                            }
                        ],
                        "skills": [
                            "lift"
                        ]
                    }
                ]
            },
            {
                "id": 4,
                "pickups": [
                    {
                        "id": 5,
                        "location": [
                            50.70816,
                            -120.37796
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            }
                        ],
                        "skills": [
                            "lift",
                            "air_conditioner"
                        ]
                    }
                ],
                "deliveries": [
                    {
                        "id": 6,
                        "location": [
                            50.66559,
                            -120.36924
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T12:45:00-08:00",
                                "2023-10-01T13:30:00-08:00"
                            ]
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            }
                        ],
                        "skills": [
                            "lift",
                            "air_conditioner"
                        ]
                    }
                ]
            },
            {
                "id": 7,
                "pickups": [
                    {
                        "id": 8,
                        "location": [
                            50.70393,
                            -120.37263
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T14:00:00-08:00",
                                "2023-10-01T14:30:00-08:00"
                            ]
                        ],
                        "duration": 600,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 3
                            }
                        ]
                    }
                ],
                "deliveries": [
                    {
                        "id": 9,
                        "location": [
                            50.69028,
                            -120.39028
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 3
                            }
                        ]
                    }
                ]
            }
        ],
        "objective": 1,
        "configuration": {
            "polylineType": "none",
            "unassignedTasks": true,
            "units": "imperial",
            "statistics": true
        }
    }
}

Efter att ha skickat in detta problem med POST-metoden (enligt beskrivningen i ”Kom igång”) får vi följande lösning med GET-metoden:

Lösning

json · lösning
{
    "id": 8193,
    "status": 200,
    "solution": {
        "statistics": {
            "distance": {
                "totalDistance": 54,
                "revenueDistance": 36
            },
            "vehicles": {
                "used": 2,
                "unused": 0
            },
            "jobs": {
                "scheduledTasks": 3,
                "unassignedTasks": 0
            },
            "times": {
                "totalHours": 9.4,
                "revenueHours": 8.7
            }
        },
        "routes": [
            {
                "vehicleId": 1,
                "shifts": [
                    {
                        "index": 1,
                        "stops": [
                            {
                                "jobId": 1,
                                "taskId": 2,
                                "type": "pickup",
                                "location": [
                                    50.65391,
                                    -120.37365
                                ],
                                "eta": "2023-10-01T09:00:00-08:00",
                                "timeToNext": 10,
                                "distanceToNext": 4.9,
                                "waitTime": 0,
                                "polyline": null,
                                "ordinal": 1
                            },
                            {
                                "jobId": 1,
                                "taskId": 3,
                                "type": "delivery",
                                "location": [
                                    50.69409,
                                    -120.35425
                                ],
                                "eta": "2023-10-01T09:25:00-08:00",
                                "timeToNext": 10,
                                "distanceToNext": 5.4,
                                "waitTime": 25,
                                "polyline": null,
                                "ordinal": 2
                            },
                            {
                                "break": 1,
                                "start": "2023-10-01T10:00:00-08:00",
                                "end": "2023-10-01T10:15:00-08:00",
                                "timeToNext": 15,
                                "distanceToNext": 7.3,
                                "waitTime": 0,
                                "polyline": null,
                                "ordinal": 3
                            },
                            {
                                "jobId": 4,
                                "taskId": 5,
                                "type": "pickup",
                                "location": [
                                    50.70816,
                                    -120.37796
                                ],
                                "eta": "2023-10-01T10:30:00-08:00",
                                "timeToNext": 13,
                                "distanceToNext": 5.6,
                                "waitTime": 112,
                                "polyline": null,
                                "ordinal": 4
                            },
                            {
                                "jobId": 4,
                                "taskId": 6,
                                "type": "delivery",
                                "location": [
                                    50.66559,
                                    -120.36924
                                ],
                                "eta": "2023-10-01T12:45:00-08:00",
                                "timeToNext": 4,
                                "distanceToNext": 1.7,
                                "waitTime": 71,
                                "polyline": null,
                                "ordinal": 5
                            },
                            {
                                "break": 2,
                                "start": "2023-10-01T14:00:00-08:00",
                                "end": "2023-10-01T14:15:00-08:00",
                                "timeToNext": 7,
                                "distanceToNext": 3.2,
                                "waitTime": 217,
                                "polyline": null,
                                "ordinal": 6
                            }
                        ]
                    }
                ]
            },
            {
                "vehicleId": 2,
                "shifts": [
                    {
                        "index": 1,
                        "stops": [
                            {
                                "break": 1,
                                "start": "2023-10-01T11:00:00-08:00",
                                "end": "2023-10-01T11:15:00-08:00",
                                "timeToNext": 13,
                                "distanceToNext": 6.6,
                                "waitTime": 152,
                                "polyline": null,
                                "ordinal": 1
                            },
                            {
                                "jobId": 7,
                                "taskId": 8,
                                "type": "pickup",
                                "location": [
                                    50.70393,
                                    -120.37263
                                ],
                                "eta": "2023-10-01T14:00:00-08:00",
                                "timeToNext": 14,
                                "distanceToNext": 4.6,
                                "waitTime": 0,
                                "polyline": null,
                                "ordinal": 2
                            },
                            {
                                "jobId": 7,
                                "taskId": 9,
                                "type": "delivery",
                                "location": [
                                    50.69028,
                                    -120.39028
                                ],
                                "eta": "2023-10-01T14:29:00-08:00",
                                "timeToNext": 13,
                                "distanceToNext": 3.9,
                                "waitTime": 197,
                                "polyline": null,
                                "ordinal": 3
                            }
                        ]
                    }
                ]
            }
        ],
        "unassigned": []
    },
    "message": "success"
}
Exempel 2 · Omoptimering

Lägga till nya jobb i ett befintligt schema

Optimera om ett delvis genomfört schema kl. 11:36:34 för att inkludera ett nyligen mottaget jobb.

Tänk nu på det föregående exemplet. Anta att du har börjat följa det framtagna schemat sedan i morse, och att klockan nu är 11:36:34, och att du får en ny arbetsorder som lyder enligt följande:

Jobb 4 (ett nytt jobb)

  • Upphämtning: Plats (50.65187, -120.40052). Tidsfönster 15:45–16:15 (uppdrag med fast upphämtningsplats). Varaktighet 15 minuter. Krav: 1 passagerare, 1 last.
  • Leverans: Plats (50.69262, -120.35412). Tid: 10 minuter.

Du har redan slutfört uppdrag 1, men uppdrag 2 och uppdrag 3 pågår fortfarande med följande detaljer:

  • Uppgift 1: utförd.
  • Uppdrag 2: pågår. Upphämtning – aktuellt fordon ID 1, beräknad ankomsttid 10:30. Leverans – aktuellt fordon ID 1, beräknad ankomsttid 12:45.
  • Uppdrag 3: pågår. Upphämtning – aktuellt fordon ID 2, beräknad ankomsttid 14:00. Leverans – aktuellt fordon ID 2, beräknad ankomsttid 14:29.

Eftersom uppdrag 2 och uppdrag 3 pågår har de ett tillhörande fordons-ID och beräknad ankomsttid. För att omoptimera ditt schema så att det inkluderar det nya uppdraget (uppdrag 4) ska du skicka en uppdaterad översikt över ditt aktuella schema via API:et. Denna ska innehålla följande uppgifter om dina uppdrag:

  • Jobb 1: redan utförts, så ändra statusen för hämtnings- och leveransuppgifterna till "status":"performed". Du behöver inte ange fordonets aktuella ID-nummer och beräknade ankomsttid för dessa uppgifter, eftersom de redan har angetts och inte kan ändras.
  • Job 2: pågår fortfarande och har tilldelats fordon 1 med beräknad ankomsttid för upphämtning kl. 10.30 och beräknad ankomsttid för leverans kl. 12.45. Inkludera "status": "in_progress", "vehicleId": 1, och motsvarande eta för sina hämtnings- och leveransuppdrag.
  • Job 3: pågår fortfarande och tilldelat fordon 2 med beräknad ankomsttid för upphämtning kl. 14:00 och beräknad ankomsttid för leverans kl. 14:29. Inkludera "status": "in_progress", "vehicleId": 2, och motsvarande eta för sina hämtnings- och leveransuppdrag.
  • Job 4: ett nytt jobb, ännu inte schemalagt, så ändra dess status till "status":"pending". Du behöver inte ange något fordon-ID eller någon beräknad ankomsttid. Efter omoptimeringen får du ett fordon-ID och en beräknad ankomsttid för varje uppdrag i detta jobb.

Du måste också ange fordonens senast kända positioner så att API:et får en uppdaterad bild av ditt aktuella schema. Anta att de senast kända positionerna kl. 11:36:34 (den tidpunkt då vi vill göra en ny optimering) är: Fordonsnummer 1: (50,66692, -120,35293) och Fordonsnummer 2: (50.65324, -120.37398). Ange en lastKnownLocation objekt med platsen och time för varje fordon.

För att göra en ny optimering kan du nu skicka in ditt nya optimeringsproblem på följande sätt:

Omoptimering av nyttolasten

json · nyttolast
{
    "problem": {
        "fleet": [
            {
                "id": 1,
                "shifts": [
                    {
                        "start": {
                            "time": "2023-10-01T08:00:00-08:00",
                            "location": {
                                "lat": 50.67293,
                                "lng": -120.34195
                            }
                        },
                        "end": {
                            "time": "2023-10-01T18:00:00-08:00",
                            "location": {
                                "lat": 50.67293,
                                "lng": -120.34195
                            }
                        },
                        "breaks": [
                            {
                                "serviceWindow": [
                                    "2023-10-01T10:00:00-08:00",
                                    "2023-10-01T10:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            },
                            {
                                "serviceWindow": [
                                    "2023-10-01T14:00:00-08:00",
                                    "2023-10-01T14:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            }
                        ]
                    }
                ],
                "capacities": [
                    {
                        "name": "seat",
                        "units": 15
                    },
                    {
                        "name": "cargo",
                        "units": 5
                    }
                ],
                "skills": [
                    "lift",
                    "air_conditioner"
                ],
                "lastKnownLocation":{
                         "location":[50.66692,-120.35293],
                         "time":"2024-10-01T11:36:34-08:00"
               }                 
            },
            {
                "id": 2,
                "shifts": [
                    {
                        "start": {
                            "time": "2023-10-01T08:00:00-08:00",
                            "location": {
                                "lat": 50.7117,
                                "lng": -120.39286
                            }
                        },
                        "end": {
                            "time": "2023-10-01T18:00:00-08:00",
                            "location": {
                                "lat": 50.67698,
                                "lng": -120.32012
                            }
                        },
                        "breaks": [
                            {
                                "serviceWindow": [
                                    "2023-10-01T11:00:00-08:00",
                                    "2023-10-01T11:30:00-08:00"
                                ],
                                "duration": 900,
                                "location": {
                                    "lat": 50.6531,
                                    "lng": -120.38393
                                }
                            }
                        ]
                    }
                ],
                "capacities": [
                    {
                        "name": "seat",
                        "units": 10
                    },
                    {
                        "name": "cargo",
                        "units": 8
                    }
                ],
                "skills": [
                    "lift"
                ],
                "lastKnownLocation":{
                         "location":[50.65324,-120.37398],
                         "time":"2024-10-01T11:36:34-08:00"
               }                 
            }
        ],
        "jobs": [
            {
                "id": 1,
                "pickups": [
                    {
                        "id": 2,
                        "location": [
                            50.65391,
                            -120.37365
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T09:00:00-08:00",
                                "2023-10-01T09:30:00-08:00"
                            ]
                        ],
                        "duration": 600,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 2
                            }
                        ],
                        "skills": [
                            "lift"
                        ],
                        "status": "performed"
                    }
                ],
                "deliveries": [
                    {
                        "id": 3,
                        "location": [
                            50.69409,
                            -120.35425
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 2
                            }
                        ],
                        "skills": [
                            "lift"
                        ],
                        "status": "performed"
                    }
                ]
            },
            {
                "id": 4,
                "pickups": [
                    {
                        "id": 5,
                        "location": [
                            50.70816,
                            -120.37796
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            }
                        ],
                        "skills": [
                            "lift",
                            "air_conditioner"
                        ],
                        "status": "in_progress",
                        "vehicleId": 1,
                        "eta": "2023-10-01T10:30:00-08:00"
                    }
                ],
                "deliveries": [
                    {
                        "id": 6,
                        "location": [
                            50.66559,
                            -120.36924
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T12:45:00-08:00",
                                "2023-10-01T13:30:00-08:00"
                            ]
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            }
                        ],
                        "skills": [
                            "lift",
                            "air_conditioner"
                        ],
                        "status": "in_progress",
                        "vehicleId": 1,
                        "eta": "2023-10-01T12:45:00-08:00"
                    }
                ]
            },
            {
                "id": 7,
                "pickups": [
                    {
                        "id": 8,
                        "location": [
                            50.70393,
                            -120.37263
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T14:00:00-08:00",
                                "2023-10-01T14:30:00-08:00"
                            ]
                        ],
                        "duration": 600,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 3
                            }
                        ],
                        "status": "in_progress",
                        "vehicleId": 2,
                        "eta": "2023-10-01T14:00:00-08:00"                        
                    }
                ],
                "deliveries": [
                    {
                        "id": 9,
                        "location": [
                            50.69028,
                            -120.39028
                        ],
                        "duration": 300,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 3
                            }
                        ],
                        "status": "in_progress",
                        "vehicleId": 2,
                        "eta": "2023-10-01T14:29:00-08:00"                       
                    }
                ]
            },
            {
                "id": 10,
                "pickups": [
                    {
                        "id": 11,
                        "location": [
                            50.65187,
                            -120.40052
                        ],
                        "serviceWindows": [
                            [
                                "2023-10-01T15:45:00-08:00",
                                "2023-10-01T16:15:00-08:00"
                            ]
                        ],
                        "duration": 900,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 1
                            }
                        ],
                        "status": "pending"
                    }
                ],
                "deliveries": [
                    {
                        "id": 12,
                        "location": [
                            50.69262,
                            -120.35412
                        ],
                        "duration": 600,
                        "demand": [
                            {
                                "name": "seat",
                                "units": 1
                            },
                            {
                                "name": "cargo",
                                "units": 1
                            }
                        ],
                        "status": "pending"
                    }
                ]
            }

        ],
        "objective": 1,
        "configuration": {
            "polylineType": "none",
            "unassignedTasks": true,
            "units": "imperial",
            "statistics": true
        }
    }
}
Exempel 3 · Omoptimering

Omoptimering med avbrutna jobb

Ta bort avbrutna jobb från ett befintligt schema och optimera de återstående jobben på nytt.

Om du har skickat in ett optimeringsproblem för en uppsättning jobb och redan har ett schema klart, men vissa jobb har avbokats, kan du optimera om schemat genom att ta bort de avbokade jobben från problemet. För att göra detta måste du:

  • Ge en aktuell översikt över dina återstående uppdrag och fordonens senast kända positioner, på samma sätt som i exempel 2.
  • Skapa och skicka in en reviderad uppgift som återspeglar dessa ändringar.

När du har skickat in uppgifterna kommer du att få ett nytt schema som tar hänsyn till de uppdaterade uppdragen och fordonsflottans status.

Exempel 4 · Omoptimering

Omoptimering med trasiga fordon

Omfördela arbetet för ett fordon som har gått sönder mitt under arbetspasset.

Anta att klockan är 08:00 och att du använder API:et för att skapa ett optimerat körschema för dina uppdrag med 10 fordon. Du börjar genomföra schemat, men klockan 09:14 får du reda på att ett av dina fordon har gått sönder och inte längre kan utföra sina tilldelade uppdrag. Gör så här för att optimera schemat på nytt:

  1. Uppdatera flottans uppgifter. Ta bort det trasiga fordonet från ditt flottobjekt.
  2. Ange fordonens positioner. Ange de sista kända positionerna för de återstående fordonen, på samma sätt som i exempel 2.
  3. Uppdatera uppgifternas status. Ange status för alla uppgifter: specificera vilka uppgifter som redan har utförts, vilka som pågår och vilka som är nya eller väntande. För pågående uppgifter ska du ange tillhörande fordons-ID och beräknad ankomsttid.
  4. Ta hand om det trasiga fordonet. Ändra statusen för alla uppgifter som tidigare tilldelats det havererade fordonet till "pending". Detta gör det möjligt för API:et att omfördela dem till andra tillgängliga fordon och beräkna deras beräknade ankomsttider på nytt.
  5. Skicka in för ny optimering. Skicka in det uppdaterade problemet till API:et för en ny schemaläggningsoptimering.

Så här testar du schemalagda rutter #

Steg 1 – Skapa en åtkomsttoken

Skicka först en POST-förfrågan till följande URL för att hämta en åtkomsttoken med hjälp av uppgifterna nedan.

INLÄGG https://iq.aiqwhite.ddsdeploytest.com/sso/auth-token

POST-förfrågans innehåll för Vancouver (Hyresgäst 2):

json · begäran
{
    "plugin": "internal;basic",
    "internal": {
        "email": "YOUR_EMAIL",
        "password": "YOUR_PASSWORD",
        "tenantId": 2
    },
    "basic": {
        "username": "YOUR_EMAIL",
        "password": "YOUR_PASSWORD",
        "tenantId": 2
    }
}

POST-förfrågans innehåll för Finland (Tenant 3):

json · begäran
{
    "plugin": "internal;basic",
    "internal": {
        "email": "YOUR_EMAIL",
        "password": "YOUR_PASSWORD",
        "tenantId": 3
    },
    "basic": {
        "username": "YOUR_EMAIL",
        "password": "YOUR_PASSWORD",
        "tenantId": 3
    }
}

Kopiera sedan den genererade koden. Här är en skärmdump av detta steg:

Skärmdump av hur man skapar en åtkomsttoken

Steg 2 – Skicka en indata (optimeringsproblem) till API:et

För att skicka en indata till API:et och få ett referens-ID ska du ange det genererade tokenet i fältet ”Authorization” i följande POST-förfrågan och placera indata i fältet ”Body” i förfrågan.

INLÄGG https://iq.aiqwhite.ddsdeploytest.com/raas/optimization

Ett exempel på en datapaket:

json · nyttolast
{
  "problem": {
    "fleet": [
      {
        "id": 1,
        "shifts": [
          {
            "start": {
              "time": "2023-10-01T08:00:00-08:00",
              "location": { "lat": 50.67293, "lng": -120.34195 }
            },
            "end": {
              "time": "2023-10-01T18:00:00-08:00",
              "location": { "lat": 50.67293, "lng": -120.34195 }
            },
            "breaks": [
              {
                "serviceWindow": ["2023-10-01T10:00:00-08:00", "2023-10-01T10:30:00-08:00"],
                "duration": 900,
                "location": { "lat": 50.6531, "lng": -120.38393 }
              },
              {
                "serviceWindow": ["2023-10-01T14:00:00-08:00", "2023-10-01T14:30:00-08:00"],
                "duration": 900,
                "location": { "lat": 50.6531, "lng": -120.38393 }
              }
            ]
          }
        ],
        "capacities": [
          {
            "name": "seat",
            "units": 15
          },
          {
            "name": "baggage",
            "units": 5
          }
        ],
        "skills": ["lift", "air_conditioner"]
      },
      {
        "id": 2,
        "shifts": [
          {
            "start": {
              "time": "2023-10-01T08:00:00-08:00",
              "location": { "lat": 50.7117, "lng": -120.39286 }
            },
            "end": {
              "time": "2023-10-01T18:00:00-08:00",
              "location": { "lat": 50.67698, "lng": -120.32012 }
            },
            "breaks": [
              {
                "serviceWindow": ["2023-10-01T11:00:00-08:00", "2023-10-01T11:30:00-08:00"],
                "duration": 900,
                "location": { "lat": 50.6531, "lng": -120.38393 }
              }
            ]
          }
        ],
        "capacities": [
          {
            "name": "seat",
            "units": 10
          },
          {
            "name": "baggage",
            "units": 8
          }
        ],
        "skills": ["lift"]
      }
    ],
    "jobs": [
      {
        "id": 1,
        "pickups": [
          {
            "id": 2,
            "location": [50.65391, -120.37365],
            "serviceWindows": [["2023-10-01T09:00:00-08:00", "2023-10-01T09:30:00-08:00"]],
            "duration": 600,
            "demand": [
              {
                "name": "seat",
                "units": 1
              },
              {
                "name": "baggage",
                "units": 2
              }
            ],
            "skills": ["lift"]
          }
        ],
        "deliveries": [
          {
            "id": 3,
            "location": [50.69409, -120.35425],
            "duration": 300,
            "demand": [
              {
                "name": "seat",
                "units": 1
              },
              {
                "name": "baggage",
                "units": 2
              }
            ],
            "skills": ["lift"]
          }
        ]
      },
      {
        "id": 4,
        "pickups": [
          {
            "id": 5,
            "location": [50.70816, -120.37796],
            "duration": 300,
            "demand": [
              {
                "name": "seat",
                "units": 1
              }
            ],
            "skills": ["lift", "air_conditioner"]
          }
        ],
        "deliveries": [
          {
            "id": 6,
            "location": [50.66559, -120.36924],
            "serviceWindows": [["2023-10-01T12:45:00-08:00", "2023-10-01T13:30:00-08:00"]],
            "duration": 300,
            "demand": [
              {
                "name": "seat",
                "units": 1
              }
            ],
            "skills": ["lift", "air_conditioner"]
          }
        ]
      },
      {
        "id": 7,
        "pickups": [
          {
            "id": 8,
            "location": [50.70393, -120.37263],
            "serviceWindows": [["2023-10-01T14:00:00-08:00", "2023-10-01T14:30:00-08:00"]],
            "duration": 600,
            "demand": [
              {
                "name": "seat",
                "units": 1
              },
              {
                "name": "baggage",
                "units": 3
              }
            ]
          }
        ],
        "deliveries": [
          {
            "id": 9,
            "location": [50.69028, -120.39028],
            "duration": 300,
            "demand": [
              {
                "name": "seat",
                "units": 1
              },
              {
                "name": "baggage",
                "units": 3
              }
            ]
          }
        ]
      }
    ],
    "objective": 1,
    "configuration": {
        "polylineType": "none",
        "unassignedTasks": true,
        "units" : "imperial",
        "statistics" : true
    }
  }
}

Om POST-metoden lyckas får du ett referens-ID som du kan använda för att hämta svaret med GET-metoden. Nedan visas en skärmdump av detta steg:

Skärmdump av inlämning av en indata-payload

Steg 3 – Hämta svaret från API-anropet

För att få ett svar med hjälp av det mottagna referens-ID:t ska du ange åtkomsttokenet i avsnittet ”Authorization” i följande GET-förfrågan och inkludera referens-ID:t i URL:en.

GET https://iq.aiqwhite.ddsdeploytest.com/raas/optimization/{ID}

Här är en skärmdump av det här steget:

Skärmdump av hämtningen av svarsmeddelandet
Referens

Ordlista #

TerminDefinition
problemEtt optimeringsproblem avseende ruttplanering och schemaläggning som ska lösas av API:et.
solutionDen lösning på optimeringsproblemet för ruttplanering och schemaläggning som API:et tillhandahåller.
fleetEn fordonsflotta består av en lista över fordonstyper och information om dessa.
jobEn lista över leverans- eller hämtnings- och leveransuppdrag som måste utföras av ett visst fordon.
taskEn uppgift ingår i ett arbete och ska utföras på en viss plats och vid en viss tidpunkt.
breakEtt attribut för att ange en eller flera rasttider för förare på specifika platser.
demandKrav på uppgiftskapacitet uttryckt i flerdimensionella enheter (t.ex. volym, massa).
durationDen tid som läggs på att utföra en uppgift eller ta en paus.
shiftsFastställer körscheman för fordonen, inklusive start- och sluttider, platser och eventuella raster.
deliveryEn arbetsuppgift som går ut på att leverera något som lastades tidigare under turen.
pickup and deliveryEtt uppdrag där både upphämtnings- och leveransplatserna är angivna.
skillsKrav på fordonet för att kunna utföra vissa uppgifter (t.ex. utrustning, storlekskrav).
service windowEtt tidsintervall inom vilket en uppgift måste slutföras.
start/end locationVar ett fordon avgår från eller återvänder till (t.ex. depå eller garage).
start/end timeAnger tidpunkter för skift, raster, avgångar eller arbetsuppgifter.
locationLatitud och longitud för en adress i WGS84-format.
re-optimizationUppdatering av ett aktivt schema på grund av ändringar, till exempel nya eller inställda beställningar.
ID (or id)En unik identifierare för ett uppdrag, en uppgift eller ett fordon.
VRPRuttplaneringsproblemet.
CVRPRuttplaneringsproblem för fordon med kapacitetsbegränsningar.
PDPProblem med upphämtning och leverans.
limitsKrav som gäller för en fordonstyp.
objectiveDen optimeringsstrategi som användes för att lösa problemet.
statisticsStatistik över de optimerade rutterna som återges i lösningen.
stopEn lista över aktiviteter som utförs vid en viss tidpunkt/på en viss plats längs en rutt.
unassigned jobs/tasksUppgifter som inte kunde tilldelas en rutt.
ETABeräknad ankomsttid. Anges för alla hållplatser i utdata.
polylineEn sammanhängande linje som visar en rutt på kartan.
encoded polylineEn komprimerad strängversion av en polylinje, som används för att minimera datastorleken (t.ex., _kv~uF|y~wGdkZ~gAx|]t@).
Referens

Vanliga frågor #

FrågaSvar
Stöder API:et lösningen av problemet med upphämtning och leverans (PDP)?Ja, se avsnittet ”Handledning” för en detaljerad förklaring.
Stöder API:et öppen PDP?Ja, du kan ange valfria start- och slutplatser för varje fordon i din vagnpark.
Använder API:et trafikdata i realtid?Ja, den använder både historiska trafikdata och trafikdata i realtid.
Kan jag ange tidpunkter för vagnbyten, start- och slutplatser samt raster?Ja, se flottan på problemsidan.
Kan vi definiera flera valfria kapacitetstyper för fordon?Ja, den capacity Attributet i flottan-objektet stöder flera mått, såsom vikt, volym och antal.
Kan vi ange det maximala antalet uppdrag per fordon?Ja, detta kan definieras med hjälp av flottobjektet på sidan Problem.
Stöder API:et flera avbrott per fordon?Ja, detta stöds via flottan-objektet på sidan Problem.
Stöder API:et upphämtningar, leveranser eller båda?Ja, se objektet ”jobs” i dokumentationen för Problem.
Kan jag ange hur lång tid en uppgift ska ta?Ja, använd attributet duration i objektet jobs i Problem.
Kan jag ange egna krav på kapacitet för uppgifterna?Ja, detta stöds via objektet ”jobs” i problemdefinitionen.
Kan vi ange ett tidsfönster för varje uppgift?Ja, ange tidigaste och senaste starttidpunkter med hjälp av tidsfönster i jobbojektet.
Kan jag ange vilka färdigheter eller egenskaper som krävs för varje uppgift?Ja, egenskaper stöds i jobbojektet och underlättar matchningen av uppdrag med lämpliga fordon eller förare.
Stöder API:et omoptimering av pågående rutter?Ja, se handledningarna för information om hur du kan optimera pågående lösningar på nytt.
Tillhandahåller API:et statistik över rutter och tidtabeller?Ja, se Lösning för detaljerad statistik om till exempel restid, sträcka och icke tilldelade uppdrag.
Förklarar API:et varför uppgifterna inte tilldelades någon?Ja, se Lösning för att ta reda på orsakerna till att jobb inte tilldelats.
Returnerar API:et beräknade ankomsttider?Ja, se Lösning för beräknade ankomsttider per uppgift.
Kan API:et gruppera jobb efter plats?Ja, klusterhantering stöds för att förbättra ruttens effektivitet.
Kan jag välja olika optimeringsmål?Ja. Alternativen är: Minimera total restid, Minimera antalet rutter och Fördela arbetsbelastningen mellan rutterna. Se avsnittet ”Problem” för mer information.

Schemalagda rutter — API för ruttplanering och schemaläggning. Behöver du hjälp? Kontakta support@ddswireless.com.

I version 1.1 lades stöd för ruttmallar till. I version 1.2 lades stöd för flexibel konfiguration av fordonskapacitet till.