User Tools

Site Tools


public:realtime:external_api:static_schedules

Statyczne dane (rozkłady)

jakdojade interpretuje wiele różnych formatów/eksportów danych dostępnych na polskim rynku.

Wbrew pozorom najlepszym rozwiązaniem nie jest wcale popularny na świecie GTFS - ze względu na swoją czysto kursową postać i brak informacji potrzebnych do pełnej rekonstrukcji tabliczek przystankowych (np. opisy i symbole dla poszczególnych kursów). Dodatkowo w takim przypadku otrzymanie poprawnego rozkładu leży po stronie instytucji/osób które mają dostęp do danych źródłowych.

Często otrzymanie poprawnych zbiorów dat (informacji kiedy dany pojazd kursuje - dana niezbędna do uzupełnienia GTFS) jest trudne - bo sposób zapisywania tej informacji jest zupełnie inny niż ten wynikający z mechanizmów przyjętych w programach w których rozkłady są układane.

Plik eksportu

Eksport danych powinien składać się z jednego pliku zip na każdy rozkład.
Plik zip powinien w nazwie zawierać daty obowiązywania, oddzielone '_': [dataOd]_[dataDo].zip.
Data powinna być zapisana w formacie YYYYMMdd.
Przykładowana nazwa pliku 20141201_20141230.zip.

Zawartość eksportu

W spakowanym pliku powinny znajdować się pliki:

  1. schedule.json: ogólne informacje o rozkładzie
  2. zones.json: informacje o strefach
  3. stops_points.json: informacje o słupkach przystankowych
  4. shapes.json: informacje o kształtach pomiedzy-przystankowych
  5. services.json: informacje o kalendarzu (typy dni/dokładne daty kursowania)
  6. line_*.json: rozkład dla linii

schedule.json

PlantUML Graph

Ogólny obiekt zawierający rozkład i opcjonalnie przystanki oraz kształty tras.

  • scheduleName: nazwa rozkładu (opcjonalna)
  • scheduleValidFrom: data od której rozkład obowiązuje - jeżeli pusta oznacza 'od zawsze' (nie jest istotna)
  • scheduleValidTo: data do której rozkład obowiązuje - jeżeli pusta oznacza 'do zawsze' (nie jest istotna)
  • scheduleVersion: oznacza unikalną wersję rozkładu (potrzebna do określenia czy nie zmienił się w ciągu dnia) - może to być np. czas ostatniej generacji z dokładnością do do sekund/minut - w razie aktualizacji będzie wiadomo czy należy go przetwarzać.
  • formatVersion: wersja formatu

stops_points.json

PlantUML Graph

Zawiera informacje o słupku przystankowym.

  • stopPointName: nazwa przystanku
  • stopPointCode: kod słupka (unikalny w ramach całej sieci)
  • x_lon: współrzędna geograficzna słupka (WGS84)
  • y_lat: współrzędna geograficzna słupka (WGS84)
  • stopPointStreet: nazwa ulicy na której znajduje się słupek
  • stopPointCity: nazwa miasta/miejscowości w której znajduje się słupek (jeśli inna niż miasto przewoźnika)
  • stopPointCodeInGroup: jeśli podróżnym prezentowane są unikalne kody przystanków wewnątrz grupy o tej samej nazwie np. RONDO ŚRÓDKA 01, RONDO ŚRÓDKA 02… ('nazwa przystanku' razem z 'kodem w grupie' jest tak samo unikalna jak 'kod przystanku')
  • stopPointZoneId: jeśli organizator transportu wiąże strefy taryfowe z przystankami wpisanie tutaj numeru strefy spowoduje, że wszystkie linie przejeżdząje przez ten przystanek będą w tej strefie (chyba że jakiś kurs linii ma zdefiniowany wyjątek strefowy)

shapes.json

PlantUML Graph

Zawiera informacje o kształcie trasy dla wszystkich pojazdów przejeżdżających pomiędzy danymi przystankami.

  • shapeFromStopCode: kod słupka z którego dany pojazd wyrusza
  • shapeToStopCode: kod słupka na który dany pojazd przyjeżdża
  • shapeCoordinates: lista współrzędnych geograficzna twożących kształt

services.json

PlantUML Graph

Reprezentuje informacje na temat terminów kursowania. Są na to dwa sposoby: określenie opisowe (dni tygodnia, święta itp.) lub lista konkretnych dat.

  • serviceId: identyfikator serwisu
  • serviceDescription: opisowe określenie terminu kursowania (np. “od poniedziałku do wtorku oprócz świąt”, “weekendy i święta” lub “dni szkolne”)
  • serviceDays: lista dni w które kurs jeździ
  • lineSymbol: jeśli dana usługa jest specyficzna tylko dla konkretnej linii

ServiceDay

  • serviceDay: dzień w którym kurs jeździ (data)

zones.json

PlantUML Graph

Zawiera listę stref biletowych.

  • zoneId: id strefy
  • zoneName: nazwa strefy
  • zoneDescription: opis strefy

line_*.json

PlantUML Graph

Line

Linia komunikacyjna.

Course

kurs pojazdu na linii.

  • courseId: unikalny w ramach jednego dnia indentyfikator kursu (np id z bazy BusMan CB), taki sam identyfikator powinien być podany w zasobach dynamicznych z lokalizacjami pojazdów.
  • courseBirgade: brygada na której obecny kurs wykonuje przejazd
  • courseNumberOnBirgade: ?
  • courseLowFloor: jeśli true to kurs realizowany jest pojazdem niskopodłogowym (domyślnie false)
  • mainVariant: true jeśli to wariant główny trasy (domyślnie false)
  • variantDirection: 0, 1?

CourseStop

przystanek na kursie

  • courseStopIndex: indeks przystanku w kursie (potrzebny m.in. do definiowania markerów)
  • stopCode: kod słupka na którym dany autobus staje
  • courseStopArrivalTime: czas przyjazdu pojazdu na przystanek - czas dnia z dokładnością sekundową. Pole Powinno być puste tylko na pierwszym przystanku (wyjazd na trasę). Format HH:mm:ss np 12:23:00.

Czas może być większy niż 24h - jeśli mamy do czynienia z kursami linii nocnych np. 25:34 - oznacza 01:34 dnia następnego ale wykonywana jest przez pojazd którego kurs (brygada) logicznie należy do poprzedniego dnia np. kurs 25:34 dla typu dnia 'pn-pt' będzie wykonywany w noce: poniedziałek/wtorek,wtorek/środa,środa/czwartek,czwartek/piątek,piątek/sobota o godz. 01:34.

  • courseStopDepartureTime: czas odjazdu kursu. Może być puste jedynie kiedy to koniec kursu (ostatni przytanek na kursie). Format HH:mm:ss np 25:23:00.
  • courseStopOnDemand: jeśli true to kurs na przystanku zatrzymuje się 'na żądanie'
  • courseStopZoneId: kod strefy taryfowej (domyślnie strefa z przystanku (obiekt Stop) - może być zmieniona dla tego konkretnego kursu)
  • courseHeadsign: nazwa wyświetlana na górze pojazdu - nazwa kierunku. Jeżeli puste to przyjmowana jest nazwa ostatniego przystanku

Marker

oznaczenie czasu wraz z opisem. Może zawierać informacje o trasie kursowania, lub czasie np. '* - kursuje tylko w święta i 02.05', lub 'x - kursuje tylko do przystanku X'.

  • markerSymbol: znak odpowiadający oznaczeniu (np. A, X, *, #)
  • markerDescription: słowny opis oznaczenia np. 'kurs do przystanku X', 'do przystanku A po trasie, potem zjazd do zajezdni Z'
  • markerFromStopIndex: indeks przystanku (w kursie) od którego oznaczenie obowiązuje (domyślnie od pierwszego)
  • markerToStopIndex: indeks przystanku (w kursie) do którego oznaczenie obowiązuje (domyślnie do ostatniego)

JSON

Przedstawiony JSON jest zgodny z przykładowym modelem klas opisanym wcześniej.

line_1.json
{
  "lineSymbol": "1",
  "lineTimetableValidFrom": "2014.12.15 00:00",
  "lineVehicleType": "VEHICLE_TYPE_BUS",
  "lineType": "FAST ZONE",
  "lineCourses": [
    {
      "courseId": "12345",
      "courseBrigade": "002-01",
      "courseLowFloor": true,
      "mainVariant": true,
      "variantDirection": 8,
      "serviceId": "s34285",
      "courseStops": [
        {
          "courseStopIndex": 0,
          "courseStopDepartureTime": "17:11:00",
          "stopCode": "LIC-2194"
        },
        {
          "courseStopIndex": 1,
          "courseStopDepartureTime": "17:12:00",
          "courseStopArrivalTime": "17:12:00",
          "stopCode": "1550"
        },
        {
          "courseStopIndex": 2,
          "courseStopDepartureTime": "17:14:00",
          "courseStopArrivalTime": "17:14:00",
          "stopCode": "1555"
        },
        {
          "courseStopIndex": 3,
          "courseStopDepartureTime": "17:16:00",
          "courseStopArrivalTime": "17:16:00",          
          "stopCode": "1519"
        },
        {
          "courseStopIndex": 4,
          "courseStopArrivalTime": "17:18:00",       
          "stopCode": "5006"
        }
      ]
    },
    {
      "courseId": "22345",
      "courseBrigade": "002-03",
      "serviceId": "s34285",
      "courseStops": [
        {
          "courseStopIndex": 0,
          "courseStopDepartureTime": "17:21:00",          
          "stopCode": "LIC-2194"
        },
        {
          "courseStopIndex": 1,
          "courseStopArrivalTime": "17:22:00",
          "courseStopDepartureTime": "17:22:30",
          "stopCode": "1550"
        },
        {
          "courseStopIndex": 2,
          "courseStopArrivalTime": "17:24:00",
          "courseStopDepartureTime": "17:24:30",
          "stopCode": "1555"
        },
        {
          "courseStopIndex": 3,
          "courseStopArrivalTime": "17:26:00",
          "courseStopDepartureTime": "17:26:30",
          "stopCode": "1519"
        },
        {
          "courseStopIndex": 4,
          "courseStopArrivalTime": "17:28:00",
          "stopCode": "5006"
        }
      ]
    },
    {
      "courseId": "32421",
      "courseLowFloor": true,
      "courseMarkers": [
        {
          "markerSymbol": "*",
          "markerDescription": "kurs do zajezdnii - Madalińskiego",
          "markerFromStopIndex": 0,
          "markerToStopIndex": 1
        }
      ],
      "courseStops": [
        {
          "courseStopIndex": 0,
          "courseStopDepartureTime": "17:31:00",
          "stopCode": "LIC-2194"
        },
        {
          "courseStopIndex": 1,
          "courseStopDepartureTime": "17:32:00",
          "courseStopArrivalTime": "17:32:00",
          "stopCode": "1550"
        },
        {
          "courseStopIndex": 2,
          "courseStopArrivalTime": "17:38:00",
          "stopCode": "37006"
        }
      ]
    }
  ],
  ...
}

Stops

stops_points.json
{
  "stopsPoints": [
    {
      "stopPointName": "Liceum",
      "stopPointCode": "LIC-451",
      "stopPointCoordinate":
        {
          "y_lat": 52.408555,
          "x_lon": 16.934034
        },
      "stopPointStreet": "Niepodległości",
      "stopPointCodeInGroup": "1",
      "stopPointZoneId": "1"
    },
    {
      "stopPointName": "Straż pożarna",
      "stopPointCode": "SPX-998",
      "stopPointCoordinate":
        {
          "y_lat": 51.408555,
          "x_lon": 15.934034
        },
      "stopPointStreet": "Główna",
      "stopPointZoneId": "2"
    },
    {
      "stopPointName": "Ratusz",
      "stopPointCode": "RAT-821",
      "stopPointCoordinate":
        {
          "y_lat": 50.408555,
          "x_lon": 14.934034
        },
      "stopPointStreet": "Ratuszowa"
    }
  ]
}

Services

services.json
{
  "services": [
    {
      "serviceId": "s34285",
      "serviceDays": [
        {
          "serviceDay": "06.10.2013"
        },
        {
          "serviceDay": "13.10.2013"
        },
        {
          "serviceDay": "20.10.2013"
        },
        {
          "serviceDay": "27.10.2013"
        }
      ]
    },
    {
      "serviceId": "s68932",
      "serviceDescription": "kursuje od poniedziałku do piątku oprócz świąt"
    },
    ....
   ]
}

Shapes

shapes.json
{
  "shapes" : [{
      "shapeFromStopCode" : "KAPO-01",
      "shapeToStopCode" : "RJNJ-01",
      "shapeCoordinates": [
        {
          "y_lat" : 52.516493360235,
          "x_lon" : 17.604603767395
        }, {
          "y_lat" : 52.536493360235,
          "x_lon" : 17.624603767395
        }, {
          "y_lat" : 52.546493360235,
          "x_lon" : 17.634603767395
        }, {
          "y_lat" : 52.556493360235,
          "x_lon" : 17.624603767395
        }, {
          "y_lat" : 52.566493360235,
          "x_lon" : 17.634603767395
        }
      ]
    }, {
      "shapeFromStopCode" : "RJNJ-02",
      "shapeToStopCode" : "KAPO-02",
      "shapeCoordinates": [
        {
          "y_lat" : 52.567493360235,
          "x_lon" : 17.635603767395
        }, {
          "y_lat" : 52.557493360235,
          "x_lon" : 17.625603767395
        }, {
          "y_lat" : 52.537493360235,
          "x_lon" : 17.625603767395
        }, {
          "y_lat" : 52.517493360235,
          "x_lon" : 17.605603767395
        }
      ]
    }
  ]
}
public/realtime/external_api/static_schedules.txt · Last modified: 2016/10/05 15:57 by lukasz.malepszak