API optymalizacji tras (REST + SOAP) – przewodnik deweloperski

Co możesz zbudować z API optymalizacji tras TrackRoad#

API umożliwia optymalizację tras dla typowych zastosowań biznesowych:

• Systemy planowania tras dostaw (kurierzy, paczki, grocery)
• Planowanie usług terenowych (technicy, naprawy, instalacje)
• Dispatching floty z wieloma pojazdami i wieloma punktami
• Workflow geokodowania i wyznaczania trasy krok po kroku
• Zaawansowane tryby Dispatch dla różnych strategii routingu

Silnik routingu obsługuje ograniczenia takie jak:

• Okna czasowe (ograniczenia przyjazdu i wyjazdu)
• Limity pojemności (waga / objętość)
• Równoważenie czasu i dystansu między pojazdami
• Wiele punktów startu i zakończenia dla pojazdów
• Przystanki przerw i czas obsługi na punkt

REST vs SOAP#

API REST (JSON/XML)

REST jest lekkie i powszechne w integracjach webowych i mobilnych. TrackRoad obsługuje wywołania REST z payloadami JSON lub XML.

API SOAP

SOAP jest powszechne w systemach enterprise i obsługuje silnie typowane referencje usług w .NET. SOAP jest przydatne, jeśli chcesz korzystać ze skompilowanych klas, takich jak DispatchSpecification, Vehicle i Location.

Uwierzytelnianie (TrackServiceKey)#

TrackRoad używa stabilnego klucza API o nazwie TrackServiceKey. Nie działa on jak klasyczny identyfikator sesji wygasający po czasie. Zobacz uwierzytelnianie API , aby poznać pełne szczegóły.

• REST: wyślij klucz w nagłówku HTTP: X-API-Key: YOUR_TRACKSERVICEKEY
• SOAP: wyślij klucz w SessionIDHeader jako SessionID

API Dispatch (główne wywołanie optymalizacyjne)#

Optymalizacja tras jest wykonywana za pomocą Dispatch. Dispatch przyjmuje pojazdy oraz punkty i zwraca zoptymalizowane trasy dla każdego pojazdu.

Pełna referencja: API Dispatch

Endpoint SOAP WSDL

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

Typowe dane wejściowe Dispatch

• Pojazdy (każdy z lokalizacją startową i końcową)
• Punkty (lokalizacje)
• DispatchMode (Auto, EqualStop, SingleRegion, MultipleRegion, Optima itd.)
• MinimumOptimization (precyzja)

Okna czasowe i tryb Optima#

TrackRoad obsługuje okna czasowe poprzez ograniczenia czasu przyjazdu i wyjazdu dla punktów. Aby uzyskać najlepsze wyniki, TrackRoad zaleca używanie DispatchMode Optima przy oknach czasowych.

Kluczowe zmienne

• CanArriveEarly
• TimeConstraintArrival
• TimeConstraintDeparture

Jeśli Twój język nie potrafi przekazać wartości datetime null, użyj 0001-01-01T00:00:00. TrackRoad traktuje daty mniejsze lub równe 1 stycznia 2012 jako null.

Przeczytaj więcej: Optymalizacja tras z oknami czasowymi

Jak rozumieć wyniki Dispatch#

Dispatch zwraca zoptymalizowane trasy dla każdego pojazdu. Każdy wynik pojazdu zawiera uporządkowane punkty z metadanymi takimi jak:

• Sekwencja punktów
• MatchCode i jakość dopasowania adresu
• Szerokość i długość geograficzna
• Czas i dystans do następnego punktu

Wskazówki dotyczące wydajności i skalowania

• Grupuj punkty, kiedy to możliwe, zamiast optymalizować jedną trasę naraz
• Podawaj dokładny czas obsługi i okna czasowe, aby uzyskać realistyczne wyniki
• Używaj trybu Optima dla harmonogramów z ograniczeniami
• Zwiększ MinimumOptimization dla lepszej jakości przy większych zbiorach punktów
• Używaj dispatchingu wielopojazdowego dla routingu floty zamiast osobnych żądań

Przykład REST JSON (X-API-Key → Dispatch)#

Ten przykład pokazuje zalecany przepływ REST z użyciem X-API-Key (TrackServiceKey).

Krok 1 — Ustaw nagłówki uwierzytelniania

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

Krok 2 — Dispatch (optymalizacja tras)

Dispatch przyjmuje pojazdy oraz punkty i zwraca zoptymalizowane trasy. Ten przykład używa jednego pojazdu i wielu punktów.

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

Wskazówka: Dla okien czasowych używaj DispatchMode = Optima. Jeśli integracja nie może wysyłać wartości null, użyj domyślnej daty, takiej jak 0001-01-01T00:00:00, aby reprezentować “null”.

Przykład curl

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 i Logout są dostępne dla zachowania zgodności wstecznej. W większości integracji używaj X-API-Key (TrackServiceKey) w każdym żądaniu.

Przykład SOAP C# (SessionIDHeader → Dispatch)

Uwierzytelnianie SOAP w TrackRoad używa SessionIDHeader.SessionID = TrackServiceKey. Zobacz uwierzytelnianie , aby poznać pełne szczegóły.

Endpoint SOAP WSDL

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

Przykład SOAP C# krok po kroku

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

Uwagi

• Używaj trybu Optima dla okien czasowych i harmonogramów.
• Podawaj godziny pracy kierowcy (TimeIn, TimeOut), aby routing był realistyczny.
• Jeśli nie możesz podać wartości datetime null, użyj DateTime.MinValue albo reguły daty null.

Rozwiązywanie problemów: typowe błędy API i sposoby ich naprawy#

Optymalizacja tras to problem oparty na ograniczeniach. Jeśli podasz nieprawidłowe adresy lub niemożliwe ograniczenia, takie jak bardzo wąskie okna czasowe, zbyt mało pojazdów lub przekroczone limity pojemności, silnik Dispatch może zwrócić błędy albo niekompletne trasy.

1) “Dispatch failed” lub Success = false

• Nieprawidłowe lub niepełne adresy punktów
• Niemożliwe okna czasowe
• Zbyt krótkie godziny pracy pojazdu
• Zbyt mało pojazdów, aby obsłużyć wszystkie punkty
• Przekroczone ograniczenia pojemności

2) Niektóre punkty znikają z tras

Typowe przyczyny:

• Zbyt restrykcyjne okna czasowe
• Zbyt restrykcyjne godziny pracy
• Przekroczona pojemność
• Czas obsługi powoduje, że harmonogram staje się niewykonalny

3) Nieprawidłowe lub niskiej jakości dopasowania adresów (problemy MatchCode)

• Podawaj pełne adresy (ulica, miasto, kod pocztowy, kraj)
• Jeśli masz już współrzędne, wyślij Latitude i Longitude
• W razie potrzeby weryfikuj punkty geokodowaniem przed Dispatch

4) Okna czasowe są niewykonalne

• Użyj DispatchMode Optima
• Poszerz okna czasowe
• Pozwól na wcześniejszy przyjazd (CanArriveEarly = true), jeśli to właściwe
• Dodaj więcej pojazdów albo wydłuż godziny pracy pojazdów

5) Za mało pojazdów lub niepełny routing floty

• Dodaj więcej pojazdów
• Zwiększ pojemność (waga i objętość)
• Wydłuż godziny pracy
• Użyj DispatchMode MinimumVehicles, jeśli celem jest minimalizacja wymaganej liczby pojazdów

6) API zwraca “key invalid” (uwierzytelnianie)

Uwierzytelnianie TrackRoad używa stabilnego klucza API o nazwie TrackServiceKey. “Key invalid” zwykle oznacza, że klucz jest brakujący, niepoprawny albo wysłany w złym miejscu.

• REST: wyślij X-API-Key: TrackServiceKey
• SOAP: wyślij SessionIDHeader.SessionID = TrackServiceKey
• Zobacz uwierzytelnianie API , aby poznać dokładne szczegóły.