Tourenbildung
Kairos Graph
Generischer Löser für Touren auf Graphen: Besuche und Sendungen werden auf Akteure verteilt, für jeden Akteur wird die Reihenfolge festgelegt. Berücksichtigt werden Kapazitäten, Fähigkeiten, Zeitfenster, Pausen und Obergrenzen je Tour.
Backend, nicht Lösung
Der Dienst ist bewusst abstrakt. Er kennt Knoten, Kanten, Akteure und Besuche. Fahrzeuge, Fahrer, Pakete, Koordinaten, Straßennetze oder Navigation kommen nicht vor. Alle Zahlen sind einheitenlos: Sie entscheiden, ob Kosten Euro oder Meter bedeuten und ob Zeit in Sekunden oder Minuten gezählt wird. Dauer, Zeitfenster und Verweildauer müssen dieselbe Zeiteinheit haben. Es gibt keine Datumsangaben; die Zeit beginnt bei 0.
Nicht abgedeckt: Koordinaten und Geocoding, Straßennetze, Verkehrslage, fachliche Modelle wie Lenk- und Ruhezeiten, Mehrtagesplanung, laufendes Umplanen und asynchrone Aufträge. Kostenmatrizen liefern Sie selbst, auch aus einem anderen Dienst.
Preise
Einreichgebühr pro Graph-Solve
Einmalig pro Request. Eine ungültige Anfrage (400) kostet nichts.
- + pro angefangene Solver-Sekunde300Credits
Synchroner Aufruf und Zeitlimit
Die Anfrage wird synchron beantwortet: Die Verbindung bleibt offen, bis die Lösung vorliegt. Wählen Sie das Client-Timeout länger als time_limit_seconds. Empfohlen sind Läufe bis 60 Sekunden. time_limit_seconds ist eine Obergrenze: Die Suche endet früher, sobald sich die Lösung nicht mehr verbessert. Die Antwort kommt nie später als das Limit.
/v1/kairos/graphBildet Touren auf einem Graphen. Der Aufruf ist synchron und liefert Routen mit Zeiten, Lasten und Kosten.
Parameter
graphGraphJaKnoten und Kosten: entweder Matrizen je Profil oder Kanten — siehe Abschnitt Graph.
taskTaskJaAufgabe vom Typ tours: Akteure, Besuche, Sendungen, Ziel — siehe Abschnitt Aufgabe.
configConfigOptionalStandard:{}Zeitlimit, Mindestsuchzeit, Early-Stopping, Korrelations-ID, Ergebnis-Auslagerung — siehe Abschnitt Config.
Request
curl -X POST "https://api.centra.dbpg.io/v1/kairos/graph" \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"graph": {
"nodes": [{ "id": "depot" }, { "id": "a" }, { "id": "b" }],
"matrices": {
"default": {
"cost": [[0, 10, 15], [10, 0, 6], [15, 6, 0]],
"duration": [[0, 600, 900], [600, 0, 300], [900, 300, 0]]
}
}
},
"task": {
"type": "tours",
"agents": [
{ "id": "agent-1", "start": "depot", "end": "depot", "capacity": [10] }
],
"visits": [
{ "id": "v1", "node": "a", "demand": [4], "service_duration": 300 },
{ "id": "v2", "node": "b", "demand": [3], "service_duration": 300 }
]
},
"config": { "time_limit_seconds": 30, "request_id": "example-1" }
}'Response
{
"status": "optimal",
"request_id": "example-1",
"result_url": "https://…/graph/3f2c9a0e8b7d4c1e9a6b5d4c3b2a1f0e.json?X-Amz-Signature=…",
"result_expires_at": "2026-10-29T19:00:00+00:00",
"totals": { "cost": 31, "penalties": 0, "objective": 31 },
"statistics": { "timing": { "total_seconds": 0.05, "solve_seconds": 0.04, "billable_seconds": 0.05, "stop_reason": "completed" } },
"warnings": [],
"diagnostics": null,
"errors": [],
"_meta": { "lambda_total_seconds": 0.06 },
"usage": {
"credits_used": 2300,
"remaining_balance": 7700
}
}Graph
Geben Sie genau eines von matrices oder edges an, sonst antwortet der Dienst mit 400. Ein Graph kann mehrere Kostensätze (Profile) tragen, zum Beispiel für schwere und leichte Akteure; jeder Akteur verweist mit profile auf einen. Höchstens 8 Profile.
graph
Parameter
nodesarray<{ id, … }>JaKnoten als Objekte mit eindeutiger id. Weitere Attribute sind erlaubt und werden ignoriert.
directedbooleanOptionalStandard:trueNur bei edges: false bedeutet, jede Kante gilt in beide Richtungen.
matricesobject<profile, MatrixProfile>AlternativeProfilname → Matrizen. Alternative zu edges.
edgesarray<Edge>AlternativeListe der Kanten. Alternative zu matrices.
Form 1: matrices
Je Profil eine quadratische Kostenmatrix in der Reihenfolge von nodes. null bedeutet nicht erreichbar; Asymmetrie ist erlaubt.
Parameter
costarray<array<number | null>>JaQuadratische Kostenmatrix, Werte ≥ 0, null = nicht erreichbar.
durationarray<array<number | null>>OptionalQuadratische Dauermatrix in derselben Form. Optional.
"matrices": {
"default": { "cost": [[0, 12.5, 9], [12, 0, 4], [9, 4.2, 0]],
"duration": [[0, 600, 450], [600, 0, 200], [450, 200, 0]] },
"heavy": { "cost": [[…]], "duration": [[…]] }
}Form 2: edges
Der Dienst berechnet je Profil die kürzesten Wege zwischen allen Knoten, die in Akteuren, Besuchen und Sendungen vorkommen. Maßgeblich sind die Kosten; die Dauer wird entlang desselben Weges aufsummiert. Die Ausgabe enthält je Stopp zusätzlich path.
Parameter
fromstringJaKnoten-ID des Anfangs.
tostringJaKnoten-ID des Endes.
costnumber ≥ 0JaKosten für das Profil default, ≥ 0.
durationnumber ≥ 0 | nullOptionalDauer für das Profil default.
by_profileobject<profile, { cost, duration } | null>OptionalÜberschreibt Kosten und Dauer je Profil. cost: null oder der ganze Eintrag null sperrt die Kante für dieses Profil.
"edges": [
{ "from": "depot", "to": "a", "cost": 12.5, "duration": 600,
"by_profile": { "heavy": { "cost": 20, "duration": 900 }, "bike": null } }
]Fehlt die Dauer im Profil eines Akteurs, sind Zeitbedingungen für diesen Akteur (time_window, breaks, break_rule, max_duration) und minimize: max_route_duration ungültig. Zeitfenster von Besuchen und Sendungen setzen in allen Profilen eine Dauer voraus.
Aufgabe
Aktueller und einziger Aufgabentyp ist tours. Mindestens ein Besuch oder eine Sendung ist erforderlich. IDs von Besuchen und Sendungen sind zusammen eindeutig, IDs von Akteuren ebenfalls.
task
total_cost: Summe aus Kantenkosten × cost_factor, Fixkosten und Strafwerten ausgelassener Aufträge. max_route_duration: gewichtetes Ziel balance_weight × längste Tourdauer + total_cost; totals.objective meldet genau diesen Wert.
Parameter
type"tours"JaImmer tours.
agentsarray<Agent> (1–200)JaAkteure, 1 bis 200.
visitsarray<Visit>OptionalStandard:[]Einzelbesuche.
shipmentsarray<Shipment>OptionalStandard:[]Abholung und Lieferung.
minimize"total_cost" | "max_route_duration"OptionalStandard:"total_cost"total_cost oder max_route_duration.
balance_weightnumberOptionalStandard:100Nur bei max_route_duration: Gewicht der längsten Tourdauer. 0 oder ≥ 1.
Akteur (agents[])
Ein Akteur fährt eine Tour von start nach end. Feste Pausen (breaks) beginnen in einem ihrer Fenster und sind Pflicht; ist eine nicht einplanbar, ist der Akteur in dieser Form nicht einsetzbar.
Parameter
idstringJaEindeutige ID.
profilestringOptionalStandard:"default"Kostensatz des Graphen; muss existieren.
startstringJaKnoten-ID des Starts.
endstring | nullJaKnoten-ID des Endes oder null für ein offenes Ende. Der Schlüssel muss vorhanden sein.
capacityarray<number ≥ 0> | nullOptionalStandard:nullKapazitätsvektor, gleiche Länge wie demand und amount aller Besuche und Sendungen. null = keine Grenze.
skillsarray<string>OptionalStandard:[]Fähigkeiten, frei belegbar.
time_window[from, to] | nullOptionalStandard:nullEinsatzfenster [von, bis].
breaksarray<Break>OptionalStandard:[]Feste Pausen: id, time_windows (mindestens ein Fenster, innerhalb von time_window) und duration.
break_rule{ max_continuous, duration } | nullOptionalStandard:nullPausenmuster mit max_continuous und duration — siehe Abschnitt Pausenmuster.
max_durationnumber ≥ 0 | nullOptionalStandard:nullObergrenze der Tourdauer.
max_costnumber ≥ 0 | nullOptionalStandard:nullObergrenze der Tourkosten.
fixed_costnumber ≥ 0OptionalStandard:0Fällt an, sobald der Akteur mindestens einen Stopp hat.
cost_factornumber (> 0, ≤ 1000)OptionalStandard:1Multiplikator auf die Kantenkosten dieses Akteurs, > 0 und höchstens 1000.
{
"id": "agent-1", "profile": "default",
"start": "depot", "end": "depot",
"capacity": [100, 8], "skills": ["cooling"],
"time_window": [0, 28800],
"breaks": [{ "id": "lunch", "time_windows": [[14400, 18000]], "duration": 1800 }],
"break_rule": { "max_continuous": 16200, "duration": 2700 },
"fixed_cost": 0, "cost_factor": 1
}Besuch (visits[])
Ein Besuch wird von genau einem Akteur bedient. Mehrere Besuche am selben Knoten sind erlaubt.
Parameter
idstringJaEindeutige ID.
nodestringJaKnoten-ID.
demandarray<number ≥ 0> | nullOptionalStandard:nullBelegt Kapazität ab dem Besuch bis zum Tourende.
skillsarray<string>OptionalStandard:[]Der Akteur braucht alle. Leer = jeder Akteur.
time_windowsarray<[from, to]>OptionalStandard:[]Der Beginn der Bedienung muss in einem Fenster liegen. Leer = kein Fenster.
service_durationnumber ≥ 0OptionalStandard:0Verweildauer.
penaltynumber ≥ 0 | nullOptionalStandard:nullnull = Pflichtbesuch. Eine Zahl erlaubt, den Besuch gegen diesen Strafwert auszulassen.
{ "id": "v1", "node": "a", "demand": [10, 1], "skills": [],
"time_windows": [[3600, 7200], [14400, 18000]],
"service_duration": 300, "penalty": null }Sendung (shipments[])
Derselbe Akteur übernimmt Abholung (zuerst) und Lieferung. amount belegt Kapazität von der Abholung bis zur Lieferung. Ausgelassen wird immer die ganze Sendung.
Parameter
idstringJaEindeutige ID.
amountarray<number ≥ 0> | nullOptionalStandard:nullBelegt Kapazität von der Abholung bis zur Lieferung.
skillsarray<string>OptionalStandard:[]Der Akteur braucht alle.
pickup{ node, time_windows, service_duration }JaAbholung: node (Pflicht), time_windows, service_duration.
delivery{ node, time_windows, service_duration }JaLieferung: node (Pflicht), time_windows, service_duration.
penaltynumber ≥ 0 | nullOptionalStandard:nullnull = Pflichtsendung, sonst Strafwert für das Auslassen.
{ "id": "s1", "amount": [5, 1], "skills": ["cooling"],
"pickup": { "node": "a", "time_windows": [[0, 7200]], "service_duration": 120 },
"delivery": { "node": "b", "time_windows": [[3600, 14400]], "service_duration": 120 },
"penalty": null }Zeitfenster
Jedes Fenster ist [von, bis] mit 0 ≤ von ≤ bis. Fenster eines Feldes müssen nach Beginn sortiert sein und dürfen sich nicht überlappen. Wartezeit vor dem Fensteranfang ist erlaubt.
Config
Alle Felder sind optional.
config
Das Zeitlimit ist eine Obergrenze für den gesamten Lauf: Prüfung der Eingabe, Aufbau der Matrizen, Vorprüfung, Modellaufbau, Suche und Prüfung der Lösung. Der Lauf endet meist früher, sobald sich die Lösung eine Zeit lang nicht mehr verbessert hat (Frühabbruch). Das Stillstandsfenster beträgt ein Viertel der bisherigen Suchzeit, mindestens 1 und höchstens 10 Sekunden; bei größeren Aufgaben ist es eher länger. Kleine Aufgaben enden so nach etwa einer Sekunde. Abgerechnet werden nur die tatsächlich genutzten Sekunden.
Parameter
time_limit_secondsnumber (1–600)OptionalStandard:60Obergrenze des gesamten Laufs in Sekunden, als Zahl (eine Zeichenkette wie "600" ergibt 400). Wird auf ganze Sekunden aufgerundet und auf 1 bis 600 begrenzt. Der Lauf endet meist früher (Frühabbruch bei Stillstand) und wird nur nach den genutzten Sekunden berechnet; der Wert bestimmt die Reserve, die vorab gebucht wird.
min_search_secondsnumber (0–time_limit_seconds)OptionalStandard:0Mindestsuchzeit in Sekunden, gezählt ab Eingang der Anfrage, als Zahl von 0 bis time_limit_seconds. Vorher endet die Suche nicht wegen Stillstands. Das ist keine Mindestlaufzeit: Die Suche endet weiterhin am Zeitlimit, und liegt min_search_seconds nahe daran, ist die Laufzeit kürzer als min_search_seconds. Sie endet auch früher, wenn die Suche von selbst fertig ist oder die Unlösbarkeit beweist. Ein Wert über time_limit_seconds ergibt 400 (status invalid, Fehler an config.min_search_seconds). Ohne Wirkung bei stop_after_first_solution. Eine längere Suche erhöht die abgerechneten Sekunden.
stop_after_first_solutionbooleanOptionalStandard:falseErste gültige Lösung zurückgeben, keine Verbesserung.
request_idstring | nullOptionalStandard:nullKorrelations-ID; wird in der Antwort gespiegelt.
offload_resultbooleanOptionalStandard:trueImmer true: Bei optimal und feasible liegt das Ergebnis hinter result_url, siehe Abschnitt Große Ergebnisse. Ein anderer Wert wird überschrieben.
result_url_expires_ininteger (60–604800)OptionalStandard:10800Gewünschte Gültigkeit der result_url in Sekunden. Effektiv höchstens etwa 24 Stunden, siehe Abschnitt Große Ergebnisse.
Ab etwa 400 Stopps empfiehlt sich ein längeres time_limit_seconds (bis 300). Die Lösungen sind gültig, bei engen Zeitfenstern aber nicht in jedem Fall nahe am Optimum. Wer die volle Suchzeit nutzen möchte, setzt min_search_seconds.
Antwort
Die Antwort enthält je eingesetztem Akteur eine Route. Alle Zahlen sind in Ihren Einheiten.
Status-Werte
Alle Antworten mit Lauf werden nach billable_seconds abgerechnet; invalid kostet nichts.
| status | HTTP | Abgerechnet | Bedeutung |
|---|---|---|---|
optimal | 200 | ja | Optimalität bewiesen. Das kommt nur bei sehr kleinen Problemen vor. |
feasible | 200 | ja | Lösung gefunden, alle harten Bedingungen sind erfüllt. Der Normalfall bei realen Größen und ein vollwertiges Ergebnis. |
infeasible | 200 | nur Einreichung | Die Vorprüfung oder die Suche beweist, dass keine Lösung existiert. Die Gründe stehen in warnings und diagnostics.reasons. |
unknown | 200 | ja | Bis zum Stillstand oder zum Zeitlimit wurde keine vollständige Lösung gefunden. Das bedeutet nicht, dass keine existiert. |
invalid | 400 | nein | Die Eingabe ist inkonsistent, zum Beispiel ein unbekannter Knoten. Details in errors[]. |
Ein Pflichtauftrag (penalty: null) steht nie in dropped. Lässt die Suche einen aus, lautet die Antwort unknown.
Felder der Antwort
Parameter
status"optimal" | "feasible" | "infeasible" | "unknown" | "invalid"JaErgebnis der Planung, siehe Status-Werte.
request_idstring | nullOptionalSpiegel von config.request_id.
result_urlstringOptionalBei optimal und feasible: signierte URL der Datei mit der vollständigen Antwort (routes, dropped, unused_agents).
result_expires_atstring (ISO 8601)OptionalBei optimal und feasible: Ablaufzeitpunkt der result_url.
routesarray<Route>OptionalBei infeasible und unknown direkt in der Antwort; bei optimal und feasible in der Datei hinter result_url. Eine Route je eingesetztem Akteur, in der Reihenfolge der Akteure der Anfrage.
unused_agentsarray<string>OptionalIDs der Akteure ohne Stopp. Dafür fallen keine Fixkosten an. Bei optimal und feasible in der Datei hinter result_url.
droppedarray<{ type, id, penalty }>OptionalAusgelassene optionale Aufträge mit type, id und penalty. Bei optimal und feasible in der Datei hinter result_url.
totals{ cost, penalties, objective }Jacost (Summe der Routenkosten), penalties (Summe der Strafwerte) und objective (Zielfunktionswert).
statistics{ timing }Jatiming.total_seconds, timing.solve_seconds, timing.billable_seconds (Abrechnungsgrundlage) und timing.stop_reason (warum der Lauf endete, siehe Abschnitt Abbruchgrund).
warningsarray<string>JaHinweise auf Deutsch; bei infeasible die Gründe.
diagnostics{ stage, reasons } | nullJaBei infeasible: stage (precheck oder solve) und reasons[], sonst null.
errorsarray<{ field, message }>JaBei invalid: Liste von field und message, alle Fehler auf einmal.
usage{ credits_used, remaining_balance }Jacredits_used und remaining_balance.
Abbruchgrund (statistics.timing.stop_reason)
Das Feld nennt, warum der Lauf endete.
stallFrühabbruch: Die Lösung hat sich innerhalb des Stillstandsfensters nicht mehr verbessert. Auch unknown kann so enden: Dann hat die Suche mindestens 10 Sekunden lang keine bessere Lösung gefunden, und keine gefundene Lösung bedient alle Pflichtaufträge.completedDie Suche war von selbst fertig, vor dem Zeitlimit und ohne Stillstandsfenster.time_limitDie Suche lief bis zum Zeitlimit. Das gilt auch bei unknown ohne Stillstand, wenn in der Zeit keine vollständige Lösung gefunden wurde.first_solutionstop_after_first_solution war gesetzt: Die erste Lösung wurde zurückgegeben.infeasibleDie Suche hat die Unlösbarkeit bewiesen (diagnostics.stage solve).precheckDie Vorprüfung hat die Unlösbarkeit erkannt. Es lief keine Suche (billable_seconds 0).invalidDie Eingabe ist ungültig. Es lief keine Suche (billable_seconds 0).
Route und Stopp
Jede Route hat agent, stops[], breaks[], cost und duration (null, wenn das Profil keine Dauer hat). Ein Stopp hat type (start, visit, pickup, delivery oder end), id (nicht bei start und end), node, arrival, departure und load (belegte Kapazität nach dem Stopp). Im Modus edges steht zusätzlich path mit den Zwischenknoten seit dem vorigen Stopp.
Abrechnung
Der Preis besteht aus der Einreichungsgebühr und den Solver-Sekunden.
- Vorab werden als Reserve 2.000 + 300 × time_limit_seconds Credits gebucht, der schlimmste Fall. Ist das Guthaben zu klein, antwortet der Dienst mit 402, bevor gerechnet wird.
- Nach der Antwort bleiben 2.000 + 300 × aufgerundete statistics.timing.billable_seconds Credits abgebucht, der nicht genutzte Teil der Reserve wird erstattet. Berechnet wird die tatsächliche Laufzeit, nie mehr als die Reserve.
- Endet die Suche durch den Frühabbruch (stop_reason stall), sind das oft nur wenige Sekunden, auch bei time_limit_seconds 60. min_search_seconds verlängert die Suche und erhöht damit die berechneten Sekunden.
- Erkennt die Vorprüfung eine unlösbare Anfrage (infeasible mit diagnostics.stage precheck), läuft keine Suche: Es fällt nur die Einreichungsgebühr an.
- Eine ungültige Anfrage (400) kostet nichts.
- Bei Fehlern des Dienstes (5xx, Zeitüberschreitung) wird alles erstattet.
- Eine unlösbare Anfrage, die die Vorprüfung nicht erkennt (etwa zu wenige Akteure für alle Pflichtbesuche), endet mit unknown, sobald die Suche 10 Sekunden lang keine bessere Lösung findet, spätestens am Zeitlimit. Sie wird mit den genutzten Sekunden berechnet, weil die Suche die Unlösbarkeit nicht beweist; gemessen waren es etwa 20 bis 30 Sekunden bei time_limit_seconds 60. Für Plausibilitätsprüfungen wählen Sie ein kleines time_limit_seconds.
Was die Vorprüfung erkennt
Nur notwendige Bedingungen: fehlende Fähigkeiten, Bedarf über der Kapazität jedes fähigen Akteurs oder der ganzen Flotte, Zeitfenster außerhalb aller Einsatzfenster und Pflichtaufträge, die kein fähiger Akteur allein in einer eigenen Tour erreichen und rechtzeitig bedienen kann. Die Prüfung weist nie eine lösbare Eingabe ab.
Pausenmuster und seine Grenzen
break_rule mit max_continuous M und duration D bedeutet: höchstens M am Stück arbeiten, dann mindestens D Pause. Es ist ein abstraktes Muster, keine fachliche Abbildung von Lenk- und Ruhezeiten. Gemessen wird vom Tourbeginn bis zum Tourende; Fahrt, Verweildauer und Warten zählen als Arbeit, nur Pausen von mindestens D unterbrechen. Feste Pausen mit mindestens D zählen mit.
Einschränkung
Regelpausen werden nur unmittelbar vor oder unmittelbar nach einer Verweildauer angelegt, je Stopp höchstens eine. Fahrten und Wartezeiten werden nicht in der Mitte unterbrochen.
- Eine einzelne Fahrt oder ein Stopp mit An- und Abfahrt, der zwei Pausen bräuchte, ist für Akteure mit Regel nicht planbar.
- Zwischen zwei Stopps liegen höchstens zwei Regelpausen.
- Am Tourbeginn liegt keine Regelpause; bei offenem Ende liegt keine Regelpause nach dem letzten Stopp.
- Touren, die nur mit Pausen an anderer Stelle einhaltbar wären, gelten als nicht einhaltbar. Ist die Regel nicht einhaltbar, ist der Akteur nicht einsetzbar.
- Pflichtaufträge, deren Verweildauer bei jedem fähigen Akteur max_continuous übersteigt, ergeben infeasible.
- Regelpausen stehen in route.breaks mit den IDs rule-1, rule-2 und so weiter. Das ID-Präfix rule- ist bei Akteuren mit Regel für feste Pausen reserviert.
- Höchstens 2 verschiedene Regeln je Anfrage, höchstens 2 verschiedene Profile und 2 verschiedene Kombinationen aus Profil und cost_factor unter den Akteuren. Das Pausenmuster setzt eine Dauer im Profil des Akteurs voraus.
Grenzen
Eine Überschreitung ergibt status invalid (HTTP 400) mit einer Meldung in errors[]. Die Prüfung meldet alle Fehler auf einmal.
| Grenze | Wert |
|---|---|
| Knoten bei matrices | 2.000 |
| Kanten bei edges | 200.000 |
| Profile | 8 |
| Akteure | 200 |
| Stopps (Besuche + 2 × Sendungen) | 2.000 |
| Routing-Knoten: Stopps × (1 + 2 × Anzahl der Pausenregeln) + 2 × Akteure | 2.500 |
| Verschiedene Paare aus Profil und cost_factor | 8 |
| Bei edges: benötigte Knoten (Start, Ziel, Besuche, Abholungen, Lieferungen) × Knoten des Netzes × Profile | 30.000.000 |
| Betrag jedes Zahlenwerts (endlich) | ≤ 1e9 |
| time_limit_seconds | 1 bis 600 |
| Größe der Anfrage | bis 30 MB |
Eine volle Kosten- und Dauermatrix für etwa 1.300 Knoten passt in 25 MB; bei zwei Profilen etwa 900 Knoten. Anfragen über 4 MB nimmt der Dienst an und verarbeitet sie automatisch.
Große Ergebnisse
Bei optimal und feasible liegt die vollständige Lösung immer hinter einer signierten URL: Die Antwort enthält statt routes, dropped und unused_agents die Felder result_url und result_expires_at. Laden Sie die Datei per GET ohne Zugangsdaten; routes, dropped und unused_agents lesen Sie aus dieser Datei. Nur bei infeasible und unknown (und als Fehlerantwort bei invalid) steht alles direkt in der Antwort. Die Auslagerung ist fest eingestellt; config.offload_result wird immer auf true gesetzt.
Inhalt der Datei
Die Datei hinter result_url enthält die vollständige Antwort mit den Routen. request_id ist dort unsere interne Vorgangs-ID; Ihre eigene request_id steht in der Antwort des Endpunkts.
curl -s "$RESULT_URL"
{
"status": "optimal",
"request_id": "…",
"routes": [{
"agent": "agent-1",
"stops": [
{ "type": "start", "node": "depot", "arrival": 0, "departure": 0, "load": [0] },
{ "type": "visit", "id": "v1", "node": "a", "arrival": 600, "departure": 900, "load": [4] },
{ "type": "visit", "id": "v2", "node": "b", "arrival": 1200, "departure": 1500, "load": [7] },
{ "type": "end", "node": "depot", "arrival": 2400, "departure": 2400, "load": [7] }
],
"breaks": [],
"cost": 31, "duration": 2400
}],
"unused_agents": [],
"dropped": [],
"totals": { "cost": 31, "penalties": 0, "objective": 31 },
"statistics": { "timing": { "total_seconds": 0.05, "solve_seconds": 0.04, "billable_seconds": 0.05, "stop_reason": "completed" } },
"warnings": [],
"diagnostics": null,
"errors": []
}result_url
Die result_url ist effektiv höchstens etwa 24 Stunden gültig, unabhängig von result_url_expires_in; bei kürzer laufenden Sitzungen auch kürzer. Holen Sie Ergebnisse zeitnah ab. Jede Anfrage erhält eine eigene Datei.
Fehler
Ungültige Anfragen werden mit HTTP 400 beantwortet und kosten nichts. Bei Schema-Verletzungen und bei der inhaltlichen Prüfung enthält error.errors[] je Fehler field und message, alle Fehler auf einmal. field ist der Pfad im Request, zum Beispiel task.visits[17].node; die Meldungen sind auf Deutsch.
| HTTP | Fall | Wann |
|---|---|---|
| 400 | error.errors[] | Schema-Verletzung: fehlendes Pflichtfeld, falscher Typ, unbekanntes Feld, falscher task.type oder Wert außerhalb der Feldgrenzen. |
| 400 | error.errors[] | Inhaltliche Prüfung: unbekannte oder doppelte IDs, Matrix nicht quadratisch, Vektorlängen passen nicht zusammen, Zeitbedingung ohne Dauer, Größengrenze überschritten und weitere. |
| 400 | bad_request | Der Body ist kein gültiges JSON. |
| 402 | insufficient_credits | Das Guthaben deckt die Reservierung nicht. |
| 5xx | — | Unerwarteter Fehler oder Zeitüberschreitung des Dienstes. Die Reservierung wird erstattet. |