Routenoptimierungs-API (REST + SOAP) – Entwicklerleitfaden

Was Sie mit der TrackRoad Routenoptimierungs-API entwickeln können#

Die API ermöglicht Routenoptimierung für typische Geschäftsanwendungsfälle:

• Liefer­routenplanungssysteme (Kurier, Pakete, Lebensmittel)
• Außendienst- und Einsatzplanung (Techniker, Reparaturen, Installationen)
• Flottendisposition mit mehreren Fahrzeugen und mehreren Stopps
• Geocoding- und Turn-by-Turn-Routing-Workflows
• Erweiterte Dispatch-Modi für unterschiedliche Routing-Strategien

Die Routing-Engine unterstützt Einschränkungen wie:

• Zeitfenster (Ankunfts- und Abfahrtsbeschränkungen)
• Kapazitätsgrenzen (Gewicht / Volumen)
• Zeit- und Distanzbalance über Fahrzeuge hinweg
• Mehrere Start- und Zielpunkte pro Fahrzeug
• Pausenstopps und Servicezeit pro Stopp

REST vs. SOAP#

REST-API (JSON/XML)

REST ist leichtgewichtig und verbreitet für Web- und Mobile-Integrationen. TrackRoad unterstützt REST-Aufrufe mit JSON- oder XML-Payloads.

SOAP-API

SOAP ist in Enterprise-Systemen verbreitet und unterstützt stark typisierte Service-Referenzen in .NET. SOAP ist nützlich, wenn Sie kompilierte Klassen wie DispatchSpecification, Vehicle und Location verwenden möchten.

Authentifizierung (TrackServiceKey)#

TrackRoad verwendet einen stabilen API-Schlüssel namens TrackServiceKey. Er verhält sich nicht wie eine klassische ablaufende Session-ID. Siehe API-Authentifizierung für vollständige Details.

• REST: Senden Sie Ihren Schlüssel im HTTP-Header: X-API-Key: YOUR_TRACKSERVICEKEY
• SOAP: Senden Sie Ihren Schlüssel im SessionIDHeader als SessionID

Dispatch-API (zentraler Optimierungsaufruf)#

Die Routenoptimierung wird mit Dispatch durchgeführt. Dispatch nimmt Fahrzeuge plus Stopps entgegen und gibt optimierte Routen pro Fahrzeug zurück.

Vollständige Referenz: Dispatch-API

SOAP-WSDL-Endpunkt

http://trackservice.trackroad.com/trackservice.asmx?wsdl

Typische Dispatch-Eingaben

• Fahrzeuge (jeweils mit Start- und Zielort)
• Stopps (Standorte)
• DispatchMode (Auto, EqualStop, SingleRegion, MultipleRegion, Optima usw.)
• MinimumOptimization (Präzision)

Zeitfenster und Optima-Modus#

TrackRoad unterstützt Zeitfenster über Ankunfts- und Abfahrtsbeschränkungen pro Stopp. Für die besten Ergebnisse empfiehlt TrackRoad bei Zeitfenstern den DispatchMode Optima.

Zentrale Variablen

• CanArriveEarly
• TimeConstraintArrival
• TimeConstraintDeparture

Wenn Ihre Sprache keine null-Datetime-Werte übergeben kann, verwenden Sie 0001-01-01T00:00:00. TrackRoad behandelt Daten kleiner oder gleich dem 1. Januar 2012 als null.

Mehr dazu: Routenoptimierung mit Zeitfenstern

Dispatch-Ergebnisse verstehen#

Dispatch gibt optimierte Routen pro Fahrzeug zurück. Jedes Fahrzeugergebnis enthält geordnete Stopps mit Metadaten wie:

• Stopp-Reihenfolge
• MatchCode und Adress-Match-Qualität
• Breitengrad und Längengrad
• Zeit und Distanz bis zum nächsten Stopp

Tipps für Performance und Skalierung

• Stopps nach Möglichkeit bündeln, statt jeweils nur eine Route zu optimieren
• Genaue Servicezeiten und Zeitfenster angeben, um realistische Ergebnisse zu erhalten
• Optima-Modus für Zeitpläne mit Einschränkungen verwenden
• MinimumOptimization für bessere Qualität bei größeren Stoppmengen erhöhen
• Mehrfahrzeug-Dispatching für Flottenrouting statt separater Anfragen verwenden

REST-JSON-Beispiel (X-API-Key → Dispatch)#

Dieses Beispiel zeigt den empfohlenen REST-Ablauf mit X-API-Key (TrackServiceKey).

Schritt 1 — Authentifizierungs-Header setzen

Headers:
X-API-Key: YOUR_TRACKSERVICEKEY
Content-Type: application/json

Schritt 2 — Dispatch (Routen optimieren)

Dispatch nimmt Fahrzeuge plus Stopps entgegen und gibt optimierte Routen zurück. Dieses Beispiel verwendet ein Fahrzeug und mehrere Stopps.

POST https://trackservice.trackroad.com/rest/dispatch
Headers:
X-API-Key: YOUR_TRACKSERVICEKEY
Content-Type: application/json

{
  "DispatchMode": "Optima",
  "DistanceUnit": "Mile",
  "MinimumOptimization": 1,
  "Vehicles": [
    {
      "Name": "Vehicle 1",
      "StartLocation": { "Name": "Depot", "Address": "350 5th Ave, New York, NY" },
      "FinishLocation": { "Name": "Depot", "Address": "350 5th Ave, New York, NY" },
      "TimeIn": "2025-12-25T08:00:00",
      "TimeOut": "2025-12-25T18:00:00",
      "CapacityWeight": 1000,
      "CapacityVolume": 100
    }
  ],
  "Stops": [
    {
      "Name": "Stop 1",
      "Address": "405 Lexington Ave, New York, NY",
      "ServiceTimeMinutes": 10,
      "TimeWindowStart": "2025-12-25T09:00:00",
      "TimeWindowEnd": "2025-12-25T11:00:00",
      "Weight": 120,
      "Volume": 12
    },
    {
      "Name": "Stop 2",
      "Address": "11 Wall St, New York, NY",
      "ServiceTimeMinutes": 8,
      "TimeWindowStart": "2025-12-25T10:00:00",
      "TimeWindowEnd": "2025-12-25T14:00:00",
      "Weight": 60,
      "Volume": 6
    },
    {
      "Name": "Stop 3",
      "Address": "200 Central Park West, New York, NY",
      "ServiceTimeMinutes": 12,
      "Weight": 80,
      "Volume": 8
    }
  ]
}

Tipp: Verwenden Sie für Zeitfenster DispatchMode = Optima. Wenn Ihre Integration keine null-Werte senden kann, verwenden Sie ein Standarddatum wie 0001-01-01T00:00:00, um „null“ darzustellen.

curl-Beispiel

curl -X POST "https://trackservice.trackroad.com/rest/dispatch" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY" \
  -H "Content-Type: application/json" \
  -d @dispatch-request.json

Legacy Login und Logout sind aus Gründen der Abwärtskompatibilität verfügbar. Für die meisten Integrationen verwenden Sie bei jeder Anfrage X-API-Key (TrackServiceKey).

SOAP-C#-Beispiel (SessionIDHeader → Dispatch)

Die TrackRoad SOAP-Authentifizierung verwendet SessionIDHeader.SessionID = TrackServiceKey. Siehe Authentifizierung für vollständige Details.

SOAP-WSDL-Endpunkt

http://trackservice.trackroad.com/trackservice.asmx?wsdl

Schritt-für-Schritt-C#-SOAP-Beispiel

using System;
using System.Collections.Generic;
using TrackServiceRef; // your generated SOAP reference namespace

public class TrackRoadSoapExample
{
    public static void OptimizeRoutesWithSoap()
    {
        var client = new TrackServiceSoapClient();

        // TrackRoad SOAP uses TrackServiceKey as SessionID.
        string sessionId = "YOUR_TRACKSERVICEKEY";

        // Vehicles
        var vehicle = new Vehicle
        {
            Name = "Vehicle 1",
            StartLocation = new Location { Name = "Depot", Address = "350 5th Ave, New York, NY" },
            FinishLocation = new Location { Name = "Depot", Address = "350 5th Ave, New York, NY" },
            TimeIn = new DateTime(2025, 12, 25, 8, 0, 0),
            TimeOut = new DateTime(2025, 12, 25, 18, 0, 0),
            CapacityWeight = 1000,
            CapacityVolume = 100
        };

        // Stops
        var stops = new List<Location>
        {
            new Location
            {
                Name = "Stop 1",
                Address = "405 Lexington Ave, New York, NY",
                ServiceTime = 10,
                TimeConstraintArrival = new DateTime(2025, 12, 25, 9, 0, 0),
                TimeConstraintDeparture = new DateTime(2025, 12, 25, 11, 0, 0),
                CanArriveEarly = true,
                Weight = 120,
                Volume = 12
            },
            new Location
            {
                Name = "Stop 2",
                Address = "11 Wall St, New York, NY",
                ServiceTime = 8,
                TimeConstraintArrival = new DateTime(2025, 12, 25, 10, 0, 0),
                TimeConstraintDeparture = new DateTime(2025, 12, 25, 14, 0, 0),
                CanArriveEarly = true,
                Weight = 60,
                Volume = 6
            },
            new Location
            {
                Name = "Stop 3",
                Address = "200 Central Park West, New York, NY",
                ServiceTime = 12,
                Weight = 80,
                Volume = 8
            }
        };

        // Dispatch spec
        var spec = new DispatchSpecification
        {
            DispatchMode = DispatchMode.Optima,
            DistanceUnit = DistanceUnit.Mile,
            MinimumOptimization = 1,
            CurrentTime = DateTime.MinValue
        };

        // Dispatch
        var dispatchResult = client.Dispatch(sessionId, spec, new[] { vehicle }, stops.ToArray());

        if (!dispatchResult.Success)
            throw new Exception("Dispatch failed: " + dispatchResult.Message);

        foreach (var route in dispatchResult.Routes)
        {
            Console.WriteLine($"Vehicle: {route.VehicleName}");
            Console.WriteLine($"Distance: {route.Distance}");
            Console.WriteLine($"Duration: {route.Duration}");

            foreach (var stop in route.Stops)
                Console.WriteLine($"  {stop.Sequence}. {stop.Name}  ETA: {stop.ETA}");
        }
    }
}

Hinweise

• Verwenden Sie den Optima-Modus für Zeitfenster und Zeitpläne.
• Geben Sie Fahrer-Arbeitszeiten (TimeIn, TimeOut) für realistisches Routing an.
• Wenn Sie keine null-Datetime-Werte übergeben können, verwenden Sie DateTime.MinValue oder eine Null-Datums-Regel.

Troubleshooting: Häufige API-Fehler und deren Behebung#

Routenoptimierung ist ein nebenbedingungsbasiertes Problem. Wenn Sie ungültige Adressen oder unmögliche Einschränkungen angeben, etwa enge Zeitfenster, zu wenige Fahrzeuge oder überschrittene Kapazitätsgrenzen, kann die Dispatch-Engine Fehler zurückgeben oder unvollständige Routen erzeugen.

1) „Dispatch failed“ oder Success = false

• Ungültige oder unvollständige Stoppadressen
• Unmögliche Zeitfenster
• Zu kurze Fahrzeug-Arbeitszeiten
• Nicht genügend Fahrzeuge, um alle Stopps zu bedienen
• Kapazitätsgrenzen überschritten

2) Einige Stopps fehlen in den Routen

Häufige Ursachen:

• Zeitfenster zu streng
• Arbeitszeiten zu streng
• Kapazität überschritten
• Servicezeit macht den Zeitplan nicht mehr realistisch erfüllbar

3) Ungültige oder schlechte Adress-Matches (MatchCode-Probleme)

• Vollständige Adressen angeben (Straße, Ort, Postleitzahl, Land)
• Wenn Koordinaten bereits vorliegen, Latitude und Longitude senden
• Stopps bei Bedarf vor dem Dispatch per Geocoding validieren

4) Zeitfenster sind nicht erfüllbar

• DispatchMode Optima verwenden
• Zeitfenster erweitern
• Frühe Ankunft erlauben (CanArriveEarly = true), wenn passend
• Weitere Fahrzeuge hinzufügen oder Fahrzeug-Arbeitszeiten erhöhen

5) Nicht genügend Fahrzeuge oder unvollständiges Flottenrouting

• Weitere Fahrzeuge hinzufügen
• Kapazität erhöhen (Gewicht und Volumen)
• Arbeitszeiten erhöhen
• DispatchMode MinimumVehicles verwenden, wenn das Ziel die Minimierung der benötigten Fahrzeuge ist

6) API gibt „key invalid“ zurück (Authentifizierung)

Die TrackRoad-Authentifizierung verwendet einen stabilen API-Schlüssel namens TrackServiceKey. „Key invalid“ bedeutet typischerweise, dass der Schlüssel fehlt, falsch ist oder nicht an der richtigen Stelle gesendet wurde.

• REST: X-API-Key: TrackServiceKey senden
• SOAP: SessionIDHeader.SessionID = TrackServiceKey senden
• Siehe API-Authentifizierung für genaue Details.