RATA.DIGITRAFFIC.FI

Tämän avoimen rajapinnan tarkoituksena on jakaa tietoa Suomen rataverkolla kulkevien junien aikatauluista, sijainneista, kokoonpanoista sekä täsmällisyystiedoista. Palvelun omistaa Liikennevirasto ja tietolähteenä toimii Liikenneviraston ratakapasiteetin ja liikenteenohjauksen Liike-perheen sovellukset sekä matkustajainformaatiojärjestelmä MIKU.

LIIKE REAALI LOKI

Rajapinnasta saatavien tietojen avulla on mahdollista vastata esimerkiksi seuraaviin kysymyksiin:

Onko junani aikataulussa?
Missä junani sijaitsee tällä hetkellä?
Millä junalla voin matkustaa paikasta A paikkaan B ajanhetkenä C?
Mitkä junat lähtevät ja saapuvat asemalta seuraavaksi?
Mistä vaunuista junani koostuu?
Mitä palveluita vaunut tarjoavat?
Oliko juna aikataulussa esimerkiksi kaksi kuukautta sitten?

Saatavilla on myös Swagger-dokumentaatio

Rajapinnasta saatavien tietojen käyttölupa on Creative Commons Nimeä 4.0.

Sisältö

Yleistä
Rajapinnat
Vastaustyypit
Versionumeroiden käyttö
Avoimen datan käyttölupa

Yleistä

Palvelun kehittäjäyhteisö

Jos sinulla on kysymyksiä tietosisällöstä, kehitysehdotuksia tai tarvitset apua rajapinnan käyttöön, palvelulle on perustettu julkinen rata.digitraffic.fi Google-ryhmä.

Suunnittellut ominaisuudet

Listassa ensimmäisenä oleva pyritään toteuttamaan ensimmäisenä. Ominaisuuksia saatetaan vielä hyllyttää esim. operaattorien liikesalaisuussyistä tai odottamattomien teknisten vaikeuksien takia.

Otamme mielellämme vastaan kehitysehdotuksia rata.digitraffic.fi -keskusteluryhmässä

Suunnitteilla olevat ominaisuudet:

Siri-sanomat
- Sisältävät asemakuulutusten kaltaista tietoa. Esimerkiksi “Raide 5 on remontissa Pasilassa”.
Routeset-sanomat
- Kun juna varaa edestään rataosia kuljettavaksi, tästä syntyy Routeset-sanomia. Myös TrackSet- ja TrackConfirm-sanomat pyritään julkaisemaan.

Toteutetut ominaisuudet

16.11.2018
- Aikataulukaudet ja muutosajankohdat
30.10.2018
- Kaikki paitsi metadata-tiedot saatavilla MQTT:n kautta
12.9.2018
- Vanhat GPS-sijainnit zip-paketteina
13.8.2018
- Junan “myöhässä”-toiminallisuus
21.5.2018
- Junan sijaintihistorian haku (/train-locations/<departure_date>/<train_number>)
12.2.2018
- Kokoonpanojen haku versionumeron avulla
5.2.2018
- GraphQL. Tapa filtteröidä, rajoittaa ja yhdistellä vastauksia
1.2.2018
- Uusi tyyli etusivulle
- Vanhat junat ja kokoonpanot zip-paketteina
12.12.2017
- Junien GPS-sijainnit
03.10.2017
- Junien tiedot GTFS-muodossa
22.08.2017
- Swagger-dokumentaatio
20.06.2017
- MIKU-järjestelmän käsiennusteet (Etelä-Suomen junien tarkemmat ennusteet)
18.05.2017
- Säännöllisen ja tulevaisuuden kiireellisen kapasiteetin jakaminen
30.03.2017
- Syytietojen (eli myöhästymissyyn) kolmas taso
24.02.2017
- Junan lähtövalmiusilmoitus (trainReady).
31.01.2017
- Junan aikataulun hyväksymishetki (timeTableAcceptanceDate).
24.01.2017
- Rajapinta, joka palauttaa kaikki muuttuneet junat (/trains?version).
11.01.2017
- Julkaistu junan aikataulun ratakapasiteettihakemuksen tyyppi.
02.01.2017
- Syyluokkiin ja -koodeihin viitataan id:llä.
25.11.2016
- Rajoitettu aikataulurajapinnan käyttöä. Lue alhaalta rajapintakuvauksesta lisätietoa.
23.11.2016
- Uusi algoritmi ennusteiden tuottamiseen
15.06.2016
- Kulkutietoviestit asemapaikoittain ja raideosuuksittain
16.03.2016
- Mahdollisuus kuunnella junia websocketilla
- Herätepisteet
29.12.2015
- Toteumatiedon haku aikavälirajoituksin
18.11.2015
- Aikatauluttomien junien kulkutietoviestit
08.10.2015
- Raideosuudet
- Kulkutietoviestit
- Liikennepaikkaluetteloon lisää tietoja
05.03.2015
- Operaattoriluettelo junanumeroavaruuksilla
- Liikennepaikkaluettelo
- Rajoitetun kokokoonpanotietojen julkaiseminen.
- Reaaliaikaisen liikennetilanteen ja toteumatiedon julkaiseminen.
- Voimassa olevan kapasiteetin julkaiseminen.

HTTPS

Rajapinta tukee sekä HTTP- että HTTPS-muotoa. Suosittelemme HTTPS:n käyttöä.

Dataa tukevat rajapinnat

https://rata.digitraffic.fi/infra-api/, josta löytyy Suomen rautatieverkon yksityiskohtainen kuvaus.
https://rata.digitraffic.fi/jeti-api/, josta löytyy tietoja rataverkkoon kohdistuvista huoltotöistä.

Rajapinnat

Avoimen datan rajapinta tarjoaa sekä on REST- että WebSocket-rajapinnat, joiden vastaukset ovat JSON-formaattia. Rajapinnan tulokset tallennetaan välimuistiin, jossa säilytysaika riippuu tehdystä kyselystä ja muodostetusta vastauksesta, esimerkiksi asematiedot pidetään välimuistissa pidempään kuin reaaliaikaiset kulkutiedot.

Rajapinta on jaettu kuuteen osaan:

Junien tiedot (/trains)
Aktiivisten junien seuranta (/live-trains))
Junan GPS-sijainnit (/train-locations)
Kulkutietoviestit (/train-tracking)
Kokoopanotiedot (/compositions)
Metatiedot (/metadata)

Palvelussa on junien aikataulu- ja toteumatiedot noin 720 päivää taaksepäin. Tulevaisuuteen tiedot ovat saatavilla niin pitkälle kuin rataviranomainen on hyväksynyt operaattoreiden aikatauluhakemukset. Rajapinnasta saatavat aikataulut voivat muuttua aikataulujen muutosajankohdissa, joita on noin kolmen kuukauden välein. Tämä koskee erityisesti tavaraliikennettä, mutta myös henkilöliikenteeseen voi tulla muutoksia näissä ajankohdissa. Tämän vuoksi sellaisten junien aikatauluihin, joiden lähtöpäivä on seuraavan muutosajankohdan jälkeen, ei voi täydellä varmuudella luottaa.

Käytettävä versio rajapinnasta kerrotaan osoitteessa. Esimerkiksi http://rata.digitraffic.fi/api/v1/trains/latest/1, jossa v1 on rajapinnan versiotunnus.

Kaikki aikaleimat ovat ISO-8601:n mukaisia (esimerkiksi 2018-03-28T04:35:00.000Z). Huomaa, että aikaleimoissa aikavyökkeenä on Z eli ne ovat UTC-aikaa, eivät Suomen aikaa.

Rajapinnan käytössä on yhtäaikaiseen käyttöön liittyviä rajoituksia. Yhdestä ip-osoitteesta voi olla maksimissaan kaksi yhtäaikaista yhteyttä ja tehdä viisi pyyntöä sekunnissa. Rajoituksen ylittyessä palvelu viivästyttää pyyntöjä tai antaa HTTP 429 -virheen.

Palvelun tilaa voi seurata osoitteessa https://nodeping.com/reports/statusevents/Q8FN33750I.

Junien tiedot (/trains)

Tämän rajapinnan kautta voidaan kysyä junien aikataulutietoja. Erilaisia tapoja kysyä junien tietoja ovat: junanumero, lähtöpäivämäärä, asema ja versio.

Toteumatiedoista osa perustuu liikenteenohjauksen tekemiin käsikirjauksiin, jonka vuoksi osa toteumakirjauksista tehdään tapahtumahetkeä 0-5 minuuttia myöhemmin (siis historiaan). Esimerkiksi Tampereen ja Seinäjoen liikennepaikoilla ei saada automaattisia toteumatietoja, vaan kaikki toteumat perustuvat käsikirjauksiin.

Automaattinen ennusteen laskeminen perustuu toteutuneisiin toteumiin. Historiasta voidaan laskea keskinopeus kuinka nopeasti juna on ajanut liikennepaikkavälin tietyllä kalustolla ja tätä keskinopeutta käytetään ennustenopeutena.

Yhden junan tiedot

URL: /trains/<train_number>?departure_date=<departure_date>&version=<version>

Esimerkkejä

Kuvaus

Palauttaa yhden junan tiedot

Hakuehdot

Nimi	Formaatti	Esimerkki	Selitys
train_number	1-99999	1, 3402	Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
departure_date	date(yyyy-mm-dd)	2017-01-01	Junan ensimmäisen lähdön päivämäärä. Jos parametriksi annetaan “latest”, pyritään päättelemään juna joka on lähinnä nykyhetkeä. Päättely tehdään siten, että haetaan kaikki junanumeron junat lähipäiviltä ja etsitään nykyhetkeä lähinnä oleva aikataulurivi (rajauksella 4 tuntia taaksepäin, 16 tuntia eteenpäin. Vertailussa käytetään aikataulurivien suunnitteltuja aikoja.
version	positive integer	159123295871	Versiorajoitus. Jos juna ei ole muuttunut sitten määritellyn version, palautetaan tyhjä tulos.

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa junat -tyyppisen vastauksen.

Päivän junien tiedot

URL: /trains/<departure_date>

Esimerkki: /trains/2017-11-09

Kuvaus

Palauttaa kaikki junat halutulta lähtöpäivämäärältä.

Hakuehdot

	Nimi	Formaatti	Esimerkki
	departure_date	date (yyyy-mm-dd)	2017-01-01

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa junat-tyyppisen vastauksen.

Kaikkien junien tiedot

URL: /trains?version/<version>

Esimerkki: /trains?version=1234567891234

Kuvaus

Palauttaa kaikkien junien tiedot, jotka ovat muuttuneet sitten annetun versionumeron. Vastaus rajoitettu 2500 junaan.

Hakuehdot

	Nimi	Formaatti	Esimerkki	Selitys
	version	positive integer	159123295871	Versiorajoitus. Palauttaa kaikki junat, jotka ovat muuttuneet sitten version-version. Jos versionumeroa ei anneta, palautetaan uusimmalla versionumerolla muuttuneet junat.

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa junat-tyyppisen vastauksen.

Junien tietojen kuunteleminen (MQTT / Sockets)

Osoite rata-mqtt.digitraffic.fi, portit: 1883 (normaali), 9001 (WebSockets)

Topic: trains/<departure_date>/<train_number>/<train-category>/<train-type>/<operator>/<commuter-line>/<running-currently>/<timetable-type>

Junien tietoja voidaan myös kuunnella aktiivisen pollauksen sijasta. Tähän käytetään MQTT-protokollaa, jossa kuunnellaan haluttuja tietoja tietystä topic:sta.

Osia topic:sta voidaan korvata wildcard-merkeillä “#” ja “+”. Esimerkiksi voidaan kuunnella topic:a trains/# (kaikki tiedot) tai trains/+/5/# (yksittäisen junan tiedot). Lisätietoa täältä.

Esimerkkitoteutus Websocketilla löytyy osoitteesta http://jsfiddle.net/cb2uj7kg/

Paluuarvo

Palauttaa junat-tyyppisiä vastauksia.

Liikennepaikan junien tietojen kuunteleminen (MQTT / Sockets)

Osoite rata-mqtt.digitraffic.fi, portit: 1883 (normaali), 9001 (WebSockets)

Topic: trains-by-station/<station>/

Esimerkkitoteutus Websocketilla löytyy osoitteesta http://jsfiddle.net/a9dgjm10/1/

Paluuarvo

Palauttaa junat-tyyppisiä vastauksia.

GTFS

URL:t

Kuvaus

Junien tiedot saa myös GTFS-muodossa (General Transit Feed Specification). Paketti gtfs-all.zip sisältää kaikki junat ja gtfs-passenger.zip sisältää vain matkustajajunat.

Paketti generoidaan uusiksi päivittäin noin klo 5:00. Se sisältää kaikki tulevaisuuden junat ja menneisyyden junat viimeiseltä seitsemältä päivältä.

Paluuarvo

Palauttaa GTFS-muodossa olevan zip-paketin

Vanhat junat zip-paketteina

Vanhojen junien tiedot löytyvät zip-paketteina osoittesta /api/v1/trains/dumps/list.html

Paketin sisältämä json on saman muotoista kuin muutkin juna-vastaukset.

Uusi paketti luodaan joka kuun viides päivä.

Aktiivisten junien seuranta (/live-trains)

Liikennepaikan saapuvat ja lähtevät junat (lukumäärärajoitus)

URL: /live-trains/station/<station_shortcode>?arrived_trains=arrived_trains>&arriving_trains=arriving_trains> &departed_trains=<departed_trains>&departing_trains=<departing_trains>&version=<change_number>

Esimerkkejä:

Kuvaus

Palauttaa asemalla pysähtyvistä junista viimeksi lähteneet tai saapuneet, tai seuraavaksi lähtevät tai saapuvat.

Parametreillä voidaan rajoittaa palautettavien junien määrää. Junien kokonaismäärän rajoitus on 1000. Rajoitusparametrien yhteenlaskettu summa ei siis voi olla tätä suurempi.

Haku tehdään aikatauluaikojen perusteella taakse ja eteenpäin 24 tuntia. Tämä tarkoittaa, että harvaan liikennöidyllä liikennepaikkalla junien määrä saattaa olla pieni.

warning Koska sama juna voi kuulua useampaan joukkoon (esim. saapunut juna voi olla yhtäaikaisesti myös lähtevä), palautettava kokonaismäärä on yleensä pienempi kuin parametrien summa.

Oletuksena haulla palautetaan vain junat, jotka pysähtyvät asemalle. Parametrin “include_nonstopping” avulla voidaan palauttaa myös junat, jotka ajavat aseman ohi pysähtymättä.

Versionumerohaulla ei palauteta junasta tietoa, mikäli junan tiedot eivät ole muuttuneet kyselyiden välillä. Tämä tarkoittaa, että tulosjoukon koko voi olla tällöin pienempi.

Nimi	Formaatti	Oletusarvo	Esimerkki	Selitys
station	string		“HKI”	Aseman lyhenne. Esimerkiksi HKL, TPE, PSL. Lista lyhenteistä löytyy täältä.
arrived_trains	positive integer, 1-600	5	20	Kuinka monta saapunutta junaa palautetaan maksimissaan.
arriving_trains	positive integer, 1-600	5	20	Kuinka monta saapuvaa junaa palautetaan maksimissaan.
departed_trains	positive integer, 1-600	5	20	Kuinka monta lähtenyttä junaa palautetaan maksimissaan.
departing_trains	positive integer, 1-600	5	20	Kuinka monta lähtevää junaa palautetaan maksimissaan.
include_nonstopping	true/false	false	true	Palautetaanko aseman ohi pysähtymättä ajavat junat.
version	positive integer		159123295871	Versiorajoitus. Palauttaa kaikki junat, jotka ovat muuttuneet sitten version-version. Jos versionumeroa ei anneta, palautetaan uusimmat tiedot.

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa junat-tyyppisen vastauksen.

Liikennepaikan saapuvat ja lähtevät junat (aikavälirajoitus)

URL: /live-trains/station/<station_shortcode>?minutes_before_departure=<minutes_before_departure>&minutes_after_departure=<minutes_after_departure>&minutes_before_arrival=<minutes_before_arrival>&minutes_after_arrival=<minutes_after_arrival>&version=<change_number>&includeNonstopping=<includeNonstopping

Esimerkiksi: /live-trains/station/HKI?minutes_before_departure=15&minutes_after_departure=15&minutes_before_arrival=15&minutes_after_arrival=15

Kuvaus

Palauttaa asemalla pysähtyvistä junista viimeksi lähteneet tai saapuneet, tai seuraavaksi lähtevät tai saapuvat.

Parametreillä voidaan rajoittaa lähteviä ja saapuvia junia aikamääreiden avulla.

Aikavälirajoituksen maksimikoko on 24 tuntia. Tämä tarkoittaa, että harvaan liikennöidyllä liikennepaikkalla junien määrä saattaa olla pieni.

Oletuksena haulla palautetaan vain junat, jotka pysähtyvät asemalle. Parametrin “include_nonstopping” avulla voidaan palauttaa myös junat, jotka ajavat aseman ohi pysähtymättä.

Versionumerorajoituksen avulla voidaan suodattaa pois junat, jotka eivät ole muuttuneet sitten annetun versionumeron.

Hakuehdot

Nimi	Formaatti	Oletusarvo	Esimerkki	Selitys
station	string		“HKI”	Aseman lyhenne. Esimerkiksi HKL, TPE, PSL. Lista lyhenteistä löytyy täältä.
minutes_before_departure	positive integer, 0-1440		20	Kuinka monta minuuttia juna näytetään ennen sen lähtöä.
minutes_after_departure	positive integer, 0-1440		20	Kuinka monta minuuttia juna näytetään sen lähdön jälkeen.
minutes_before_arrival	positive integer, 0-1440		20	Kuinka monta minuuttia juna näytetään ennen sen saapumista.
minutes_after_arrival	positive integer, 0-1440		20	Kuinka monta minuuttia juna näytetään sen saapumisen jälkeen.
include_nonstopping	true/false	false	true	Palautetaanko aseman ohi pysähtymättä ajavat junat.
version	positive integer		159123295871	Versiorajoitus. Palauttaa kaikki junat, jotka ovat muuttuneet sitten version-version. Jos versionumeroa ei anneta, palautetaan uusimmat tiedot.

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa junat-tyyppisen vastauksen.

Reittiperusteinen haku

URL: /live-trains/station/<departure_station_code>/<arrival_station_code>?departure_date=<departure_date>&startDate=<startDate>&endDate=<endDate>&limit=<limit>

Esimerkki: /live-trains/station/HKI/TPE

Kuvaus

Palauttaa junat, jotka kulkevat departure_station_code- ja arrival_station_code-asemien kautta ja pysähtyvät asemilla.

Haku palauttaa vain suorat junayhteydet.. Hakutulos ei siis sisällä operaattorin tarjoamia reittivaihtoehtoja, joissa matkustaja joutuu esimerkiksi vaihtamaan junaa. Päivämääräväli rajattu maksimissaan kahteen päivään.

Oletuksena haulla palautetaan vain junat, jotka pysähtyvät asemallilla. Parametrin “include_nonstopping” avulla voidaan palauttaa myös junat, jotka ajavat asemien ohi pysähtymättä.

Hakuehdot

Nimi	Formaatti	Esimerkki	Selite
departure_station	string	“HKI”	Lähtöaseman lyhenne. Lyhennekoodit löytyvät täältä.
arrival_station	string	“RI”	Määränpääaseman lyhenne. Lyhennekoodit löytyvät täältä.
departure_date	date(yyyy-mm-dd)	2017-01-01	Päivämäärä jolta junia haetaan. Jos lähtöpäivämäärä on tyhjä, etsitään seuraavan 24 tunnin aikana lähteviä junia.
startDate	datetime(ISO 8601)	2017-01-01T23:28:59.564Z	departure_date päivämäärän sijasta voidaan määritellä aikaväli, jolta junia haetaan. Tämä parametri määrittelee aikavälin alun. Päivämääräväliä verrataan junan aikataulun mukaisen lähtöaikaan reittihaun lähtöasemalta.
endDate	datetime(ISO 8601)	2017-01-01T23:28:59.564Z	Tämä parametri määrittelee aikavälin lopun. Jos tämä parametri jätetään tyhjäksi, haetaan junia seuraavalle 24 tunnille asti.
limit	positive integer	15	Rajaa palautettavien junien määrää. Oletusarvo on 1000.
include_nonstopping	true/false	false	Palautetaanko aseman ohi pysähtymättä ajavat junat.

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa junat-tyyppisen vastauksen.

Kohta lähtevien tai saapuvien junien seuranta

URL: /live-trains?version=<version>

Esimerkkejä:

Kuvaus

Palauttaa kaikkien lähiaikoina kulussa olevien junien tiedot.

Kulussa oleva juna määritellään siten, että junan aikataulutapahtuman (suunniteltu, ennuste tai toteuma reitin jollain liikennepaikalla) hetkestä on kulunut alle 4 tuntia nykyhetkeen verrattuna.

Hakuehdot

	Nimi	Formaatti	Esimerkki	Selitys
	version	positive integer	6403053026	Versiorajoitus. Palauttaa kaikki junat, jotka ovat muuttuneet sitten version-version. Jos versionumeroa ei anneta, palautetaan uusimmat tiedot.

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa junat-tyyppisen vastauksen.

Junan GPS-sijainnit (/train-locations)

Tämän rajapinnan kautta voidaan lukea junan GPS:n tuottamaa sijaintitietoa. Kaikissa junissa ei ole GPS:ää käytössä. Jos näiden junien tarkka sijainti kiinnostaa, voidaan seuraamiseen käyttää käyttää esimerkiksi kulkutietoviestejä.

Junan GPS-laite toimittaa sijainnin tällä hetkellä 15 sekunnin välein. Sijainnit saapuvat kuitenkin eri aikoihin, joten kyselyiden cache-aika on yksi sekunti.

GPS-datan tuotto kytkeytyy päälle ja pois veturin kuljettajan toimesta, joten on mahdollista, että juna tuottaa GPS-dataa vaikka se ei olekaan ajossa. Yli 500 metriä lähimmästä radasta sijaitsevat GPS-sijainnit suodatetaan pois.

Kehittäjien kannattaa huomioida junien sijaintitietojen puutteet sovelluksissaan ja kertoa rajoitteista selkeästi myös sovellusten loppukäyttäjille. Puutteiden ja virheiden vuoksi tietojen käyttöä turvallisuuteen liittyvissä sovelluksissa kannattaa harkita tarkkaan.

Kaikkien junien sijainnit

URL: /train-locations/latest?bbox=<points>

Esimerkki 1: /train-locations/latest/
Esimerkki 2: /train-locations/latest?bbox=20,60,35,70

Kuvaus

Palauttaa kaikkien junien GPS-tiedot, jotka ovat olleet aktiivisia viimeisen 15 minuutin sisällä. Historiatietojen kysely tulossa myöhemmin.

	Nimi	Formaatti	Esimerkki	Selitys
	bbox	4 numeroa	1,1,70,70	Maantieteellinen rajaus WSG84-koordinaateilla. Kahdesta ensimmäisestä ja kahdesta viimeisestä numerosta muodostetaan rajausneliön määrittelevät pisteet

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa GPS-sijainnit -tyyppisen vastauksen.

Yhden junan sijainti

URL: /train-locations/<departure_date>/<train_number>?bbox=<points>

Esimerkkejä:

Kuvaus

Palauttaa junan GPS-sijainnit lähtöpäivänä.

Mikäli lähtöpäivänä käytetään arvoa “latest” palautetaan GPS-sijainti, joka on päivittynyt viimeisen 15 minuutin sisällä.

Nimi	Formaatti	Esimerkki	Selitys
train_number	1-99999	1	Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
departure_date	date(yyyy-mm-dd)	2017-01-01	Junan ensimmäisen lähdön päivämäärä. Jos arvo on “latest” (esim. train-locations/latest/1), palautetaan uusin, vähintään 15 minuutin sisällä päivittynyt GPS-sijainti.
bbox	4 numeroa	1,1,70,70	Maantieteellinen rajaus WSG84-koordinaateilla. Kahdesta ensimmäisestä ja kahdesta viimeisestä numerosta muodostetaan rajausneliön määrittelevät pisteet

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa GPS-sijainnit -tyyppisen vastauksen.

Sijaintien kuunteleminen (MQTT / Sockets)

Osoite rata-mqtt.digitraffic.fi, portit: 1883 (normaali), 9001 (WebSockets)

Topic: train-locations/<departure_date>/<train_number>/

Sijainteja voidaan myös kuunnella aktiivisen pollauksen sijasta. Tähän käytetään MQTT-protokollaa, jossa kuunnellaan haluttuja tietoja tietystä topic:sta.

Osia topic:sta voidaan korvata wildcard-merkeillä “#” ja “+”. Esimerkiksi voidaan kuunnella topic:a train-locations/# (kaikki tiedot) tai train-locations/+/5 (yksittäisen junan tiedot). Lisätietoa täältä

Esimerkkitoteutus Websocketilla löytyy osoitteesta http://jsfiddle.net/k8sfd4an/53/

Paluuarvo

Palauttaa GPS-sijainnit -tyyppisiä vastauksia.

Vanhat sijainnit zip-paketteina

Vanhat sijainnit löytyvät zip-paketteina osoitteesta /api/v1/train-locations/dumps/list.html

Paketin sisältämä json on saman muotoista kuin muutkin GPS-sijainti-vastaukset.

Uusi paketti luodaan joka päivä noin kello 15:30. Paketin sisältö on kaksi päivää vanhaa. Esimerkiksi 11.9.2018 15:30 luodaan päivän 9.9. junat.

Tarkempi seuranta kulkutietoviestien avulla (/train-tracking)

Liikennepaikkakohtaisten toteumien ja ennusteiden lisäksi junaa voidaan seurata ja paikantaa raideosuustarkkuudella kulkutietoviestien avulla

Kun juna saapuu raideosuudelle, aktivoituu raideosuuden anturi ja raideosuus varautuu kyseiselle junalle. Varatumisesta muodostuu “OCCUPY”-tyyppinen kulkutietoviesti. Junan poistuessa raideosuudelta syntyy puolestaan “RELEASE”-tyyppinen kulkutietoviesti. Kulkutietoviestit kertovat siis mitä raideosuuksia juna on varannut itselleen kuljettavaksi.

Kulkutietoviestejä voi seurata kahdella tapaa. Perinteisellä REST-rajapinalla (eli kuten esimerkiksi “live-trains”-liittymää) tai socketeilla (MQTT).

Kulkutietoviestejä kertyy päivittäin yli 300 000. On siis hyvä miettiä halutaanko hyödyntää kulkutietoviestejä vai luvussa 1.1 kuvattuja liikennepaikkakohtaisia toteumia ja ennusteita.

warning Datan laatu ei ole aina optimaalista. Tunnettuja välillä esiintyviä vikoja:

Seuraavan ja edellisen aseman/raideosuuden puuttuvat
Junan lähtöpäivämäärä tyhjä
Viestejä esiintyy tuplana (samat tiedot, eri id)

Kulkutietoviestit välitetään avoimen datan rajapintaan käytännössä sellaisena kuin ne saadaan kauko-ohjausjärjestelmistä. Virheellisiä viestejä lähettäviä kauko-ohjausjärjestelmiä pyritään korjaamaan jatkuvasti palautteen avulla.

Kaikkien junien seuranta

URL: /train-tracking?version=<version>

Esimerkiksi: /train-tracking?version=65403053026

Kuvaus

Palauttaa kaikki kulkutietoviestit, joiden versionumero on suurempi kuin parametrina annettuna versio.

Maksimissaan palautetaan 2500 kulkutietoviestiä.

Hakuehdot

	Nimi	Formaatti	Esimerkki	Selitys
	version	positive integer	6403053026	Versionumero, jota uudemmat kulkutietoviestit palautetaan.

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa Kulkutietoviestit-tyyppisen vastauksen.

Yhden junan seuranta

URL: /train-tracking/<departure_date>/<train_number>?version=<version>

Esimerkki: /train-tracking/2017-01-01/1?version=1000

Kuvaus

Palauttaa halutun yhden junan kulkutietoviestit.

warning Kyselyyn otetaan mukaan myös kulkutietoviestit, joilla ei ole lähtöpäivämäärää (departureDate) edellisen ja seuraavan vuorokauden rajauksella. Tällöin saattaa palautua “eilisen” kulkutietoviestejä.

Hakuehdot

Nimi	Formaatti	Esimerkki	Selitys
train_number	1-99999	1, 3402	Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
departure_date	date(yyyy-mm-dd)	2017-01-01	Junan ensimmäisen lähdön päivämäärä. Jos arvo on “latest” (esim. train-tracking/latest/1) , palauttaa uusimman lähdön kulkutietoviestejä. Palauttaa lisäksi kulkutietoviestit ilman lähtöpäivämäärää +1..-1 päivän rajauksella.
version	positive integer	159123295871	Versiorajoitus. Jos juna ei ole muuttunut sitten määritellyn version, palautetaan tyhjä tulos. Jos tyhjä, ei tehdä versiorajoitusta.

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa Kulkutietoviestit-tyyppisen vastauksen.

Liikennepaikan seuranta

URL: /train-tracking/station/<station>/<departure_date>

Esimerkki: /train-tracking/station/JY/2017-08-01

Kuvaus

Palauttaa liikennepaikan kulkutietoviestit.

Hakuehdot

	Nimi	Formaatti	Esimerkki	Selitys
	station	string	“HKI”	Liikennepaikan lyhenne. Lyhennekoodit löytyvät täältä
	departure_date	date(yyyy-mm-dd)	2017-01-01	Junan ensimmäisen lähdön päivämäärä. Palauttaa lisäksi kulkutietoviestit ilman lähtöpäivämäärää hakuparametria seuraavalta päivältä kello 16:00 asti.

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa Kulkutietoviestit-tyyppisen vastauksen.

Raideosuuden seuranta

URL: /train-tracking/station/<station>/<departure_date>/<track_section>

Esimerkkejä:

Kuvaus

Palauttaa liikennepaikan raideosuuden kulkutietoviestit.

Hakuehdot

Nimi	Formaatti	Esimerkki	Selitys
station	string	“HKI”	Liikennepaikan lyhenne. Lyhennekoodit löytyvät täältä
track_section	string	“001”	Liikennepaikan raideosuuden lyhenne. Lyhennekoodit löytyvät täältä
departure_date	date (yyyy-mm-dd)	2017-01-01	Kulkutietoviestiin liittyvän junan ensimmäisen lähdön päivämäärä. Palauttaa lisäksi kulkutietoviestit ilman lähtöpäivämäärää hakuparametria seuraavalta päivältä kello 16:00 asti. Jos arvo on “latest”, palautetaan uusimpia kulkutietoviestejä.
limit	positive integer	100	Kuinka monta uusinta kulkutietoviestiä kyselyssä palautetaan. Maksimiarvo 1000. Tämä rajaus poissulkee departure_date-rajauksen. Jos departure_date- tai limit-rajoitusta ei anneta, käytetään limit-rajoitusta.

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa Kulkutietoviestit-tyyppisen vastauksen.

Kulkutietoviestien kuunteleminen (MQTT / Sockets)

Osoite rata-mqtt.digitraffic.fi, portit: 1883 (normaali), 9001 (WebSockets)

Topic: train-tracking/<departure_date>/<train_number>/<type>/<station>/<track_section>/<previous_station>/<next_station>/<previous_track_section>/<next_track_section>/

Kulkutietoviestejä voidaan myös kuunnella aktiivisen pollauksen sijasta. Tähän käytetään MQTT-protokollaa, jossa kuunnellaan haluttuja tietoja tietystä topic:sta.

Osia topic:sta voidaan korvata wildcard-merkeillä “#” ja “+”. Esimerkiksi voidaan kuunnella topic:a train-tracking/# (kaikki tiedot) tai train-tracking/+/5/# (yksittäisen junan tiedot). Lisätietoa täältä

Esimerkkitoteutus Websocketilla löytyy osoitteesta http://jsfiddle.net/cb2uj7kg/2/

Paluuarvo

Palauttaa Kulkutietoviestit-tyyppisiä vastauksia.

Kokoonpanotiedot (/compositions)

Kokoonpanotietoja tulee junille 0-5 tuntia ennen junan lähtö tai pysähdystä, jossa kokoonpano muuttuu.

warning Moottorivaunut (esimerkiksi tyypit Sm3, Sm4, Sm5) on yleisesti ilmoitettu kokoonpanoissa vaunuina.

Junan kokoonpanohaku

URL: /compositions/<departure_date>/<train_number>

Esimerkki: /compositions/2017-01-01/1

Kuvaus

Palauttaa yksittäisen junan kokoonpanotiedot tiettynä päivämääränä.

Hakuehdot

	Nimi	Formaatti	Selitys
	train_number	1-99999	1	Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
	departure_date	date(yyyy-mm-dd)	2017-01-01	Lähtöpäivämäärä

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa Kokoonpanot-tyyppisen vastauksen.

Junien kokoonpanohaku

URL: /compositions/<departure_date>

Esimerkki: /compositions/2017-01-01

Kuvaus

Palauttaa junien kokoonpanotiedot halutulta vuorokaudelta.

Hakuehdot

	Nimi	Formaatti	Esimerkki
	departure_date	date(yyyy-mm-dd)	2017-01-01

Pakollinen Vapaaehtoinen

Paluuarvo

Palauttaa Kokoonpanot-tyyppisen vastauksen.

Kaikkien kokoonpanojen seuranta

URL: /compositions?version=<version>

Esimerkki: /compositions?version=12349873459128375

Kuvaus

Palauttaa kaikki kokoonpanot, jotka ovat uudempia kuin version

Paluuarvo

Palauttaa Kokoonpanot-tyyppisen vastauksen.

Hakuehdot

	Nimi	Formaatti	Esimerkki	Selitys
	version	positive integer	6403053026	Versiorajoitus. Palauttaa kaikki kokoonpanot, jotka ovat muuttuneet sitten `version`. Jos versionumeroa ei anneta, palautetaan uusin kokoonpano.

Pakollinen Vapaaehtoinen

Kokoonpanojen kuunteleminen (MQTT / Sockets)

Osoite rata-mqtt.digitraffic.fi, portit: 1883 (normaali), 9001 (WebSockets)

Topic: compositions/<departure_date>/<train_number>/<train_category>/<train_type>/<operator>

Kokoonpanoja voidaan myös kuunnella aktiivisen pollauksen sijasta. Tähän käytetään MQTT-protokollaa, jossa kuunnellaan haluttuja tietoja tietystä topic:sta.

Osia topic:sta voidaan korvata wildcard-merkeillä “#” ja “+”. Esimerkiksi voidaan kuunnella topic:a compositions/# (kaikki tiedot) tai compositions/+/5/# (yksittäisen junan tiedot). Lisätietoa täältä

Esimerkkitoteutus Websocketilla löytyy osoitteesta http://jsfiddle.net/cb2uj7kg/3/

Paluuarvo

Palauttaa Kokoonpanot-tyyppisiä vastauksia.

Vanhat kokoonpanot zip-paketteina

Vanhat kokoonpanot löytyvät zip-paketteina osoittesta /api/v1/compositions/dumps/list.html

Paketin sisältämä json on saman muotoista kuin muutkin kokoonpano-vastaukset.

Uusi paketti luodaan joka kuun viides päivä.

Metatiedot (/metadata)

Palvelun metatietojen hakurajapinta.

Liikennepaikkatiedot

URL: metadata/stations

Kuvaus

Palauttaa palvelun liikennepaikkojen tiedot. Tiedot päivittyvät lähdejärjestelmästä päivittäin n. klo 1:00.

Paluuarvo

Palauttaa Liikennepaikat-tyyppisen vastauksen.

Operaattoritiedot

URL: metadata/operators

Kuvaus

Palauttaa palvelun operaattoreiden tiedot. Tiedot päivittyvät lähdejärjestelmästä päivittäin n. klo 1:00.

Paluuarvo

Palauttaa Operaattorit-tyyppisen vastauksen.

Syyluokat

URL: metadata/cause-category-codes

Kuvaus

Palauttaa listan palvelussa aktiivisesti käytössä olevista syyluokista. Syyluokat ovat yleisiä kategorioita syytiedoille. Kaikki syyluokat julkaistaan AvoinData-palvelun kautta. Jos haluat listaukseen mukaan käytöstä poistuneet tai käyttöön lisättävät syyluokat, lisää osoitteeseen parametri show_inactive=true.

Paluuarvo

Palauttaa Palauttaa Syyluokat-tyyppisen vastauksen.-tyyppisen vastauksen.

Syykoodit

URL: metadata/detailed-cause-category-codes

Kuvaus

Palauttaa listan palvelussa käytössä olevista syykoodeista. Jokainen syyluokka on jaettu syykoodeihin eli syykoodi on syyluokan alempi taso. Kaikkia syykoodeja ei julkaista. Jos haluat listaukseen mukaan käytöstä poistuneet tai käyttöön lisättävät syykoodit, lisää osoitteeseen parametri show_inactive=true.

Paluuarvo

Palauttaa Syykoodit-tyyppisen vastauksen.

Kolmannen tason syykoodit

URL: metadata /third-cause-category-codes

Kuvaus

Palauttaa listan palvelussa käytössä olevista kolmannen tason syykoodeista. Kolmannen tason syykoodi on syykoodin alempi taso. Kaikkia kolmannen tason syykoodeja ei julkaista. Jos haluat listaukseen mukaan käytöstä poistuneet tai käyttöön lisättävät kolmannen tason syykoodit, lisää osoitteeseen parametri show_inactive=true.

Paluuarvo

Palauttaa Kolmannen tason syykoodit-tyyppisen vastauksen.

Junatyypit

URL: metadata/train-types

Kuvaus

Palauttaa listan palvelussa käytössä olevista junatyypeista (esim. IC, P, P). Jokaisella junatyypillä on yläkäsitteenä junalaji (esim. lähijuna, kaukojuna, tavarajuna).

Paluuarvo

Palauttaa Junatyypit-tyyppisen vastauksen.

Raideosuudet

URL: metadata/track-sections

Kuvaus

Palauttaa listan raideosuuksista. Raideosuus on pienin osuus raiteesta, jonka yksittäinen juna voi varata käyttöönsä ja näin muodostaa turvallisen kulkureitin. Raideosuudella voi siis sijaita maksimissaan yksi juna.

Lista ei kata kaikkia kulkutietoviesteissä esiintyviä raideosuuksia. Datan laatua pyritään parantamaan.

Paluuarvo

Palauttaa Raideosuudet-tyyppisen vastauksen.

Herätepisteet

URL: metadata/train-running-message-rules

Kuvaus

Herätepiste kuvaa miten kulkutietoviesti muunnetaan aikataulurivin toteumaksi taustajärjestelmässä.

Esimerkiksi kun saadaan kulkutietoviesti, joka vastaa herätepisteessä määriteltyä liikennepaikkaa, raideosuutta, varautumisen tyyppiä ja seuraavaa liikennepaikkaa, haetaan kulkutietoviestissä määritellyn junan aikataulurivi, joka vastaa herätepisteessä määritelty liikennepaikkaa ja aikataulurivityyppiä. Aikatauluriville kirjataan toteuma, joka on kulkutietoviestin aikaleima lisättynä offset-arvolla.

Paluuarvo

Palauttaa Herätepisteet-tyyppisen vastauksen.

Aikataulukaudet ja muutosajankohdat

URL: metadata/time-table-periods

Kuvaus

Aikataulukausi kuvaa ajanjaksoa, jolle haetaan säännöllisiä aikatauluja. Junan aikataulu on säännöllinen, jos sen vastauksessa on mukana arvo timetableType:"REGULAR".

Muutosajankohta on ajankohta aikataulukauden sisällä, jolloin jäljellä olevaan aikataulukauteen voidaan hakea muutoksia.

Muutosajankohtia voidaan käyttää arvioimaan junan aikataulun luotettavuutta eli sitä voiko se enää muuttua. Jos juna esimerkiksi lähtee 1.2.2018 ja seuraava muutosajankohta on 1.3.2018, junan aikataulu ei voi enää muuttua.

Paluuarvo

Palauttaa Aikataulukaudet ja muutosajankohdat-tyyppisen vastauksen.

GraphQL

GraphQL voidaan käyttää vastausten rajoittamiseen, filtteröintiin ja yhdistelyyn. GraphQL:än avulla voidaan esimerkiksi rajata mukaan vain tietyt json-kentät tai filtteröidä vastausta käyttäen mitä tahansa vastauksesta löytyvää json-kenttää.

GraphQL-kyselyitä voi kokeilla ja kirjoitella GraphiQL-työkalulla osoitteessa https://rata.digitraffic.fi/api/v1/graphql/graphiql

Jokaista kyselyä voidaan filtteröidä where-parametrillä, joka on json-query -tyyppinen string.

Esimerkkejä

Vain tiettyjen kenttien (junanumero ja operaattori) poiminta vastaukseen: kokeile

{
  viewer {
    getStationsTrainsUsingGET(station: "HKI") {
      trainNumber
      operatorShortCode
    }
  }
}

Sisällön filtteröinti (vain U-junat): kokeile

{
  viewer {
    getStationsTrainsUsingGET(station: "HKI", where:"[*commuterLineID=U]") {
      trainNumber
      commuterLineID
    }
  }
}

Ensimmäisen alkion poiminta: kokeile

{
  viewer {
    getStationsTrainsUsingGET(station: "HKI", where:"[*][0]") {
      trainNumber
      operatorShortCode
    }
  }
}

Kyselyiden yhdistäminen (junan aikataulu ja kokoonpano samassa kyselyssä): kokeile

{
  viewer {
    getTrainByTrainNumberUsingGET_1(train_number: "1", departure_date: "2017-12-28") {
      departureDate
      trainNumber
      trainType
    }
    getCompositionByTrainNumberAndDepartureDateUsingGET(train_number: "1", departure_date: "2017-12-28") {
      departureDate
      trainNumber
    }
  }
}

GraphQL-kysely omassa sovelluksessa

GraphQL-kysely on POST-tyyppinen pyyntö osoitteeseen https://rata.digitraffic.fi/api/v1/graphql/graphiql/?.

HTTP-pyyntöön tulee lisätä otsikko Content-Type: application/json

Itse kysely on jsonia POST:n bodyssä. Esimerkiksi:

{"query":"{  viewer  {    getCompositionsByDepartureDateUsingGET(departure_date:\"2017-12-26\", where:\"[*trainType=S]\"){      trainType trainNumber    }  } }"}

Kokonaisuudessaan homma näyttää REST-pluginissa tältä:

GraphQL Postmanissa

Vastaustyypit

Kaikki vastaukset ovat JSON-formaattia. Eri vastaustyypit ovat kuvattu alla.

Jokainen tyypin kenttä on kuvattu ikonilla, jotka tarkoittavat:

Required Ei voi olla tyhjä Optional Voi olla tyhjä Info Komentti, jos tarpeen

Junat

Järjestetty kenttien departureDate ja trainNumber mukaisesti nousevaan järjestykseen.

trainNumber: 1-99999 Junan numero. Esim junan “IC 59” junanumero on 59
departureDate: date Junan ensimmäisen lähdön päivämäärä
operatorUICCode: 1-9999 Junan operoiman operaattorin UIC-koodi
operatorShortCode: vr, vr-track, destia, … Lista operaattoreista löytyy täältä.
trainType: IC, P, S, …
trainCategory: lähiliikenne, kaukoliikenne, tavaraliikenne, …
commuterLineID: Z, K, N….
runningCurrently: true/false Onko juna tällä hetkellä kulussa
cancelled: true/false Totta, jos junan peruminen on tehty 10 vuorokauden sisällä. Yli 10 vuorokautta sitten peruttuja junia ei palauteta rajapinnassa laisinkaan.
version: positive integer Versionumero, jossa juna on viimeksi muuttunut
timetableType: REGULAR tai ADHOC. Kertoo onko junan aikataulu haettu säännöllisenä (REGULAR) vai kiireellisenä yksittäistä päivää koskevana (ADHOC).
timetableAcceptanceDate: datetime. Ajanhetki jolloin viranomainen on hyväksynyt junan aikataulun.
deleted: true,false Vain /trains/version -rajapinnassa käytetty attribuutti, joka kertoo onko juna poistettu eli peruttu yli kymmenen päivää ennen lähtöä.
timeTableRows Kuvaa saapumisia ja lähtöjä liikennepaikoilta. Järjestetty reitin mukaiseen järjestykseen.
- trainStopping true,false Pysähtyykö juna liikennepaikalla
- stationShortCode: string Aseman lyhennekoodi
- stationcUICCode: 1-9999 Aseman UIC-koodi
- countryCode: “FI”, “RU”
- type: “ARRIVAL” tai “DEPARTURE” Pysähdyksen tyyppi
- commercialStop: boolean Onko pysähdys kaupallinen. Annettu vain pysähdyksille, ei läpiajoille. Mikäli junalla on osaväliperumisia, saattaa viimeinen perumista edeltävä pysähdys jäädä virheellisesti ei-kaupalliseksi.
- commercialTrack: string Suunniteltu raidenumero, jolla juna pysähtyy tai jolta se lähtee. Raidenumeroa ei saada junille, joiden lähtöön on vielä yli 10 päivää. Operatiivisissa häiriötilanteissa raide voi olla muu.
- cancelled: true/false Totta, jos lähtö tai saapuminen on peruttu
- scheduledTime: datetime Aikataulun mukainen pysähtymis- tai lähtöaika
- liveEstimateTime: datetime Ennuste. Tyhjä jos juna ei ole matkalla
- estimateSource: datetime Ennusteen lähde. Lisätietoa lähteistä täältä.
- unknownDelay: boolean Jos ennustetta ei voida antaa luotettavasti, liikenteenohjaaja voi kytkeä unknownDelay-bitin päälle. Bitti tarkoittaa, että juna on myöhässä, mutta ei osata kertoa kuinka paljon. Lisätietoa: https://www.liikennevirasto.fi/-/juna-myohassa-eika-arviota-lahtoajasta-asemien-nayttotaulut-kertovat-taman-pian-uudella-tavalla
- actualTime: datetime Aika jolloin juna saapui tai lähti asemalta
- differenceInMinutes: integer Vertaa aikataulun mukaista aikaa ennusteeseen tai toteutuneeseen aikaan ja kertoo erotuksen minuutteina
- causes Syytiedot. Kuvaavat syitä miksi juna oli myöhässä tai etuajassa pysähdyksellä. Kaikkia syyluokkia ja -tietoja ei julkaista.
  - categoryCodeId Yleisen syyluokan yksilöivä tunnus. Lista syyluokista löytyy osoitteesta metadata/cause-category-codes
  - categoryCode Yleisen syyluokan koodi. Huom. ei yksilöivä.
  - detailedCategoryCodeId Tarkemman syykoodin yksilöivä tunnus. Lista syykoodeista löytyy osoitteesta täältä
  - detailedCategoryCode Tarkempi syykoodin koodi. Huom. ei yksilöivä
  - thirdCategoryCodeId Kolmannen tason syykoodin tunnus.
  - thirdCategoryCode Kolmannen tason syykoodin koodi. Huom. ei yksilöivä
- trainReady Junan lähtövalmius. Operaattorin tulee tehdä lähtövalmiusilmoitus liikenteenohjaajalle aina kun junan kokoonpanovaihtuu tai se lähtee ensimmäiseltä pysäkiltään.
  - source Tapa, jolla lähtövalmiusilmoitus on tehty.
  - accepted Onko lähtövalmiusilmoitus hyväksytty.
  - timestamp Aika jolloin lähtövalmiusilmoitus on päätetty.

Kokoonpanot

Järjestetty kenttien departureDate ja trainNumber mukaisesti nousevaan järjestykseen.

trainNumber: 1-99999 Junan numero. Esim junan “IC 59” junanumero on 59
departureDate: date Junan ensimmäisen lähdön päivämäärä
operatorUICCode: 1-9999 Junan operoiman operaattorin UIC-koodi
operatorShortCode: vr, vr-track, destia, … Lista operaattoreista löytyy täältä.
trainCategory: lähiliikenne, kaukoliikenne, tavaraliikenne
trainType: P, S, IC, IC2, MUS, etc.
version: positive integer Versionumero, jossa juna on viimeksi muuttunut
journeySections Kuvaa junan yhtä matkaosuutta, joka ajetaan samalla kokoonpanolla
- beginTimeTableRow Aloitus
  - stationShortCode: string Aseman lyhennekoodi
  - stationcUICCode: 1-9999 Aseman UIC-koodi
  - countryCode: “FI” or “RU”
  - type: “ARRIVAL” tai “DEPARTURE” Pysähdyksen tyyppi
  - scheduledTime: datetime Aikataulun mukainen pysähtymis- tai lähtöaika
- endTimeTableRow Lopetus
  - stationShortCode: string Aseman lyhennekoodi
  - stationcUICCode: 1-9999 Aseman UIC-koodi
  - countryCode: “FI” tai “RU”
  - type: “ARRIVAL” tai “DEPARTURE” Pysähdyksen tyyppi
  - scheduledTime: datetime Aikataulun mukainen pysähtymis- tai lähtöaika
- locomotives Kokoonpanon veturit
  - location: positive integer Veturin paikka kokoonpanossa. Pienin numero on junan kärjessä
  - locomotiveType: SR1, SR2, … Veturin tyyppi
  - powerType: Diesel, Sähkö, … Veturin vetovoimalaji
- wagons Kokoonpanon vaunut
  - location: integer Vaunun paikka kokoonpanossa. Pienin numero on junan kärjessä
  - salesNumber: 0-99 Vaunun myyntinumero. Lukee esimerkiksi matkustajan junalipussa. 0 jos ei tiedossa.
  - length: positive integer Vaunun pituus senttimetreinä
  - playground : true Onko vaunussa leikkipaikka
  - pet: true Onko vaunussa lemmikkivaunu
  - catering : true Onko vaunussa ravintolavaunu
  - video : true Onko vaunussa videonäyttömahdollisuus
  - luggage : true Onko vaunussa matkatavarasäilytysmahdollisuus
  - smoking : true Saako vaunussa tupakoida
  - disabled : true Onko vaunussa invalidiystävällinen
  - wagonType Suomalainen sarjatunnus vaunulle. Ilmaisee vaunun tyypin sekä vaunun palvelut. Kaikille vaunuille ei välttämättä löydy sarjatunnusta. Lisätietoa http://fi.wikipedia.org/wiki/Sarjatunnus
- totalLength: positive integer Junan kokonaispituus metreissä
- maximumSpeed: positive integer Junan kokoonpanolle ilmoitettu maksiminopeus kilometreina tunnissa

GPS-sijainnit

trainNumber: string Junan numero. Esim junan “IC 59” junanumero on 59
departureDate: date Junan ensimmäisen lähdön päivämäärä. Voi olla tyhjä tapauksissa, jossa junan aikataulua ei tunneta.
timestamp: datetime Aikaleima jolloin sijainti on luettu
location: geojson Sijainti GeoJSON-muodossa
speed: number Junan nopeus

Kulkutietoviestit

id: positive integer Kulkutietoviestin yksilöivä numero.
version: positive integer Versionumero, jossa kulkutietoviesti on viimeksi muuttunut
trainNumber: string Junan numero. Esim junan “IC 59” junanumero on 59
departureDate: date Junan ensimmäisen lähdön päivämäärä. Voi olla tyhjä tapauksissa, jossa junan aikataulua ei tunneta.
timestamp: date Tapahtuman ajanhetki
trackSection: string Tapahtuman raideosuuden tunniste. Lista raideosuuksista löytyy täältä.
nextTrackSection: string Seuraava raideosuuden tunniste, jolle juna ajaa.
previousTrackSection: string Raideosuuden tunniste, jolta juna tuli.
station: string Liikennepaikan tunniste, jonka alueella raideosuus on. Lista liikennepaikoista löytyy täältä.
nextStation: string Liikennepaikan tunniste, jonka alueella juna aiemmin oli.
previousStation: string Liikennepaikan tunniste, jonka alueelle juna ajaa seuraavaksi.
type: string Tapahtuman tyyppi. OCCUPY tarkoittaa, että juna varasi raideosuuden. RELEASE tarkoittaa, että juna vapautti raideosuuden.

Liikennepaikat

passengerTraffic: boolean Onko liikennepaikalla kaupallista matkustajaliikennettä
countryCode: string Liikennepaikan maatunnus
stationName: string Liikennepaikan nimi
stationShortCode: string Liikennepaikan lyhenne
stationUICCode: 1-9999 Liikennepaikan maakohtainen UIC-koodi
latitude: decimal Liikennepaikan latitude “WGS 84”-muodossa
longitude: decimal Liikennepaikan longitudi “WGS 84”-muodossa
type: string Liikennepaikan tyyppi. STATION = asema, STOPPING_POINT = seisake, TURNOUT_IN_THE_OPEN_LINE = linjavaihde

Operaattorit

id: positive integer Operaattorin yksilöivä tunnus
operatorName: string Operaattorin nimi
operatorShortCode: string Operaattorin lyhenne
operatorUICCode: 1-9999 Operaattorin UIC-koodi
trainNumbers Operaattorin käytössäolevat junanumeroavaruudet.
- id: positive integer Junanumeroavaruuden yksilöivä tunnus
- bottomLimit: 1-99999 Junanumeroiden alaraja
- topLimit: 1-99999 Junanumeroiden yläraja
- trainCategory: string Junalaji

Syyluokat

id: positive integer Syyluokan yksilöivä tunnus
categoryCode: string Syyluokan tunnus
categoryName: string Syyluokan suomenkielinen nimi
validFrom: string Ajanhetki jolloin syyluokka astuu voimaan. Ajanhetki viittaa junan lähtöpäivämäärään.
validTo: string Ajanhetki jolloin syyluokka poistuu voimasta. Voi olla tyhjä, jolloin syyluokka on toistaiseksi voimassa. Ajanhetki viittaa junan lähtöpäivämäärään.
passengerTerm Matkustajatiedotustermi. Matkustajaläheinen kuvaus syyluokasta
- fi: string Suomenkielinen käännös
- en: string Englanninkielinen käännös
- sv: string Ruotsinkielinen käännös

Syykoodit

id: positive integer Syykoodin yksilöivä tunnus
detailedCategoryCode: string Syykoodin tunnus
detailedCategoryName: string Syykoodin suomenkielinen nimi
validFrom: string Ajanhetki jolloin syykoodi astuu voimaan. Ajanhetki viittaa junan lähtöpäivämäärään.
validTo: string Ajanhetki jolloin syykoodi poistuu voimasta. Voi olla tyhjä, jolloin syykoodi on toistaiseksi voimassa. Ajanhetki viittaa junan lähtöpäivämäärään.
passengerTerm Matkustajatiedotustermi. Matkustajaläheinen kuvaus syykoodista
- fi: string Suomenkielinen käännös
- en: string Englanninkielinen käännös
- sv: string Ruotsinkielinen käännös

Kolmannen tason syykoodit

id: positive integer Kolmannen tason syykoodin yksilöivä tunnus
thirdCategoryCode: string Kolmannen tason syykoodin tunnus
thirdCategoryName: string Kolmannen tason syykoodin suomenkielinen nimi
validFrom: string Ajanhetki jolloin kolmannen tason syykoodin astuu voimaan. Ajanhetki viittaa junan lähtöpäivämäärään.
validTo: string Ajanhetki jolloin kolmannen tason syykoodin astuu poistuu voimasta. Voi olla tyhjä, jolloin kolmannen tason syykoodin astuu on toistaiseksi voimassa. Ajanhetki viittaa junan lähtöpäivämäärään.
passengerTerm Matkustajatiedotustermi. Matkustajaläheinen kuvaus kolmannen tason syykoodista
- fi: string Suomenkielinen käännös
- en: string Englanninkielinen käännös
- sv: string Ruotsinkielinen käännös

Junatyypit

name: string Junatyypin nimi
trainCategory Junalaji
- name: string Junalajin nimi

Raideosuudet

station: string Raideosuuden liikennepaikan lyhenne. Lista liikennepaikoista löytyy täältä.
trackSectionCode: string Raideosuuden tunnus. Yksilöivä tieto
ranges Raideosuuden sijainnit. Raideosuudella voi olla monta sijaintia, jos se sijaitsee usealla eri ratanumerolla.
- id : positive integer Sijainnin yksilöivä numero
- startLocation: string Sijainnin alkukohta
  - track: string Ratanumero
  - kilometres: positive integer Sijainnin kilometri-komponentti. Sijainti kilometreina rataverkon nollapisteestä.
  - metres: positive integer Sijainnin metri-komponentti. Eli ylijäävä osuus kilometreistä.
- endLocation Sijainnin loppukohta
  - track: string Ratanumero
  - kilometres: positive integer Sijainnin kilometri-komponentti. Sijainti kilometreina radan alkuosasta
  - metres: positive integer Sijainnin metri-komponentti. Eli ylijäävä osuus kilometreistä.

Herätepisteet

id: positive integer Herätepisteen yksilöivä numero
trainRunningMessageTrackSection: string Kulkutietoviestin raideosuus
trainRunningMessageStationShortCode: string Kulkutietoviestin liikennepaikka
trainRunningMessageNextStationShortCode: string Kulkutietoviestin seuraava liikennepaikka
trainRunningMessageType Kulkutietoviestin tyyppi
timeTableRowStationShortCode Aikataulurivin liikennepaikka
timeTableRowType Aikataulurivin tyyppi
offset Kuinka paljon aikaa sekunteina kulkutietoviestin aikaleimaan lisätään, jotta saadaan aikataulurivin toteuma

Aikataulukaudet ja muutosajankohdat

id: positive integer Aikataulukauden yksilöivä numero
name: string Aikataulukauden nimi
effectiveFrom: date Aikataulukauden alkupäivämäärä
effectiveTo: date Aikataulukauden loppupäivämäärä
capacityAllocationConfirmDate: date Päivämäärä jolloin viranomainen tekee päätöksen kapasiteettihakemukselle
capacityRequestSubmissionDeadline: date Viimeinen päivämäärä, jolloin operaattorin kapasiteettihakemuksia aikataulukaudelle otetaan vastaan
changeDates Aikataulukauden muutosajankohdat
- id: positive integer Muutosajankohdan yksilöivä numero
- effectiveFrom: date Muutosajankohdan alkupäivämäärä
- capacityRequestSubmissionDeadline: date Viimeinen päivämäärä, jolloin operaattorin kapasiteettihakemuksia muutosajankohtaan otetaan vastaan

Versionumeroiden käyttö

Useissa rajapinnan pyynnöissä parametrina on mukana version, joka rajaa vastauksesta pois junat, jotka eivät ole päivittyneet sitten version määrittelemän versionumeron.

Esimerkiksi kysely /live-trains/station/HKI?arrived_trains=5 saattaisi palauttaa seuraavan vastauksen:

[
   {
      "trainNumber":44,
      "departureDate":"2017-01-01",
      "operatorUICCode":10,
      "operatorShortCode":"vr",
      "trainType":"S",
      "trainCategory":"Long-distance",
      "runningCurrently":true,
      "cancelled":false,
      "version":3657782905,
      "timeTableRows":...

Jos kyselyyn lisättäisiin versionumero /live-trains/station/HKI?arrived_trains=5&version=3657782905, ei junaa 44 palautettaisi vastauksessa ennenkuin se on muuttunut.

Vastaanottajan on siis parsittava vastauksesta suurin versionumero ja käytettävä sitä seuraavassa kyselyssä parametrina.

Avoimen datan käyttölupa

Rajapinnasta saatavien tietojen käyttölupa on Creative Commons Nimeä 4.0.

Käyttöehdot -sivulla on lisätietoja käyttöluvasta ja ohjeita lähteen nimeämiseen.

Liikenneviraston avoimen datan sivustolla on lisätietoja käyttöluvasta ja ohjeita lähteen nimeämiseen.

Rautatieliikenne

RATA.DIGITRAFFIC.FI

Sisältö

Yleistä

Palvelun kehittäjäyhteisö

Suunnittellut ominaisuudet

Toteutetut ominaisuudet

HTTPS

Dataa tukevat rajapinnat

Rajapinnat

Junien tiedot (/trains)

Yhden junan tiedot

Päivän junien tiedot

Kaikkien junien tiedot

Junien tietojen kuunteleminen (MQTT / Sockets)

Liikennepaikan junien tietojen kuunteleminen (MQTT / Sockets)

GTFS

Vanhat junat zip-paketteina

Aktiivisten junien seuranta (/live-trains)

Liikennepaikan saapuvat ja lähtevät junat (lukumäärärajoitus)

Liikennepaikan saapuvat ja lähtevät junat (aikavälirajoitus)

Reittiperusteinen haku

Kohta lähtevien tai saapuvien junien seuranta

Junan GPS-sijainnit (/train-locations)

Kaikkien junien sijainnit

Yhden junan sijainti

Sijaintien kuunteleminen (MQTT / Sockets)

Vanhat sijainnit zip-paketteina

Tarkempi seuranta kulkutietoviestien avulla (/train-tracking)

Kaikkien junien seuranta

Yhden junan seuranta

Liikennepaikan seuranta

Raideosuuden seuranta

Kulkutietoviestien kuunteleminen (MQTT / Sockets)

Kokoonpanotiedot (/compositions)

Junan kokoonpanohaku

Junien kokoonpanohaku

Kaikkien kokoonpanojen seuranta

Kokoonpanojen kuunteleminen (MQTT / Sockets)

Vanhat kokoonpanot zip-paketteina

Metatiedot (/metadata)

Liikennepaikkatiedot

Operaattoritiedot

Syyluokat

Syykoodit

Kolmannen tason syykoodit

Junatyypit

Raideosuudet

Herätepisteet

Aikataulukaudet ja muutosajankohdat

GraphQL

Esimerkkejä

GraphQL-kysely omassa sovelluksessa

Vastaustyypit

Junat

Kokoonpanot

GPS-sijainnit

Kulkutietoviestit

Liikennepaikat

Operaattorit

Syyluokat

Syykoodit

Kolmannen tason syykoodit

Junatyypit

Raideosuudet

Herätepisteet

Aikataulukaudet ja muutosajankohdat

Versionumeroiden käyttö

Avoimen datan käyttölupa