Route-optimalisatie API (REST + SOAP) – Ontwikkelaarsgids

Wat u kunt bouwen met de TrackRoad route-optimalisatie API#

De API maakt route-optimalisatie mogelijk voor veelvoorkomende zakelijke toepassingen:

• Systemen voor het plannen van bezorgroutes (koeriers, pakketten, boodschappen)
• Planning van buitendienstwerkzaamheden (technici, reparaties, installaties)
• Vlootdispatching met meerdere voertuigen en meerdere stops
• Workflows voor geocodering en turn-by-turn-routering
• Geavanceerde dispatchmodi voor verschillende routeringsstrategieën

De routeringsengine ondersteunt beperkingen zoals:

• Tijdvensters (aankomst- en vertrekbeperkingen)
• Capaciteitslimieten (gewicht / volume)
• Balans van tijd en afstand over voertuigen
• Meerdere start- en eindpunten voor voertuigen
• Pauzestops en servicetijd per stop

REST vs SOAP#

REST API (JSON/XML)

REST is lichtgewicht en gebruikelijk voor web- en mobiele integraties. TrackRoad ondersteunt REST-aanroepen met JSON- of XML-payloads.

SOAP API

SOAP is gebruikelijk in enterprise-systemen en ondersteunt sterk getypeerde servicereferenties in .NET. SOAP is handig als u gecompileerde klassen wilt zoals DispatchSpecification, Vehicle en Location.

Authenticatie (TrackServiceKey)#

TrackRoad gebruikt een stabiele API-sleutel genaamd TrackServiceKey. Deze werkt niet als een klassieke vervallende sessie-id. Zie API-authenticatie voor alle details.

• REST: Verstuur uw sleutel in de HTTP-header: X-API-Key: YOUR_TRACKSERVICEKEY
• SOAP: Verstuur uw sleutel in SessionIDHeader als SessionID

Dispatch API (kern-aanroep voor optimalisatie)#

Route-optimalisatie wordt uitgevoerd met Dispatch. Dispatch neemt voertuigen plus stops en retourneert geoptimaliseerde routes per voertuig.

Volledige referentie: Dispatch API

SOAP WSDL-endpoint

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

Typische Dispatch-invoer

• Voertuigen (elk met start- en eindlocatie)
• Stops (locaties)
• DispatchMode (Auto, EqualStop, SingleRegion, MultipleRegion, Optima, etc.)
• MinimumOptimization (precisie)

Tijdvensters en Optima-modus#

TrackRoad ondersteunt tijdvensters via aankomst- en vertrekbeperkingen per stop. Voor de beste resultaten raadt TrackRoad aan om DispatchMode Optima te gebruiken voor tijdvensters.

Belangrijke variabelen

• CanArriveEarly
• TimeConstraintArrival
• TimeConstraintDeparture

Als uw programmeertaal geen null-datetimewaarden kan doorgeven, gebruik dan 0001-01-01T00:00:00. TrackRoad behandelt datums kleiner dan of gelijk aan 1 januari 2012 als null.

Lees meer: Route-optimalisatie met Tijdvensters

Dispatch-resultaten begrijpen#

Dispatch retourneert geoptimaliseerde routes per voertuig. Elk voertuigresultaat bevat geordende stops met metadata zoals:

• Stopvolgorde
• MatchCode en betrouwbaarheid van adresmatch
• Latitude en Longitude
• Tijd en afstand tot de volgende stop

Tips voor prestaties en schaalbaarheid

• Bundel stops waar mogelijk in plaats van één route tegelijk te optimaliseren
• Geef nauwkeurige servicetijden en tijdvensters op voor realistische resultaten
• Gebruik Optima-modus voor schema's met beperkingen
• Verhoog minimum optimization voor betere kwaliteit bij grotere stopsets
• Gebruik multi-voertuigdispatching voor vlootroutering in plaats van aparte verzoeken

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

Dit voorbeeld toont de aanbevolen REST-flow met X-API-Key (TrackServiceKey).

Stap 1 — Authenticatieheaders instellen

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

Stap 2 — Dispatch (routes optimaliseren)

Dispatch neemt voertuigen plus stops en retourneert geoptimaliseerde routes. Dit voorbeeld gebruikt één voertuig en meerdere stops.

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
    }
  ]
}

Tip: Gebruik voor tijdvensters DispatchMode = Optima. Als uw integratie geen null-waarden kan versturen, gebruik dan een standaarddatum zoals 0001-01-01T00:00:00 om “null” weer te geven.

curl-voorbeeld

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 en Logout zijn beschikbaar voor achterwaartse compatibiliteit. Gebruik voor de meeste integraties X-API-Key (TrackServiceKey) bij elk verzoek.

SOAP C#-voorbeeld (SessionIDHeader → Dispatch)

TrackRoad SOAP-authenticatie gebruikt SessionIDHeader.SessionID = TrackServiceKey. Zie authenticatie voor alle details.

SOAP WSDL-endpoint

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

Stapsgewijs C# SOAP-voorbeeld

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}");
        }
    }
}

Opmerkingen

• Gebruik Optima-modus voor tijdvensters en schema's.
• Geef werktijden van chauffeurs op (TimeIn, TimeOut) voor realistische routering.
• Als u geen null-datetimewaarden kunt opgeven, gebruik dan DateTime.MinValue of een null-datumregel.

Probleemoplossing: veelvoorkomende API-fouten en hoe u ze oplost#

Route-optimalisatie is een beperkingsgebaseerd probleem. Als u ongeldige adressen of onmogelijke beperkingen opgeeft, zoals krappe tijdvensters, te weinig voertuigen of overschreden capaciteitslimieten, kan de dispatch-engine fouten retourneren of onvolledige routes produceren.

1) “Dispatch failed” of Success = false

• Ongeldige of onvolledige stopadressen
• Onmogelijke tijdvensters
• Werktijden van voertuigen zijn te kort
• Niet genoeg voertuigen om alle stops te bedienen
• Capaciteitsbeperkingen overschreden

2) Sommige stops ontbreken in routes

Veelvoorkomende oorzaken:

• Tijdvensters zijn te streng
• Werktijden zijn te streng
• Capaciteit overschreden
• Servicetijd duwt het schema buiten haalbare grenzen

3) Ongeldige of lage kwaliteit adresmatches (MatchCode-problemen)

• Geef volledige adressen op (straat, plaats, postcode, land)
• Als u al coördinaten hebt, verstuur dan Latitude en Longitude
• Valideer stops indien nodig met geocodering vóór dispatch

4) Tijdvensters zijn niet haalbaar

• Gebruik DispatchMode Optima
• Maak tijdvensters ruimer
• Sta vroege aankomst toe (CanArriveEarly = true) waar passend
• Voeg voertuigen toe of verleng werktijden van voertuigen

5) Niet genoeg voertuigen of onvolledige vlootroutering

• Voeg meer voertuigen toe
• Vergroot capaciteit (gewicht en volume)
• Verleng werktijden
• Gebruik DispatchMode MinimumVehicles als uw doel is om het benodigde aantal voertuigen te minimaliseren

6) API retourneert “key invalid” (authenticatie)

TrackRoad-authenticatie gebruikt een stabiele API-sleutel genaamd TrackServiceKey. “Key invalid” betekent meestal dat de sleutel ontbreekt, onjuist is of niet in de juiste header is verzonden.

• REST: verstuur X-API-Key: TrackServiceKey
• SOAP: verstuur SessionIDHeader.SessionID = TrackServiceKey
• Zie API-authenticatie voor exacte details.