SmartRoad API

Dokumentacja systemu optymalizacji tras pojazdów

System SmartRoad

SmartRoad to aplikacja umożliwiająca optymalizację tras przejazdu dla wielu pojazdów. System przyjmuje zestaw punktów geograficznych (koordynat) oraz opcjonalne ograniczenia czasowe i zwraca zoptymalizowaną kolejność odwiedzania punktów dla każdego pojazdu.

Aplikacja nie posiada interfejsu graficznego (GUI) – komunikacja odbywa się wyłącznie poprzez REST API z wykorzystaniem formatu JSON.

Opis procesu optymalizacji

Proces optymalizacji trasy jest dwuetapowy:

  1. Wysłanie danych → otrzymanie indywidualnego optimizationId
  2. Pobranie wyniku optymalizacji za pomocą ID

Wysłanie danych do optymalizacji POST

Użytkownik wysyła JSON zawierający:

  • Punkt startowy
  • Listę pojazdów
  • Listę punktów
  • Przedział czasowy (opcjonalnie)

POST https://smartroadapi.postdata.pl?api-key=<API_KEY>

Struktura żądania

  • start: name, latitude, longitude
  • vehicles: registrationNumber
  • points: coordinates (name, latitude, longitude), timeWindow (from, to)
{
  "start": { "name": "Główne Miasto w Gdańsku", "latitude": 54.348, "longitude": 18.653 },
  "vehicles": [{ "registrationNumber": "ABC1234" }, { "registrationNumber": "XYZ5678" }],
  "points": [
    { "coordinates": { "name": "Rynek Starego Miasta w Warszawie", "latitude": 52.2497, "longitude": 21.012 }, "timeWindow": {"from": "08:00:00", "to": "12:00:00"} },
    { "coordinates": { "name": "Rynek Główny w Krakowie", "latitude": 50.0614, "longitude": 19.9366 }, "timeWindow": {"from": "18:00:00", "to": "22:00:00"} },
    { "coordinates": { "name": "Stary Rynek w Poznaniu", "latitude": 52.4084, "longitude": 16.9342 }, "timeWindow": {"from": "10:00:00", "to": "14:00:00"} },
    { "coordinates": { "name": "Rynek we Wrocławiu", "latitude": 51.109, "longitude": 17.0325 }, "timeWindow": {"from": "12:00:00", "to": "18:00:00"} }
  ]
}

Nadanie identyfikatora optymalizacji

System zwraca identyfikator zapytania, umożliwiający śledzenie statusu i pobranie wyników.

{
  "data": { "optimizationId": "019d2457-1a66-7abe-a0e6-1824c3e42051" },
  "message": null,
  "type": 1,
  "isSuccess": true
}

Pobranie wyniku GET

Identyfikator optimizationId umożliwia monitorowanie przebiegu procesu optymalizacji oraz pobranie jego wyników. W zależności od stanu przetwarzania system zwraca informację o statusie lub docelowy wynik optymalizacji. Wynik optymalizacji przechowywany jest w bazie przez 30 dni – po tym czasie zostaje trwale usunięty z bazy danych.

GET https://smartroadapi.postdata.pl/{optimizationId}?api-key=<API_KEY>

W trakcie optymalizacji

{
  "message": "Route optimization is: New.",
  "type": 1,
  "isSuccess": true
}

Po zakończeniu

{
  "data": {
    "vehicles": [{
      "registrationNumber": "ABC1234",
      "tracePoints": [
        { "isDepot": true, "arrivalTime": "00:00:00", "pointCoordinates": {"name": "Główne Miasto w Gdańsku", "latitude": 54.348, "longitude": 18.653} },
        { "isDepot": false, "arrivalTime": "08:00:00", "pointCoordinates": {"name": "Rynek Starego Miasta w Warszawie", "latitude": 52.2497, "longitude": 21.012} },
        { "isDepot": false, "arrivalTime": "11:08:12", "pointCoordinates": {"name": "Stary Rynek w Poznaniu", "latitude": 52.4084, "longitude": 16.9342} },
        { "isDepot": false, "arrivalTime": "13:24:22", "pointCoordinates": {"name": "Rynek we Wrocławiu", "latitude": 51.109, "longitude": 17.0325} },
        { "isDepot": false, "arrivalTime": "18:00:00", "pointCoordinates": {"name": "Rynek Główny w Krakowie", "latitude": 50.0614, "longitude": 19.9366} },
        { "isDepot": true, "arrivalTime": "23:53:21", "pointCoordinates": {"name": "Główne Miasto w Gdańsku", "latitude": 54.348, "longitude": 18.653} }
      ]
    }],
    "droppedPoints": []
  },
  "message": "Route optimization completed successfully.",
  "type": 1,
  "isSuccess": true
}

Ograniczenia i walidacje danych

Pojazdy

Tablica vehicles nie może być pusta

Tablica vehicles, składająca się z pojazdów, nie może być pusta, tj. musi być podany co najmniej jeden pojazd.

{
    "message": "'Vehicles' must not be empty.",
    "type": 2,
    "isSuccess": false
}
Maksymalna ilość elementów w tablicy vehicles wynosi 10

Maksymalna ilość elementów, tj. deklarowanych pojazdów, dla tablicy vehicles wynosi 10.

{
    "message": "There cannot be more than 10 vehicles.",
    "type": 2,
    "isSuccess": false
}
Wartość pola registrationNumber nie może być pusta

Wartość pola registrationNumber nie może być pusta.

{
    "message": "'Registration Number' must not be empty.",
    "type": 2,
    "isSuccess": false
}
Wartość pola registrationNumber musi być unikalna

Wartość pola registrationNumber musi być unikalna.

{
    "message": "Vehicle registrations must be unique.",
    "type": 2,
    "isSuccess": false
}
Wartość pola registrationNumber może składać się z maksymalnie 15 znaków

Wartość pola registrationNumber może składać się z maksymalnie 15 znaków.

{
    "message": "The length of 'Registration Number' must be 15 characters or fewer. You entered 28 characters.",
    "type": 2,
    "isSuccess": false
}

Punkty

Tablica points nie może być pusta

Tablica points, składająca się z koordynat, nie może być pusta, tj. musi być podany co najmniej jeden punkt docelowy.

{
    "message": "'Points' must not be empty.",
    "type": 2,
    "isSuccess": false
}
Maksymalna ilość elementów w tablicy points wynosi 100

Maksymalna ilość elementów, tj. deklarowanych punktów, dla tablicy points wynosi 100.

{
    "message": "There cannot be more than 100 points.",
    "type": 2,
    "isSuccess": false
}
Obiekt start jest wymagany

Obiekt start będący punktem początkowym oraz kończącym trasę jest wymagany. Składa się z pól name, latitude, longitude.

Zakres wartości pola latitude

Wartość pola latitude musi mieścić się w zakresie wartości nie mniejszej niż 49 i jednocześnie mniejszej niż 55.

{
    "message": "'Coordinates Latitude' must be greater than or equal to '49'.",
    "type": 2,
    "isSuccess": false
}
Zakres wartości pola longitude

Wartość pola longitude musi mieścić się w zakresie wartości nie mniejszej niż 14 i jednocześnie mniejszej niż 25.

{
    "message": "'Coordinates Longitude' must be greater than or equal to '14'.",
    "type": 2,
    "isSuccess": false
}
Wartość pola name może składać się z maksymalnie 50 znaków

Wartość pola name może składać się z maksymalnie 50 znaków.

{
    "message": "The length of 'Coordinates Name' must be 50 characters or fewer. You entered 64 characters.",
    "type": 2,
    "isSuccess": false
}

Czas

Obiekt timeWindow jest opcjonalny

Obiekt timeWindow definiuje zakres czasu dostępności punktu. Brak definicji oznacza dostępność cały dzień. Składa się z pól from i to.

Ograniczenie zakresu wartości pól czasu

Zakłada się, że dostępność danego punktu definiowana jest w obrębie jednego dnia. W związku z tym wartość pola from nie może być większa niż wartość pola to. Walidacja dotyczy pól wchodzących w skład obiektu timeWindow. Wartości czasu należy podawać w formacie HH:MM:SS.

{
    "message": "TimeWindow.From cannot be greater than TimeWindow.To",
    "type": 2,
    "isSuccess": false
}

Maksymalny czas wykonania optymalizacji

Zakłada się, że maksymalny czas na zwrócenie wyniku optymalizacji wynosi około 20 minut, przy czym maksymalny czas poświęcony na proces optymalizacji wynosi 15 minut. Po jego upływie optymalizator zwraca najlepsze rozwiązanie uzyskane w dostępnym czasie, nawet jeśli proces optymalizacji nie został w pełni zakończony.

Licencje Open Source

  1. OpenStreetMap