Übersicht über die API für Linienflüge
Planen und optimieren Sie Routen für Fahrzeugflotten unter Berücksichtigung von Zeitfenstern, Kapazitätsgrenzen, Verkehrsbedingungen und Fahrerpausen. Geben Sie ein Problem ein und erhalten Sie eine optimierte Lösung.
Die API wurde entwickelt, um die Routenplanung und Terminierung für Fahrzeugflotten zu optimieren und dabei wichtige Einschränkungen wie Zeitfenster für die Dienstleistungen, Kapazitätsgrenzen und Verkehrsbedingungen zu berücksichtigen. Durch den Einsatz der API können Unternehmen die Effizienz ihrer Lieferungen deutlich steigern, Betriebskosten senken und durch optimierte Routen- und Terminierungslösungen wertvolle Zeit sparen.
Im Kern löst die API das Fahrzeug-Routing-Problem (VRP) im Zusammenhang mit Abhol- und Lieferfahrten. Bei diesem Problem geht es darum, die effizientesten Routen für eine Fahrzeugflotte zu berechnen, die mehrere Standorte anfährt, um Abhol- und Lieferaufträge auszuführen, wobei Einschränkungen wie Zeitfenster, Fahrzeugkapazität und Verfügbarkeit berücksichtigt werden müssen.
Darüber hinaus unterstützt die API dynamische Plananpassungen oder eine Neuoptimierung. Wenn Sie einen bestehenden Plan ändern müssen – sei es aufgrund neuer Aufträge, Stornierungen oder anderer Änderungen –, können Sie ein aktuelles Bild Ihres Plans bereitstellen, indem Sie die Auftragsstatus und Fahrzeugstandorte angeben. Die API optimiert den Plan dann neu, um diese Änderungen zu berücksichtigen, und gewährleistet so eine kontinuierliche Effizienz Ihrer Betriebsabläufe.
Informationen dazu, wie Sie sich schnell einarbeiten und mit der Nutzung der API beginnen können, finden Sie unter „Erste Schritte“. Im Abschnitt „Tutorials“ stehen Ihnen außerdem mehrere kurze Anleitungen zur Verfügung.
- In Version 1.1 wurde die Unterstützung für Routenvorlagen hinzugefügt.
- In Version 1.2 wurde die Unterstützung für eine flexible Konfiguration der Fahrzeugkapazität hinzugefügt.
Schnellstart
„Scheduled Routes“ ist eine asynchrone API: Senden Sie ein Routing- und Terminierungsproblem, erhalten Sie eine Referenz-ID und fragen Sie diese ID so lange ab, bis die optimierte Lösung bereitsteht.
Senden Sie Anfragen mit einem API-Zugriffstoken im „Authorization“-Header.
Verwendung POST /raas/optimization mit einem problem Nutzlast.
Verwendung GET /raas/optimization/{id} bis die Lösung zurückgegeben wird.
Authentifizierung
Anfragen verwenden ein Bearer-Zugriffstoken im Authorization Kopfzeile. Ersetzen YOUR_ACCESS_TOKEN mit Ihrem generierten API-Zugriffstoken.
Authorization: Bearer YOUR_ACCESS_TOKENDie ursprüngliche Quelldokumentation enthielt Beispiel-Bearer-Token und Testzugangsdaten. Diese WordPress-kompatible Datei behält die Beispiele und Anleitungen bei, verwendet jedoch Platzhalter wie YOUR_ACCESS_TOKEN, YOUR_EMAILund YOUR_PASSWORD damit Zugangsdaten nicht versehentlich veröffentlicht werden.
API-Lebenszyklus #
Die API bietet zwei wichtige Methoden zur Optimierung von Routenplanung und Terminierung:
- Optimierung (POST ) – Senden Sie ein Problem zur Routen- und Terminoptimierung. Nach dem Absenden einer POST-Anfrage erhalten Sie eine eindeutige Referenz-ID.
- Optimierung GET — Rufen Sie den Status eines eingereichten Problems anhand der eindeutigen Referenz-ID ab, die Sie über die POST-Methode erhalten haben. Wenn die Optimierungslösung bereitsteht, können Sie die Lösung des Optimierungsproblems abrufen.
So funktioniert die Optimierung #
Um ein Routen- und Terminplanungs-Optimierungsproblem für eine Fahrzeugflotte zu lösen, gehen Sie wie folgt vor:
- Definieren Sie das Problem. Beginnen Sie damit, Ihr Problem anhand des im Abschnitt „Problem“ angegebenen Formats zu skizzieren.
- Senden Sie das Problem. Verwenden Sie die POST-Methode, wie unter „Erste Schritte“ beschrieben, um Ihr Problem an die API zu senden.
- Lösung abrufen. Rufen Sie die Lösung für Ihr Optimierungsproblem mithilfe der GET-Methode ab. Das Format der Lösung ist im Abschnitt „Lösung“ beschrieben.
Weitere Informationen zu den verschiedenen Begriffen, die in der API verwendet werden, finden Sie im Glossar. Eine Liste mit häufig gestellten Fragen finden Sie in den FAQ.
POST /raas/optimization #
Verwenden Sie diese Methode, um Ihr Routen- und Terminplanungsoptimierungsproblem an die API zu übermitteln. Sobald eine POST-Anfrage zur Optimierung erfolgreich übermittelt wurde, gibt die API in der Bestätigungsantwort eine eindeutige Referenz-ID zurück. Verwenden Sie diese eindeutige ID, um die eigentliche Lösung mithilfe der GET-Methode zur Optimierung abzurufen (siehe nächster Abschnitt).
Beispielanfrage (cURL)
Ein Beispiel für die Übermittlung eines Optimierungsproblems mittels der POST-Methode mit einem Beispiel-Token und einer Beispiel-Nutzlast. In diesem Beispiel befindet sich das Eingabeproblem in einer Datei namens payload.json. Ersetzen Sie das Beispiel-Token YOUR_ACCESS_TOKEN mit Ihrem eigenen Token. Das Schema für das Eingabeproblem ist in der Problem Abschnitt.
Antwortschema
Nach dem Absenden der POST-Anfrage erhalten Sie eine Antwortnachricht im folgenden Format:
Wenn die Übermittlung erfolgreich war, wird die status wird 202, mit dem message mit der Angabe „akzeptiert“ und der id die eindeutige Referenznummer für den asynchronen Vorgang. Diese ID dient dazu, den Status des Vorgangs zu verfolgen und die Ergebnisse später abzurufen.
Falls ein Fehler auftritt, wird die status zeigt einen Fehlercode an, der id entweder null oder leer sein, das message wird „Fehler“ lauten, und die error beschreibt den Fehler. Weitere Informationen finden Sie in den unten aufgeführten POST-Statuscodes.
Beispielanfrage (Windows PowerShell)
Das folgende Skript zeigt, wie man in Windows PowerShell eine POST-Anfrage mit einer Beispiel-Nutzlast durchführt. Es wird davon ausgegangen, dass die Eingabe-Nutzlast in einer Datei namens payload.json, und das API-Zugriffstoken wird gespeichert in token.txt. Bei der Ausführung wird die generierte ID in id.txt. Um PowerShell zu starten, geben Sie einfach „PowerShell“ im Startmenü oder in der Befehlszeile ein.
POST-Statuscodes
| Code | Beschreibung | Weitere Hinweise |
|---|---|---|
| 202 | Der Antrag wurde zur Bearbeitung angenommen. | Es wird eine Referenz-ID zurückgegeben, mit der Sie die Lösung mittels einer GET-Anfrage abrufen können, sobald sie fertig ist. |
| 400 | Die Eingabevalidierung ist fehlgeschlagen (Ungültige Anfrage). | Fehlender/ungültiger Parameter oder falscher Werttyp. Überprüfen Sie die Eingabedaten und versuchen Sie es erneut. |
| 403 | Unzulässige Anfrage. | Dies geschieht, wenn die Authentifizierung fehlschlägt. |
| 404 | Der angeforderte Pfad wurde nicht gefunden. | Dies geschieht, wenn ein falscher Pfad verwendet wird. |
| 429 | Zu viele Anfragen. | Ratenlimit überschritten (Anfragen pro Minute oder Kontingent erreicht). |
| 500 | Interner Dienstfehler. | Das Problem liegt bei uns. Bitte wenden Sie sich an support@ddswireless.com. |
GET /raas/optimization/{id} #
Verwenden Sie diese Methode, um die optimierte Lösung für die Optimierungsaufgaben abzurufen, die mit der POST-Methode „Optimierung“ erstellt wurden. Dazu müssen Sie die Referenz-ID angeben, die Sie von der POST-Methode erhalten haben.
Beispielanfrage (cURL)
Ein Beispiel dafür, wie man die Antwort der API mithilfe der GET-Methode und einer ID abruft. Ersetzen Sie ID in der URL mit der ID, die du über die POST-Methode erhalten hast, und vergiss nicht, dein eigenes API-Zugriffstoken zu verwenden.
Wenn zum Beispiel ID ist gleich 5, verwende Folgendes:
Antwortschema
Wenn die Lösung fertig ist, statistics, routesund unassigned wird auf der Grundlage der erhaltenen Lösung ausgefüllt. Andernfalls, ähnlich wie bei der POST-Methode, status, messageund error zeigt den Status oder den Fehler an.
Das Schema für die Ausgabelösung ist im Abschnitt „Lösung“ definiert.
Beispielanfrage (Windows PowerShell)
Das folgende Skript zeigt, wie man eine GET-Anfrage unter Verwendung einer ID erstellt, die mit der POST-Methode generiert wurde. Es wird davon ausgegangen, dass die ID in einer Datei namens id.txt, und das API-Zugriffstoken wird gespeichert in token.txt. Bei der Ausführung wird die generierte Antwort in response.txt.
GET-Statuscodes
| Code | Beschreibung | Weitere Hinweise |
|---|---|---|
| 200 | Die Anfrage war erfolgreich. | Die Lösung wird über statistics, routesund unassigned. |
| 202 | Die Anfrage wurde angenommen, ist jedoch noch nicht abgeschlossen. | Der Status lautet „In Bearbeitung“. Bitte schauen Sie später noch einmal nach, ob eine Lösung bereitsteht. |
| 400 | Die Anfrage konnte nicht verarbeitet werden (Ungültige Anfrage). | Aufgrund ungültiger Eingaben oder Parameter konnte keine brauchbare Lösung ermittelt werden. |
| 401 | Unzulässige Anfrage. | Eine Benutzerauthentifizierung ist erforderlich. Es wurden keine gültigen Anmeldedaten empfangen. |
| 500 | Interner Dienstfehler. | Auf unserer Seite ist ein Fehler aufgetreten. Kontakt support@ddswireless.com. Felder wie statistics, routesund unassigned wird leer sein. |
Codeformate
Verwenden Sie denselben Endpunkt-Ablauf in Ihrem bevorzugten Format. Diese Beispiele behalten die Anforderungsstruktur aus der API-Referenz bei und verwenden für die Veröffentlichung geeignete Platzhalter.
Optimierungsproblem einreichen
cURL
curl -X POST "https://iq.scheduledroutes.ddswireless.net/raas/optimization" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d @payload.jsonPython
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 $responseEin Optimierungsergebnis abrufen
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())Objekte
Das Anfrageobjekt konzentriert sich auf problem. Das Antwortobjekt ist zentriert auf solution. Die ursprünglichen Verweise, Beispiele, Diagramme, Anmerkungen und Regeln sind im Folgenden beibehalten worden.
Problem, Flotte / Fahrzeug / Schicht / Pause, Auftrag / Aufgabe / Abholung / Lieferung, Ziel und Konfiguration.
Anleitungen, Glossar und FAQ.
Das Problem-Objekt #
Die Problem Dieses System stellt ein Routing- und Terminierungsproblem dar. Wie in der folgenden Abbildung dargestellt, besteht es aus vier Hauptkomponenten: fleet, jobs, objectiveund configuration. Darunter fleet und jobs sind obligatorisch, während objective und configuration sind optional.
Um einen Standort oder eine Adresse in der API anzugeben, verwenden Sie WGS84-Geokoordinaten mit mindestens 5 Dezimalstellen, um eine hohe Genauigkeit zu gewährleisten. Beispielsweise lautet die Adresse „1600 Amphitheatre Parkway, Mountain View, CA“ hat die Breitengradkoordinate 37.423021 und Längengrad -122.083739. Sie können es wie folgt angeben: "location": {"lat": 37.423021, "lng": -122.083739} oder als [37.423021, -122.083739].
Die API verwendet das ISO-8601-Format für Zeitstempel, einschließlich Zeitzonenangaben, um die Ortszeit für das Gebiet zu definieren, für das Sie eine optimierte Routen- und Terminplanung benötigen. Zum Beispiel: 2024-07-31T14:45:30-08:00 entspricht dem 31. Juli 2024 um 14:45:30 Uhr PST, was einer Zeitverschiebung von 8 Stunden gegenüber der koordinierten Weltzeit (UTC) entspricht.
In der Eingabedatenlast müssen Sie durchgehend dieselbe lokale Zeitzone verwenden. Werden mehrere Zeitzonen erkannt, gibt die API einen Fehler zurück. Die Zeiten für geplante Stopps in der Ausgabemeldung werden in demselben Format angegeben, wie es in der Eingabedatenlast festgelegt wurde. Wenn Sie beispielsweise angeben 2024-07-31T14:45:30-08:00 Wenn Sie dies in Ihrer Eingabe angeben, werden die optimierten Fahrzeiten in der Ausgabe ebenfalls -08:00; wenn Sie +05:30 Wenn in der Eingabe steht, wird in der Ausgabe +05:30.
Alle optionalen Attribute können in der Nutzlast weggelassen werden. Leere Arrays (z. B. []) kann auch für optionale Attribute verwendet werden, die ein Array akzeptieren.
Stellen Sie sicher, dass die an die API gesendeten Daten keine vertraulichen oder persönlichen Informationen enthalten. Vermeiden Sie es beispielsweise, reale Identifikationsmerkmale wie Kfz-Kennzeichen als Fahrzeug-ID oder Auftrags-/Aufgaben-IDs zu verwenden.
Komponentenübersicht
Legt eine Liste von Fahrzeugen zusammen mit zugehörigen Informationen wie Schichtplänen, Start- und Endorten, Pausen, Kapazitäten und Fähigkeiten fest. Für jedes Fahrzeug können Sie einen oder mehrere Schichtpläne (Start-/Endzeiten und -orte), eine oder mehrere Pausen (Zeitfenster, Ort und Dauer), eine oder mehrere Kapazitätsarten mit verfügbaren Einheiten (mehrdimensionale Einheiten wie Volumen, Masse oder Größe) sowie eine oder mehrere Fähigkeiten definieren, die es ihm ermöglichen, bestimmte Aufgaben auszuführen. Beispielsweise könnten Sie „Schweißgerät“ und „Sauerstoffflasche“ als Fähigkeiten für ein Fahrzeug und „Hebebühne“ als Fähigkeit für ein anderes Fahrzeug zuweisen; wenn ein Auftrag eine Hebebühne erfordert, wird er nur von dem Fahrzeug ausgeführt, das über diese Fähigkeit verfügt. Sie können auch Grenzen festlegen, wie die maximale Anzahl von Stopps und die maximale Fahrstrecke (in Meilen).
Gibt eine Liste der Aufträge an, die von den Fahrzeugen im fleetJeder Auftrag kann eine Reihe von Aufgaben umfassen, bei denen es sich ausschließlich um Abholungen, ausschließlich um Zustellungen oder um beides handeln kann. Behandeln Sie „Besuchs“-Aufträge, bei denen Sie einen Standort aufsuchen müssen, um Arbeiten durchzuführen (z. B. Reparaturen, Installation eines Modems), als Zustellungsaufgabe mit oder ohne Kapazitätsbedarf. Für jede Aufgabe können Sie Attribute wie Ort, Zeitfenster, Dauer, Kapazitätsanforderungen und erforderliche Fähigkeiten definieren. Wenn der Optimierer keine geeignete voraussichtliche Ankunftszeit (ETA) für eine Aufgabe innerhalb des angegebenen Zeitfensters finden kann, bleibt die Aufgabe unzugewiesen. Für flexible oder nicht zeitkritische Aufgaben geben Sie ein breiteres Zeitfenster an (maximal 24 Stunden).
Legt das Optimierungsziel oder die Optimierungsstrategie fest. Derzeit werden drei Ziele unterstützt:
- Gesamtfahrzeit minimieren – die Standardstrategie; minimiert die Gesamtfahrzeit der Flotte bei der Erledigung der angegebenen Aufträge.
- Anzahl der Routen minimieren – reduziert die Anzahl der Fahrzeuge, die zur Erledigung der Aufträge benötigt werden. Dies kann jedoch als Kompromiss zu einer längeren Gesamtfahrzeit oder einer höheren Auslastung der einzelnen Fahrzeuge führen.
- Ausgleich der Auslastung auf die Routen – verteilt die Auslastung gleichmäßig auf alle Fahrzeuge der Flotte. Dieser Ausgleich kann zu einer Verlängerung der Gesamtfahrzeit führen.
Passt die API-Einstellungen an oder ändert die Standardoptionen. Sie können beispielsweise festlegen, ob die API-Antwort eine Zusammenfassung der Optimierungsstatistiken (wie Gesamtfahrzeit und -strecke) oder eine Liste der nicht zugewiesenen Aufgaben enthalten soll.
Schema für Eingabeanforderung #
Das Schema der Eingabeanfrage zur Lösung eines Routenoptimierungsproblems sieht wie folgt aus. Um ein Problem einzureichen, muss diese Anfrage gemäß der Beschreibung unter „Erste Schritte“ in der POST-Methode enthalten sein.
Bei einem Routenoptimierungsproblem soll eine Fahrzeugflotte eine Reihe von Aufträgen effizient abwickeln. Über das obige Schema können Sie Ihre Flotte und Ihre Aufträge definieren. In der aktuellen Version der API kann jeder Auftrag:
- Nur Abholaufträge – dabei werden Gegenstände entlang der Route abgeholt und zum Endpunkt der Route geliefert.
- Nur Lieferaufträge – erfordern die Zustellung von Artikeln, die zu Beginn der Route auf das Fahrzeug verladen werden.
- Abhol- und Zustellaufgaben (A/Z) zusammen – beide Vorgänge kombinieren: etwas an einem Ort abholen und an einen anderen bringen.
Für den Auftrag müssen mindestens ein Mitarbeiter und ein Fahrzeug bereitgestellt werden. Bei „Besuchs“-Aufträgen, bei denen ein Vor-Ort-Einsatz erforderlich ist (z. B. Reparaturen, Modem-Installationen), sind diese als Lieferaufträge zu betrachten, mit oder ohne Kapazitätsanforderung.
Außerdem:
- Wenn nur die
pickupsWird für einen Auftrag ein Objekt bereitgestellt, gilt dieser als reiner Abholauftrag. - Wenn nur die
deliveriesWird für einen Auftrag ein Objekt bereitgestellt, gilt dieser als reiner Lieferauftrag. - Wenn beide
pickupsunddeliveriesWenn diese Angaben vorliegen, wird der Auftrag als Abhol- und Zustellauftrag eingestuft.
Die API unterstützt keine Aufträge mit mehreren Abholungen und mehreren Zustellungen. Mit anderen Worten, bei einem „Abhol- und Zustell“-Auftrag:
- Die
pickupsDas Array darf nur enthalten eins Abholauftrag. - Die
deliveriesDas Array darf nur enthalten eins Lieferauftrag.
Die API unterstützt zudem keine Aufträge ohne Abholung und ohne Zustellung. Klassifizierungsregeln:
- Wenn nur
pickupsist definiert, wird der Auftrag als an der Tonabnehmerhalterung befestigt Stelle. - Wenn nur
deliveriesist definiert, wird der Auftrag als lieferungsgebunden Stelle. - Wenn sowohl Abholung als auch Zustellung definiert sind, ist der Anker derjenige, der ein Zeitfenster enthält.
- Wenn sowohl für die Abholung als auch für die Zustellung Zeitfenster angegeben sind, gilt der Auftrag als abholungsgebunden.
Für jeden Auftrag können verschiedene Attribute und Einschränkungen definiert werden, wie beispielsweise Kapazitätsanforderungen, Zeitfenster für die Erbringung der Dienstleistung und erforderliche Qualifikationen. Besuchsaufträge, bei denen bestimmte Orte aufgesucht werden müssen, um Aufgaben (z. B. Reparaturen) auszuführen, können als eine spezielle Form von Lieferaufträgen betrachtet werden (mit oder ohne Kapazitätsanforderungen). Aufgaben werden Fahrzeugen zugewiesen, deren Kapazitäten oder Qualifikationen den Anforderungen der Aufgabe entsprechen. Wenn für eine Aufgabe beispielsweise eine Hebebühne oder eine Leiter benötigt wird, werden nur Fahrzeuge eingesetzt, die mit einer Hebebühne oder einer Leiter ausgestattet sind.
problem — Feldreferenz
Problem ( erforderlich ) Gibt das Routing- und Terminierungsoptimierungsproblem an, das Sie lösen möchten. Es besteht aus den folgenden Attributen.
fleet
flotte erforderlich Definiert die Flotteninformationen. Es handelt sich um ein Array von Flottenobjekten. Jedes Flottenobjekt besteht aus den folgenden Attributen:
Eine eindeutige Kennung für das Fahrzeug.
Ein Array von Schichtobjekten. Jedes Schichtobjekt enthält Daten zu den Start- und Endorten sowie den Start- und Endzeiten der Schicht sowie ein Array von Pausenobjekten, die jeweils die Start- und Endorte sowie die Start- und Endzeiten der Pausen enthalten. Es können mehrere Schichtobjekte definiert werden, diese dürfen sich jedoch nicht überschneiden. Elemente in jedem Schichtobjekt:
Die Startzeit und der Startort der Schicht.
time— optional. Gibt den Beginn der Schicht an. Wenn kein Wert angegeben wird, wird standardmäßig 00:00:00 (Mitternacht) des aktuellen Datums verwendet.location— optional. Die Geokoordinaten (Breiten- und Längengrad) des Startortes. Als Array angeben[A,B](A = Breitengrad, B = Längengrad) oder als{"lat": A,"lng": B}.
Die Endzeit und der Endort der Schicht.
time— optional. Gibt die Endzeit der Schicht an. Wenn kein Wert angegeben wird, wird standardmäßig 23:59:00 Uhr des aktuellen Datums verwendet.location— optional. Die Geokoordinaten des Endpunkts. Geben Sie diese wie folgt an:[A,B]oder{"lat": A,"lng": B}.
serviceWindow— erforderlich, wenn „breaks“ verwendet wird. Der Zeitraum, in dem die Unterbrechung auftreten kann.duration— erforderlich, wenn „breaks“ verwendet wird. Eine Ganzzahl, die die Dauer der Pause in Sekunden angibt.location— optional. Die Stelle des Bruchs, da[A,B]oder{"lat": A,"lng": B}. Wird der Ort nicht angegeben, handelt es sich um eine „flexible“ Pause, d. h., sie kann nach Belieben des Fahrers an einem beliebigen Ort eingelegt werden.
Beispiel — shifts
Ein Array von Kapazitätsobjekten. Jedes Kapazitätsobjekt ist ein Schlüssel-Wert-Objekt, das mit den folgenden Schlüsseln definiert ist:
name— erforderlich. Eine Zeichenfolge, die den Namen des Kapazitätstyps angibt (z. B. „Rollstuhl“, „Kiste“, „Sitzplatz“, „Abfallbehälter“).units— erforderlich. Eine Ganzzahl, die die verfügbaren Einheiten des Kapazitätstyps angibt.
Wenn ein Fahrzeug beispielsweise Platz für 2 Personen und 20 Pakete bietet, können Sie seine Kapazität wie folgt definieren:
Eine Liste von Fahrzeugfähigkeiten oder -ausstattungen, die jeweils durch eine für Ihre Anwendung spezifische beliebige Zeichenfolge dargestellt werden. Auf diese Weise können Sie die Fähigkeiten Ihrer Fahrzeuge an die Anforderungen der jeweiligen Einsätze anpassen. Beispiel: "skills": ["lift","fridge","oxygen tank"]
Gibt die für das Fahrzeug geltenden Einschränkungen an.
maxDistance— optional. Eine ganze Zahl, die die maximale Entfernungsbegrenzung für das Fahrzeug in Meilen angibt.maxStops— optional. Eine ganze Zahl, die die maximale Anzahl an Stopps (Abhol- oder Auslieferungsaufträge) angibt, die das Fahrzeug in einer Schicht abwickeln kann.lifoDepth— optional. Eine Ganzzahl, die die LIFO-Tiefe (Last In First Out) des Fahrzeugs angibt.
Gibt den letzten bekannten Standort des Fahrzeugs zum angegebenen Zeitpunkt an. Diese Information ist entscheidend für die Neuoptimierung einer laufenden Route, um neuen Änderungen wie Fahrzeugausfällen, verspäteten Aufträgen, neuen Aufträgen oder stornierten Aufträgen Rechnung zu tragen. Bei der Neuoptimierung eines bestehenden Fahrplans müssen Sie den Standort aller beteiligten Fahrzeuge angeben.
Eine eindeutige Kennung zur Definition einer Routenvorlage. Die API unterstützt das Konzept der „Routenvorlagen“, mit denen Sie die Spezifikationen für einen bestimmten Fahrzeugtyp festlegen und die API anweisen können, eine bestimmte Anzahl solcher Fahrzeuge zur Optimierung zu generieren. Eine Routenvorlage enthält dieselben Informationen wie eine Route oder ein Fahrzeug, Sie können jedoch einen „Größe“-Parameter angeben, der maxInstances dafür. Nehmen wir zum Beispiel an, Sie haben 100 Fahrzeuge. Sie könnten 2 oder 3 Routenvorlagen definieren:
- Schicht 6:00–18:00 Uhr, Kapazität 4, Größe = 60
- Schicht 13:00–01:00 Uhr, Kapazität 4, Größe = 50
- Schicht 6:00–20:00 Uhr, Kapazität 10, Größe = 35
Das bedeutet, dass die API bei Bedarf automatisch bis zu 60 Fahrzeuge mit Vorlage 1, 5 mit Vorlage 2 und 35 mit Vorlage 3 instanziieren kann.
Falls routeTemplateId wird bereitgestellt, maxInstances legt fest, wie viele Routenvorlagen auf der Grundlage der angegebenen Routenvorlage generiert werden sollen.
- Genau eins von
idoderrouteTemplateIdmuss verwendet werden, niemals beides. idundmaxInstanceskann nicht zusammen verwendet werden.- Wenn beide
routeTemplateIdundmaxInstancessind vorhanden, verwendet die API die Routenvorlagenmodell um Routen zu erstellen.
jobs
Jobs Mindestens eines erforderlich Ein Array von Job-Objekten. Jedes Job-Objekt verfügt über die folgenden Attribute:
Eine eindeutige Kennung für den Auftrag.
Ein Array von Task-Objekten, von denen jedes eine Abholaufgabe definiert.
Ein Array von Task-Objekten, von denen jedes eine Liefer- (oder Abgabe-)Aufgabe definiert.
- Die API unterstützt keine Aufträge mit mehreren Abholungen und mehreren Zustellungen.
- Die API unterstützt keine Aufträge ohne Abholung und ohne Zustellung.
- Wenn nur
pickupsWenn dies angegeben ist, wird der Auftrag als Auftrag mit Abholung. - Wenn nur
deliveriesWenn dies angegeben ist, wird der Auftrag als leistungsorientierte Stelle. - Wenn ein Auftrag sowohl eine Abholung als auch eine Zustellung umfasst, richtet sich der Anker nach der Aufgabe, für die ein Zeitfenster festgelegt wurde.
- Wenn beide Aufgaben Zeitfenster haben, wird der Auftrag als auf eine Abholung bezogener Auftrag behandelt.
Das Aufgabenobjekt
Jedes Aufgabenobjekt besteht aus den folgenden Attributen:
Eine eindeutige Kennung für die Aufgabe.
Ein Schlüssel-Wert-Objekt, das die Geokoordinaten (Breiten- und Längengrad) des Ortes angibt, an dem die Aufgabe ausgeführt werden soll. Als Array angeben [A,B] (A = Breitengrad, B = Längengrad) oder als {"lat": A,"lng": B}.
Gibt das Zeitfenster für die Ausführung der Aufgabe an (je nach Anwendungsfall erforderlich oder optional; siehe „Abholungen und Zustellungen“ oben). Das Zeitfenster ist ein Array der Form [A, B] wobei A und B die Start- und Endzeit sind. Die API versucht, eine voraussichtliche Ankunftszeit (ETA) innerhalb des angegebenen Zeitfensters zu ermitteln; ist dies nicht möglich, wird die Aufgabe als „nicht zugewiesen“ aufgeführt. Die Zeiten A und B legen den frühesten und spätesten Zeitpunkt fest, zu dem eine Aufgabe von einem Fahrzeug erledigt sein muss. Verwenden Sie für flexible oder nicht zeitkritische Aufgaben ein beliebig großes Zeitfenster (max. 24 Stunden), um der API mehr Flexibilität bei der Planung anderer Aufgaben zu geben. Die aktuelle Version der API unterstützt nur ein Zeitfenster pro Aufgabe. Für reine Abhol- und reine Zustellaufträge ist das Zeitfenster erforderlich.
Gibt die Dauer der Aufgabe in Sekunden an. Es kann sich dabei entweder um eine Ganzzahl oder um ein Schlüssel-Wert-Objekt mit den folgenden Schlüsseln handeln:
fixed— die festgelegte Dauer (in Sekunden) für den Vorgang (z. B. zum Suchen eines Parkplatzes, zum Herunterfahren des Aufzugs).service— die Dauer (in Sekunden) der Ausführung des Auftrags.
Eine Reihe von Kapazitätsanforderungen für die Aufgabe. Die Struktur jedes Anforderungsobjekts entspricht der des Kapazitätsobjekts in der Flottenentität. Jede Kapazitätsposition besteht aus einem name (Zeichenkette) und deren units (Ganzzahl). Die angegebenen Namen müssen mit denen übereinstimmen, die im Kapazitätsobjekt der Flottenentität definiert sind. Wenn ein Auftrag beispielsweise Kapazität für zwei Plätze und 20 Pakete benötigt:
Eine Reihe von Fähigkeiten oder Ausrüstungsgegenständen, die zur Ausführung der Aufgabe erforderlich sind und jeweils durch eine willkürliche, anwendungsspezifische Zeichenfolge dargestellt werden. Nur Fahrzeuge, deren Fähigkeiten mit den für die Aufgabe erforderlichen Fähigkeiten übereinstimmen, kommen für die Ausführung der Aufgabe in Betracht. Diese Fähigkeiten werden mit den in der Flottenentität definierten Fähigkeiten abgeglichen. Beispiel: "skills": ["lift", "ladder", "welding machine"]
Eine Zeichenfolge, die den Status der Aufgabe angibt: pending, in_progressoder performed. Dies ist entscheidend für die Neuoptimierung einer laufenden Route. Bei neuen oder noch nicht ausgeführten Aufgaben setzen Sie den Wert auf pending. Wenn die Aufgabe bereits erledigt ist, setze sie auf performed. Wenn das Fahrzeug bereits am Standort angekommen ist und der Auftrag bereits läuft, stellen Sie es auf in_progress. Der Standardwert ist pending. Beispiel: "status": "pending"
Gibt die zugewiesene Fahrzeug-ID für bereits geplante Aufgaben an. Dies ist entscheidend für die Neuoptimierung einer laufenden Route. Der Standardwert ist Null. Setzen Sie diesen Wert für neue Aufgaben auf Null. Setzen Sie dieses Attribut für bestehende Aufgaben, die bereits einem Fahrzeug zugewiesen sind, auf die zugewiesene Fahrzeug-ID. Beispiel: "vehicleId": 12
Gibt die aktuelle ETA (voraussichtliche Ankunftszeit) für bereits geplante Aufträge an. Dies ist entscheidend für die Neuoptimierung einer laufenden Route. Der Standardwert ist 0. Setzen Sie den Wert für neue oder bereits ausgeführte Aufgaben auf 0; für bestehende, noch ausstehende Aufgaben setzen Sie ihn auf die aktuelle ETA. Beispiel: "eta": "2021-07-04T12:13:00-08:00"
objective
Ziel Ganzzahl Optional Legt das Optimierungsziel (die Strategie) fest. Der Standardwert ist 1.
| Wert | Strategie |
|---|---|
1 | Gesamtfahrzeit minimieren (Standard) |
2 | Anzahl der Routen minimieren |
3 | Ausgleich der Auslastung auf den verschiedenen Strecken |
Beispiel: "objective": 1
configuration
Konfiguration ( optional ) Dient zur Angabe zusätzlicher Einstellungen oder Konfigurationen.
Legt den Typ der ausgegebenen Polylinie fest, die für jede geplante Route zurückgegeben wird. Eine der folgenden Optionen: none, plain, encoded. Wenn none, sind keine Polylinien enthalten. Wenn plainwird eine geordnete Liste der Kreuzungen zurückgegeben, die zwischen jedem Paar aufeinanderfolgender Haltestellen zu passieren sind. Wenn encodedwird die Polylinie in ein Zeichenfolgenformat komprimiert, das Sie an Navigations-APIs von Drittanbietern wie Google Maps übermitteln können, um detaillierte Wegbeschreibungen zu erhalten. Der Standardwert ist none.
Ein Flag, das festlegt, ob nicht zugewiesene Aufgaben in die Antwortausgabe aufgenommen werden sollen. Der Standardwert ist False. Sollte die API aus irgendeinem Grund eine Aufgabe keiner Route zuweisen können, wird sie als „nicht zugewiesen“ aufgeführt.
Ein Flag, das festlegt, ob die Optimierungsstatistiken in die Ausgabelösung aufgenommen werden sollen. Der Standardwert ist True.
Legt die Einheiten für die Ausgabestatistiken und die Flottengrenzen fest. Entweder metric oder imperial. Der Standardwert ist metric.
Legt die maximale Verweildauer für alle Aufträge fest. Diese wird durch eine statische Tabelle definiert, in der jede Zeile ein Array mit drei Zeitwerten (in Minuten) enthält: [A, B, C]. Das bedeutet: Wenn die reine Fahrzeit für einen Auftrag zwischen A und B liegt, entspricht die maximale Zeit an Bord der Summe aus „Fahrtzeit + C“. Hier ein Beispiel einer einfachen Tabelle mit zwei Zeilen: "maxRideTable":[[0, 10, 30], [11, 20, 40]]. Standard ist [[0, 300, 720]]. In dieser Tabelle sind Überschneidungen und Lücken nicht zulässig, und die Zeitangaben erfolgen in Minuten.
Legt fest, wie die Optimierungs-Engine bei einer erneuten Optimierung mit zuvor zugewiesenen Aufträgen umgeht. Die Standardeinstellung ist false.
Wenn eingestellt auf trueAlle Aufträge, die in der Neuoptimierungs-Nutzlast bereits einem Fahrzeug zugewiesen wurden, gelten als gesperrt und müssen auf ihrem aktuellen Fahrzeug verbleiben. Der Motor optimiert und weist nur neue Aufträge zu, denen noch kein Fahrzeug zugewiesen wurde.
Wenn eingestellt auf false… darf die Engine bei einer Neuoptimierung bestehende Zuweisungen ändern. Zuvor zugewiesene Aufträge können von ihrem ursprünglichen Fahrzeug entfernt werden, wenn die Zuweisung nicht mehr gültig oder optimal ist. So kann beispielsweise ein Auftrag, der ursprünglich für 8:00 Uhr eingeplant war, bei einer Neuoptimierung um 10:00 Uhr entfernt werden, da die Aufgabe nicht mehr innerhalb der vorgegebenen Rahmenbedingungen erledigt werden kann.
Fahrzeugkapazitätsdefinitionen können benannt und anschließend im Flottenbereich verwendet werden. Dies ist besonders nützlich bei komplexen Definitionen, wenn ein Fahrzeug viele verschiedene Konfigurationen haben kann. Wenn ein Fahrzeug beispielsweise entweder (10 gehfähige und 0 Rollstuhlfahrer) ODER (8 gehfähige und 1 Rollstuhlfahrer) befördern kann, könnten Sie Folgendes definieren: "vehicleCapacities":{"flexBus": [[{"name": "ambulatory", "units": 10}], [{"name": "ambulatory", "units": 8},{"name":"wheelchair", "units": 1}]]}. In den Flotteneigenschaften kannst du dann fleet[<index>].capacities: "flexBus" für jeden FlexBus in der Flotte. Benannte Fahrzeugkapazitäten können auch in Ihrem persönlichen Kundenprofil gespeichert werden, wo sie zur Verwendung bereitstehen, ohne dass Sie sie im Konfigurationsbereich neu definieren müssen. Wenn eine benannte Fahrzeugkapazität sowohl in Ihrem persönlichen Profil als auch in der Nutzlast vorhanden ist, hat die Definition in der Nutzlast Vorrang.
Die Dauer des „Freeze Window“ in Minuten. Ein „Freeze Window“ ist ein Konzept, das nur bei der Optimierung am selben Tag zur Anwendung kommt und bei der erneuten Optimierung eines Problems nützlich ist. Wenn Sie beispielsweise ein Problem bereits optimiert haben, aber im Laufe des Tages Änderungen vornehmen möchten, könnten Sie das Problem erneut senden (mit entsprechenden task.status (um bereits durchgeführte Schritte zu berücksichtigen) und ein Sperrfenster von 60 Minuten festlegen. Dadurch wird dem Optimierer mitgeteilt, dass der Zeitraum von 60 Minuten ab dem aktuellen Zeitpunkt tabu ist: Innerhalb des Sperrfensters dürfen keine Aufgaben zu einer Route hinzugefügt oder von dieser entfernt werden.
Eine Reihe von Kapazitätstypen, für die die LIFO-Regel (Last In, First Out) gilt. Beispiel: "lifoConstrainedCapacities": ['wheelchair', 'scooter']
Beispiel — configuration
version
Version Optional Gibt die Version der API an. Der Standardwert ist 1.0.
Um verschiedene Beispiele für ein Problem und erfahren Sie, wie Sie die API in verschiedenen Anwendungsfällen (z. B. bei der Neuoptimierung) nutzen können, siehe Anleitungen.
1. Eindeutige Kennungen. Alle Aufträge müssen über eine eindeutige ID verfügen. Alle Aufgaben müssen über eine eindeutige ID verfügen. Alle Fahrzeuge müssen über eine eindeutige ID verfügen. Ein Auftrag kann dieselbe ID wie eine Aufgabe oder ein Fahrzeug haben – dies ist zulässig.
2. Zeitliche Einschränkungen. Jede Aufgabe kann mehrere zeitbezogene Elemente enthalten, wie beispielsweise Zeitfenster für Dienstleistungen und Fahrzeugschichten. Die API ermittelt den kleinsten Wert aus allen Angaben. Wenn das Minimum beispielsweise 2024-09-18T04:32:00-08:00… wird der Maximalwert berechnet, indem man den Zeitpunkt um Mitternacht an dem Tag ermittelt, an dem das Minimum auftritt, und zu diesem Zeitstempel 33 Stunden hinzuzählt. In diesem Beispiel beträgt die maximal zulässige Zeit also 2024-09-19T09:00:00-08:00. Wenn eine beliebige Zeitspanne im Problem (z. B. Fahrzeugwechsel oder Aufgabenfenster) diesen Wert überschreitet, gibt die API einen 400 Fehler.
Das Solution-Objekt #
Sobald Sie ein Problem über die POST-Methode übermittelt haben, erhalten Sie eine eindeutige Referenz-ID. Verwenden Sie diese Referenz-ID mit der GET-Methode, um den Status des übermittelten Problems abzurufen. Sobald die Optimierungslösung fertig ist, können Sie darauf zugreifen in der solution Inhalt der Antwort. Wie in der folgenden Abbildung dargestellt, ist die solution Die Einheit besteht aus drei Hauptteilen:
Enthält verschiedene Kennzahlen, die einen Überblick über die gesamte Lösung für alle Routen bieten und es Ihnen ermöglichen, deren Wirksamkeit zu bewerten (zum Beispiel die Gesamtfahrstrecke aller optimierten Routen). Durch die Analyse dieser Statistiken können Sie die Qualität und Effizienz der erarbeiteten Lösung messen.
Enthält die optimierten Routen samt ihren Haltestellen und voraussichtlichen Ankunftszeiten (ETA). Außerdem kann die Polylinie jeder Route enthalten sein.
Enthält die Liste der nicht zugewiesenen Aufgaben. Wenn die API eine Aufgabe während der Optimierung keiner Route zuweisen kann, wird sie als nicht zugewiesen aufgeführt. Die Liste kann Gründe dafür enthalten, warum die jeweilige Aufgabe nicht zugewiesen wurde, und gibt Aufschluss über die Einschränkungen oder Probleme, die einer Zuweisung im Wege standen.
Schema der Ausgabelösung #
Die Vorlage der Lösung, die in der Antwort der API bereitgestellt wird, sieht wie folgt aus:
Die solution Die Entität stellt die Lösung des Routenoptimierungsproblems dar und besteht aus den nachfolgend beschriebenen Attributen.
statistics
Enthält die Statistiken der gesamten Lösung. Sie umfasst die folgenden Eigenschaften:
totalDistance— die Gesamtstrecke, die die gesamte Flotte zurückgelegt hat, einschließlich der Strecke vom Startort jedes Fahrzeugs bis zu seinem Zielort.revenueDistance— die gesamte zurückgelegte Strecke der gesamten Flotte, einschließlich der Strecke vom ersten bis zum letzten Halt für jedes Fahrzeug. Nicht enthalten sind die Strecke vom Startort des Fahrzeugs zum ersten Halt sowie die Strecke vom letzten Halt zum Endort des Fahrzeugs.
used— die Anzahl der in der Lösung eingesetzten Fahrzeuge zur Ausführung der geplanten Aufträge/Aufgaben.unused— die Anzahl der ungenutzten Fahrzeuge.
scheduledTasks— die Anzahl der geplanten Aufgaben.unassignedTasks— die Anzahl der noch nicht zugewiesenen Aufgaben.
totalHours— die Gesamtfahrzeit der gesamten Flotte, einschließlich der Zeit, die für die Fahrt vom Startort jedes Fahrzeugs zum Zielort benötigt wird.revenueHours— die Gesamtzahl der Fahrstunden der gesamten Flotte, einschließlich der Zeit, die jedes Fahrzeug vom ersten bis zum letzten Halt benötigt. Nicht enthalten ist die Zeit für die Fahrt vom Startort des Fahrzeugs zum ersten Halt oder vom letzten Halt zum Endort des Fahrzeugs.
Beispiel — statistics
routes
Liefert ein Array mit den geplanten Routen für jedes Fahrzeug. Jede geplante Route enthält:
Die Kennung des zugewiesenen Fahrzeugs.
Ein Array von Schichtobjekten. Die API unterstützt mehrere Schichten pro Fahrzeug. Jedes Schichtobjekt besteht aus:
index— der Index der Verschiebung (Ganzzahl).stops— eine Liste aller Haltestellen, die das Fahrzeug in dieser Schicht anfahren wird.
Jede Haltestelle weist folgende Eigenschaften auf:
ordinal— die Position der Haltestelle im Fahrplan, dargestellt durch ihren Index (Ganzzahl).jobId— die zu diesem Stopp gehörende Auftrags-ID (Ganzzahl).taskId— die zu diesem Stopp gehörende Aufgaben-ID (Ganzzahl).type— die Art der an dieser Haltestelle auszuführenden Aufgabe („Abholung“ oder „Zustellung“).location— die Geokoordinaten des Standorts der Haltestelle.eta— die voraussichtliche Ankunftszeit am Haltepunkt (in derselben Zeitzone wie die eingegebene Nutzlast).timeToNext— die Fahrzeit bis zur nächsten Haltestelle. Wenn Sie beispielsweise um 9:00 Uhr einen Fahrgast absetzen und Ihr nächster Auftrag um 10:00 Uhr ist, bedeutet dies, dass die Fahrzeit von der aktuellen Haltestelle zur nächsten Haltestelle 20 Minuten beträgt.distanceToNext— die Entfernung zur nächsten Haltestelle. Je nach den in der Konfiguration gewählten Einheiten kann dies Meilen oder Meter sein.waitTime— wie lange der Fahrer an der nächsten Haltestelle warten müsste, wenn er jetzt losfährt.polyline— die Polylinie, die die Haltestelle mit der vorhergehenden Haltestelle verbindet. Wenn in der Konfiguration „plain“ angegeben ist, handelt es sich bei der Polylinie um eine geordnete Liste von Kreuzungen, die zwischen der vorhergehenden und der aktuellen Haltestelle zu passieren sind. Wenn „encoded“ angegeben ist, wird die einfache Polylinie kodiert und als kodierte Zeichenfolge zurückgegeben.break— Wenn der geplante Stopp eine Pause darstellt, gibt er die ID der Pause an. Andere Stopps enthalten dieses Element nicht. Die API schreibt nicht vor, dass Pausen (oder Aufträge) in chronologischer Reihenfolge aufgeführt werden müssen.
Beispiel — routes
unassigned
Die optionale Liste der nicht zugewiesenen Aufgaben enthält Aufgaben, die aufgrund bestimmter Einschränkungen nicht zugewiesen werden können. Jeder Eintrag besteht aus einer Auftrags-ID, einer Aufgaben-ID und möglichen Gründen für die Nichtzuweisung (ein Code sowie eine Beschreibung):
job— die Job-ID (Ganzzahl) der noch nicht zugewiesenen Aufgabe.task— die ID (Ganzzahl) der noch nicht zugewiesenen Aufgabe.
Eine Reihe möglicher Gründe für die nicht zugewiesenen Aufgaben.
code— der Code (Ganzzahl) des möglichen Grundes.description— die Beschreibung (Zeichenkette) des möglichen Grundes.
Fehler und Statuscodes #
Wie im Abschnitt „Erste Schritte“ beschrieben, unterstützt die API sowohl die POST- als auch die GET-Methode. Je nach Methode gibt sie in der Antwort einen Statuscode zurück. Nachfolgend finden Sie die Beschreibungen der Statuscodes für diese beiden Methoden.
POST-Statuscodes
| Code | Beschreibung | Weitere Hinweise |
|---|---|---|
| 202 | Der Antrag wurde zur Bearbeitung angenommen. | Es wird eine Referenz-ID zurückgegeben, mit der die Lösung mittels einer GET-Anfrage abgerufen werden kann, sobald sie fertig ist. |
| 400 | Die Eingabevalidierung ist fehlgeschlagen (Ungültige Anfrage). | Ein oder mehrere Parameter fehlen, sind ungültig oder wurden falsch eingegeben. Bitte korrigieren Sie die Eingabedaten und senden Sie die Anfrage erneut. |
| 403 | Ungültige Anmeldedaten oder unzureichende Berechtigungen. | Die Anfrage wurde verstanden, aber der Client ist aufgrund fehlender oder falscher Berechtigungen nicht autorisiert. |
| 404 | Der angeforderte Pfad wurde nicht gefunden. | Dieser Fehler tritt auf, wenn der angeforderte URL-Pfad keinem gültigen Endpunkt entspricht. |
| 429 | Zu viele Anfragen. | Die QPM-Quote (Anfragen pro Minute) oder die Anfragequote wurde überschritten. Der Client muss die Häufigkeit der Anfragen verringern. |
| 500 | Interner Dienstfehler. | Es gab ein serverseitiges Problem mit der API. Wenden Sie sich bitte an support@ddswireless.com, um Unterstützung zu erhalten. |
GET-Statuscodes
| Code | Beschreibung | Weitere Hinweise |
|---|---|---|
| 200 | Die Anfrage war erfolgreich. | Das Problem wurde erfolgreich gelöst. Die Ergebnisse werden über statistics, routesund unassigned. |
| 202 | Die Anfrage wurde angenommen, ist jedoch noch nicht abgeschlossen (Status: „In Bearbeitung“). | Die Lösung ist noch nicht verfügbar. Bitte schauen Sie später noch einmal vorbei. |
| 400 | Die Anfrage konnte nicht verarbeitet werden (Ungültige Anfrage). | Für die angegebenen Standorte oder Parameter konnte keine realisierbare Lösung ermittelt werden. |
| 401 | Unzulässige Anfrage. | Für diese Anfrage ist eine Benutzerauthentifizierung erforderlich. Der Server hat keine gültigen Anmeldedaten erhalten. |
| 500 | Interner Dienstfehler. | Es gab ein Problem auf der Serverseite mit unserer API. Bitte wenden Sie sich an support@ddswireless.com. Die Felder statistics, routesund unassigned wird leer sein. |
Anleitungen / Tutorials #
Hier finden Sie verschiedene Beispiele, die die Verwendung der API veranschaulichen. Die API unterstützt in erster Linie zwei Hauptanwendungsfälle:
- Planung und Terminierung – erstellt einen optimierten Fahrplan für die Touren einer Flotte unter Berücksichtigung von auftrags- und fahrzeugspezifischen Einschränkungen.
- Neuoptimierung – passt einen bestehenden oder laufenden Fahrplan an, um Änderungen wie neue Aufträge, Stornierungen oder Fahrzeugausfälle zu berücksichtigen.
Sehen Sie sich die folgenden Beispiele an, um zu erfahren, wie diese Anwendungsfälle umgesetzt werden:
- Beispiel 1 – Planung eines einfachen Abhol- und Zustellungsszenarios.
- Beispiel 2 – Ein einfaches Szenario zur Neuoptimierung, bei dem neue Aufträge in einen bestehenden Zeitplan eingefügt werden.
- Beispiel 3 – Neuoptimierung bei stornierten Aufträgen.
- Beispiel 4 – Neuoptimierung mit defekten Fahrzeugen.
Die in den folgenden Beispielen genannten Orte sind fiktiv und zufällig generiert und entsprechen keinen realen Orten.
Planung eines einfachen Abhol- und Lieferszenarios
Eine Flotte von zwei Fahrzeugen, die drei Abhol- und Lieferaufträge ausführt, optimiert zur Minimierung der Gesamtfahrzeit.
In diesem Beispiel besteht unsere Flotte aus zwei Fahrzeugen, und wir haben drei Abhol- und Lieferaufträge, die von diesen beiden Fahrzeugen erledigt werden müssen. Hier sind die Details zu den einzelnen Fahrzeugen:
Fahrzeug 1
- Schichtdetails: Die Schicht beginnt am 01.10.2024 um 8:00 Uhr PST am Standort (50.67293, -120.34195) und endet um 18:00 Uhr am selben Standort. Die Zeitzone ist PST, daher wird die Startzeit wie folgt erfasst:
2024-10-01T08:00:00-08:00und die Endzeit als2024-10-01T18:00:00-08:00. - Pausen: Zwei Pausen von jeweils 15 Minuten. Erste Pause zwischen 10:00 Uhr und 10:30 Uhr am Standort (50.6531, -120.38393); zweite Pause zwischen 14:00 Uhr und 14:30 Uhr am Standort (50.6531, -120.38393).
- Kapazität: 15 Sitzplätze und 5 Gepäckplätze.
- Ausstattung: Mit Aufzug und Klimaanlage ausgestattet.
Fahrzeug 2
- Schichtdetails: Die Schicht beginnt am 01.10.2024 um 8:00 Uhr PST am Standort (50.7117, -120.39286) und endet um 18:00 Uhr am Standort (50.67698, -120.32012).
- Pausen: Eine 15-minütige Pause zwischen 11:00 Uhr und 11:30 Uhr am Standort (50.6531, -120.38393).
- Kapazität: 10 Sitzplätze und 8 Gepäckstücke.
- Ausstattung: Nur mit Aufzug.
Außerdem haben wir drei „Abhol- und Lieferaufträge“ in Kamloops, BC, Kanada. Hier sind die Einzelheiten zu den einzelnen Aufträgen:
Stelle 1
- Abholung: Standort (50.65391, -120.37365). Zeitfenster: 9:00 bis 9:30 Uhr (der Auftrag ist an die Abholung gebunden; die Abholung muss innerhalb dieses Zeitfensters erfolgen). Dauer: 10 Minuten. Anforderungen: 1 Sitzplatz, 2 Ladegut, Fahrzeug mit Hebevorrichtung.
- Lieferort: Standort (50.69409, -120.35425). Dauer: 5 Minuten.
Hiob 2
- Abholort: Standort (50.70816, -120.37796). Dauer: 5 Minuten. Voraussetzungen: 1 Sitzplatz, Fahrzeug mit Hebevorrichtung und Klimaanlage.
- Lieferung: Standort (50.66559, -120.36924). Zeitfenster: 12:45 Uhr bis 13:30 Uhr (der Auftrag ist an die Lieferung gebunden, die innerhalb dieses Zeitfensters erfolgen muss). Dauer: 5 Minuten.
Hiob 3
- Abholung: Standort (50.70393, -120.37263). Zeitfenster: 14:00 bis 14:30 Uhr (der Auftrag ist an die Abholung gebunden). Dauer: 10 Minuten. Anforderungen: 1 Sitzplatz, 3 Frachtstücke, keine spezielle Ausrüstung erforderlich.
- Lieferort: Standort (50.69028, -120.39028). Dauer: 5 Minuten.
Unser Ziel ist es, diese Aufträge den definierten Fahrzeugen so zuzuweisen, dass die Gesamtfahrzeit minimiert wird. Mit anderen Worten: Unser Optimierungsziel ist gleich 1. Die Ausgangsformulierung lautet wie folgt:
Eingabeproblem (Nutzlast)
Nachdem wir dieses Problem mit der POST-Methode übermittelt haben (wie unter „Erste Schritte“ beschrieben), erhalten wir mit der GET-Methode folgende Lösung:
Ausgabe
Neue Aufträge zu einem bestehenden Zeitplan hinzufügen
Einen teilweise ausgeführten Zeitplan um 11:36:34 Uhr neu optimieren, um einen neu eingegangenen Auftrag einzubeziehen.
Betrachten wir nun das vorherige Beispiel. Nehmen wir an, Sie haben seit dem Morgen mit der Ausführung des erstellten Zeitplans begonnen, und es ist jetzt 11:36:34 Uhr, und Sie erhalten folgenden neuen Arbeitsauftrag:
Auftrag 4 (ein neuer Auftrag)
- Abholung: Standort (50.65187, -120.40052). Zeitfenster 15:45 bis 16:15 Uhr (ein an der Abholung gebundener Auftrag). Dauer 15 Minuten. Anforderungen: 1 Sitzplatz, 1 Ladung.
- Lieferort: Standort (50.69262, -120.35412). Dauer: 10 Minuten.
Auftrag 1 haben Sie bereits ausgeführt, Auftrag 2 und Auftrag 3 sind jedoch noch in Bearbeitung. Die Details lauten wie folgt:
- Aufgabe 1: erledigt.
- Auftrag 2: in Bearbeitung. Abholung – aktuelles Fahrzeug-ID 1, voraussichtliche Ankunftszeit 10:30 Uhr. Zustellung – aktuelles Fahrzeug-ID 1, voraussichtliche Ankunftszeit 12:45 Uhr.
- Auftrag 3: in Bearbeitung. Abholung – aktuelles Fahrzeug-ID 2, voraussichtliche Ankunftszeit 14:00 Uhr. Zustellung – aktuelles Fahrzeug-ID 2, voraussichtliche Ankunftszeit 14:29 Uhr.
Da Auftrag 2 und Auftrag 3 derzeit in Bearbeitung sind, sind ihnen eine Fahrzeug-ID und eine voraussichtliche Ankunftszeit zugeordnet. Um Ihren Zeitplan neu zu optimieren und den neuen Auftrag (Auftrag 4) einzubeziehen, übermitteln Sie bitte über die API eine aktualisierte Ansicht Ihres aktuellen Zeitplans. Diese enthält folgende Details zu Ihren Aufträgen:
- Aufgabe 1: bereits ausgeführt, also setze den Status der Abhol- und Zustellaufgaben auf
"status":"performed". Für diese Aufgaben müssen Sie die aktuelle Fahrzeug-ID und die voraussichtliche Ankunftszeit nicht angeben, da diese bereits erfasst wurden und nicht mehr geändert werden können. - Hiob 2: noch in Bearbeitung und Fahrzeug 1 zugewiesen, mit voraussichtlicher Abholzeit um 10:30 Uhr und voraussichtlicher Lieferzeit um 12:45 Uhr. Enthalten
"status": "in_progress","vehicleId": 1und die dazugehörigeetafür seine Abhol- und Lieferaufgaben. - Hiob 3: noch in Bearbeitung und Fahrzeug 2 zugewiesen, mit voraussichtlicher Abholzeit um 14:00 Uhr und voraussichtlicher Lieferzeit um 14:29 Uhr. Enthalten
"status": "in_progress","vehicleId": 2und die dazugehörigeetafür seine Abhol- und Lieferaufgaben. - Hiob 4: ein neuer Auftrag, noch nicht terminiert, also den Status auf
"status":"pending". Sie müssen keine Fahrzeug-ID oder Ankunftszeit angeben. Nach der Neuoptimierung erhalten Sie für jeden Auftrag dieses Jobs eine Fahrzeug-ID und eine Ankunftszeit.
Sie müssen außerdem die zuletzt bekannten Standorte Ihrer Fahrzeuge angeben, damit die API einen aktuellen Überblick über Ihren aktuellen Fahrplan hat. Angenommen, die zuletzt bekannten Standorte um 11:36:34 Uhr (dem Zeitpunkt, zu dem wir die Neuoptimierung durchführen möchten) lauten: Fahrzeug 1: (50,66692, -120,35293) und Fahrzeug 2: (50.65324, -120.37398). Fügen Sie eine lastKnownLocation Objekt mit dem Standort und time für jedes Fahrzeug.
Um eine erneute Optimierung durchzuführen, können Sie Ihr neues Optimierungsproblem nun wie folgt einreichen:
Neuoptimierung der Nutzlast
Neuoptimierung unter Berücksichtigung stornierter Aufträge
Entfernen Sie stornierte Aufträge aus einem bestehenden Zeitplan und optimieren Sie die verbleibenden Aufträge neu.
Wenn Sie ein Optimierungsproblem für eine Reihe von Aufträgen eingereicht haben und bereits über einen Zeitplan verfügen, einige Aufträge jedoch storniert wurden, können Sie Ihren Zeitplan neu optimieren, indem Sie die stornierten Aufträge aus dem Problem entfernen. Dazu müssen Sie Folgendes tun:
- Geben Sie einen aktuellen Überblick über Ihre noch ausstehenden Aufträge und die letzten bekannten Standorte Ihrer Fahrzeuge, ähnlich wie in Beispiel 2.
- Erstellen Sie eine überarbeitete Aufgabenstellung, die diese Änderungen berücksichtigt, und reichen Sie sie ein.
Nach dem Absenden erhalten Sie einen neuen Zeitplan, der die aktualisierten Aufträge und den aktuellen Flottenstatus berücksichtigt.
Neuoptimierung bei defekten Fahrzeugen
Die Aufgaben eines Fahrzeugs, das während der Schicht eine Panne hatte, neu zuweisen.
Angenommen, es ist 8:00 Uhr morgens und Sie nutzen die API, um einen optimierten Fahrplan für Ihre Aufträge mit 10 Fahrzeugen zu erstellen. Sie beginnen mit der Ausführung des Fahrplans, doch um 9:14 Uhr erfahren Sie, dass eines Ihrer Fahrzeuge eine Panne hat und die ihm zugewiesenen Aufträge nicht mehr ausführen kann. Um den Fahrplan neu zu optimieren, gehen Sie wie folgt vor:
- Aktualisiere die Flotteninformationen. Entferne das defekte Fahrzeug aus deinem Flottenobjekt.
- Geben Sie die Standorte der Fahrzeuge an. Geben Sie die letzten bekannten Standorte der verbleibenden Fahrzeuge an, ähnlich wie in Beispiel 2.
- Aufgabenstatus aktualisieren. Geben Sie den Status aller Aufgaben an: Geben Sie an, welche Aufgaben bereits erledigt sind, welche gerade bearbeitet werden und welche neu oder noch ausstehend sind. Geben Sie bei laufenden Aufgaben die zugehörige Fahrzeug-ID und die voraussichtliche Ankunftszeit an.
- Kümmere dich um das defekte Fahrzeug. Ändern Sie den Status aller Aufgaben, die zuvor dem defekten Fahrzeug zugewiesen waren, in
"pending"Dadurch kann die API sie anderen verfügbaren Fahrzeugen zuweisen und ihre voraussichtlichen Ankunftszeiten neu berechnen. - Zur erneuten Optimierung übermitteln. Übermitteln Sie das aktualisierte Problem an die API, um eine neue Terminoptimierung durchzuführen.
So testen Sie geplante Routen #
Schritt 1 – Erstellen Sie einen Zugriffstoken
Senden Sie zunächst eine POST-Anfrage an die folgende URL, um unter Verwendung der unten angegebenen Anmeldedaten einen Zugriffstoken abzurufen.
POST-Anfrage-Body für Vancouver (Mieter 2):
POST-Anfrage-Body für Finnland (Mandant 3):
Kopieren Sie anschließend das generierte Token. Hier ist ein Screenshot dieses Schritts:
Schritt 2 – Senden Sie eine Eingabedatenlast (Optimierungsproblem) an die API
Um eine Eingabedatenlast an die API zu senden und eine Referenz-ID zu erhalten, fügen Sie das generierte Token in den Abschnitt „Authorization“ der folgenden POST-Anfrage ein und die Eingabedatenlast in den Abschnitt „Body“ der Anfrage.
Ein Beispiel für eine Eingabe-Nutzlast:
Wenn die POST-Methode erfolgreich ist, erhalten Sie eine Referenz-ID, mit der Sie die Antwort über die GET-Methode abrufen können. Unten sehen Sie einen Screenshot dieses Schritts:
Schritt 3 – Rufen Sie die Antwort des API-Aufrufs ab
Um die Antwort unter Verwendung der empfangenen Referenz-ID abzurufen, fügen Sie das Zugriffstoken in den Abschnitt „Authorization“ der folgenden GET-Anfrage ein und nehmen Sie die Referenz-ID in die URL auf.
Hier ist ein Screenshot dieses Schritts:
Glossar #
| Begriff | Definition |
|---|---|
problem | Ein Problem der Routen- und Terminierungsoptimierung, das von der API gelöst werden soll. |
solution | Die von der API bereitgestellte Lösung für das Problem der Routen- und Terminierungsoptimierung. |
fleet | Eine Flotte umfasst eine Liste von Fahrzeugtypen und deren Angaben. |
job | Eine Liste von Liefer- oder Abhol- und Lieferaufträgen, die von einem bestimmten Fahrzeug ausgeführt werden müssen. |
task | Eine Aufgabe ist Teil eines Auftrags und muss an einem bestimmten Ort und zu einer bestimmten Zeit ausgeführt werden. |
break | Ein Attribut zur Festlegung einer oder mehrerer Pausen für Fahrer an bestimmten Standorten. |
demand | Anforderung an die Aufnahmekapazität, ausgedrückt in mehrdimensionalen Einheiten (z. B. Volumen, Masse). |
duration | Die Zeit, die für die Erledigung einer Aufgabe oder für eine Pause aufgewendet wird. |
shifts | Legt die Fahrpläne fest, einschließlich Start- und Endzeiten, Standorte und eventueller Pausen. |
delivery | Eine Aufgabe zur Auslieferung von Waren, die zuvor im Rahmen der Tour geladen wurden. |
pickup and delivery | Ein Auftrag, bei dem sowohl der Abhol- als auch der Lieferort angegeben sind. |
skills | Für bestimmte Aufgaben erforderliche Fahrzeugmerkmale (z. B. Ausstattung, Größenanforderungen). |
service window | Ein Zeitraum, innerhalb dessen eine Aufgabe erledigt werden muss. |
start/end location | Wo ein Fahrzeug abfährt oder zurückkehrt (z. B. Depot oder Garage). |
start/end time | Legt den Zeitplan für Schichten, Pausen, Abgänge oder Aufgaben fest. |
location | Die Breiten- und Längengrade einer Adresse im WGS84-Format. |
re-optimization | Aktualisierung eines laufenden Zeitplans aufgrund von Änderungen wie neuen oder stornierten Aufträgen. |
ID (or id) | Eine eindeutige Kennung für einen Auftrag, eine Aufgabe oder ein Fahrzeug. |
VRP | Das Fahrzeug-Routing-Problem. |
CVRP | Das Routenplanungsproblem für Fahrzeuge mit begrenzter Kapazität. |
PDP | Problem bei Abholung und Lieferung. |
limits | Für einen Fahrzeugtyp geltende Auflagen. |
objective | Die zur Lösung des Problems verwendete Optimierungsstrategie. |
statistics | Statistiken zu den optimierten Routen, die in der Lösung zurückgegeben werden. |
stop | Eine Liste der Aktivitäten, die zu einer bestimmten Zeit an einem bestimmten Ort entlang einer Route durchgeführt werden. |
unassigned jobs/tasks | Aufträge/Aufgaben, die keiner Route zugewiesen werden konnten. |
ETA | Voraussichtliche Ankunftszeit. Wird für alle Haltestellen in der Ausgabe angegeben. |
polyline | Eine durchgehende Linienführung, die eine Route auf der Karte darstellt. |
encoded polyline | Eine komprimierte Zeichenfolgenversion einer Polylinie, die zur Minimierung der Datengröße verwendet wird (z. B. _kv~uF|y~wGdkZ~gAx|]t@). |
FAQ Nr.
| Frage | Antwort |
|---|---|
| Unterstützt die API die Lösung des Abhol- und Zustellungsproblems (PDP)? | Ja, eine ausführliche Erklärung findest du im Abschnitt „Tutorials “. |
| Unterstützt die API Open PDP? | Ja, Sie können für jedes Fahrzeug in Ihrer Flotte beliebige Start- und Zielorte festlegen. |
| Verwendet die API Echtzeit-Verkehrsdaten? | Ja, es nutzt sowohl historische als auch Echtzeit-Verkehrsdaten. |
| Kann ich die Schichtzeiten, Start- und Endorte sowie Pausen festlegen? | Ja, siehe das Flottenobjekt auf der Problemseite. |
| Können wir mehrere beliebige Kapazitätstypen für Fahrzeuge definieren? | Ja, die capacity Das Attribut im Flottenobjekt unterstützt mehrere Dimensionen wie Gewicht, Volumen und Menge. |
| Können wir die maximale Anzahl an Aufgaben pro Fahrzeug festlegen? | Ja, dies kann über das Flottenobjekt auf der Seite „Problem“ festgelegt werden. |
| Unterstützt die API mehrere Pausen pro Fahrzeug? | Ja, dies wird über das Flottenobjekt auf der Seite „Problem“ unterstützt. |
| Unterstützt die API Abholungen, Lieferungen oder beides? | Ja, siehe das „jobs“-Objekt in der Problem- Dokumentation. |
| Kann ich die Dauer einer Aufgabe festlegen? | Ja, verwenden Sie das Attribut „duration“ im Objekt „jobs“ des Problems. |
| Kann ich beliebige Kapazitätsanforderungen für Aufgaben festlegen? | Ja, dies wird über das „jobs“-Objekt in der Problemdefinition unterstützt. |
| Können wir für jede Aufgabe ein Zeitfenster für die Erledigung festlegen? | Ja, geben Sie die früheste und späteste Startzeit mithilfe von Zeitfenstern im Jobs-Objekt an. |
| Kann ich für jede Aufgabe die erforderlichen Fähigkeiten oder Eigenschaften festlegen? | Ja, Merkmale werden im „jobs“-Objekt unterstützt und helfen dabei, Aufgaben mit geeigneten Fahrzeugen oder Fahrern abzugleichen. |
| Unterstützt die API die Neuoptimierung laufender Routen? | Ja, unter „Tutorials“ finden Sie Anleitungen zur erneuten Optimierung laufender Lösungen. |
| Stellt die API Statistiken zu Routen und Fahrplänen bereit? | Ja, unter „Lösung“ finden Sie detaillierte Statistiken wie Fahrzeit, Entfernung und nicht zugewiesene Aufträge. |
| Erklärt die API, warum Aufgaben nicht zugewiesen wurden? | Ja, die Gründe für nicht zugewiesene Aufträge finden Sie unter „Lösung “. |
| Gibt die API voraussichtliche Ankunftszeiten zurück? | Ja, siehe Lösung für die voraussichtlichen Fertigstellungszeiten pro Aufgabe. |
| Kann die API Aufträge nach Standort gruppieren? | Ja, Clustering wird unterstützt, um die Routeneffizienz zu verbessern. |
| Kann ich verschiedene Optimierungsziele auswählen? | Ja. Zu den Optionen gehören: „Gesamtfahrzeit minimieren“, „Anzahl der Routen minimieren“ und „Arbeitsaufwand auf die Routen verteilen“. Weitere Informationen finden Sie unter „Problem “. |