Liike
Liikennevirasto

rata.digitraffic.fi

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

Liike Reaali Loki

Rajapinnasta saatavien tietojen avulla on mahdollista vastata esimerkiksi seuraaviin kysymyksiin:

  • Onko junani aikataulussa?
  • 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?

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

Muutoshistoria

  • 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.

Palvelun kehittäjäyhteisö

Palvelulle on perustettu kehittäjien väliseen kommunikaatioon julkinen rata.digitraffic.fi Google-ryhmä.

Rajapinnan osat ja vastaustyypit

1. 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 neljään osaan:

Palvelussa on junien aikataulu- ja toteumatiedot 1.8.2014 alkaen sekä kokoonpanotiedot 4.3.2015 alkaen. Tulevaisuuteen tiedot ovat saatavilla 10 päivää eteenpäin. Tiedot päivittyvät noin 10 sekunnin viiveellä lähdejärjestelmistä rajapintapalveluun.

Käytettävä versio rajapinnasta kerrotaan osoitteessa. Esimerkiksi http://rata.digitraffic.fi/api/v1/live-trains?station=HKI, jossa v1 on rajapinnan versiotunnus.

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 503 -virheen. Palvelun tilaa voi seurata osoitteessa http://uptime.statuscake.com/?TestID=KIvdE8ZaAe.

1.1. Reaaliaikainen seuranta

Junien toteumien ja ennusteiden reaaliaikainen seuranta. Junia voi seurata reaaliaikaisesti kerrallaan joko yhtä tai kaikkia kulussa olevia. Lisäksi voidaan seurata tietylle asemalle saapuvia ja lähteviä junia.

Automaattinen ennusteen laskeminen perustuu ns. kulmakerroin laskentaan (lineaarinen funktio), joka tuottaa useimmiten hieman pessimistisempi ennusteita todellisuuteen nähden.

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.

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

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

Esimerkiksi: live-trains?station=HKI

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.

Hakuehdot

  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

(warning) Etenkin liikennepaikan seurannassa versionumeron käyttö saattaa aiheuttaa yllättäviä vaikutuksia, kts. 3. Versionumeroiden käyttö

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

(warning) Etenkin liikennepaikan seurannassa versionumeron käyttö saattaa aiheuttaa yllättäviä vaikutuksia, kts. 3. Versionumeroiden käyttö

Paluuarvo

Palauttaa Junat -tyyppisen vastauksen.

Yhden junan seuranta

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

Esimerkki: live-trains/1

Kuvaus

Palauttaa halutun 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)
2014-12-01 Junan ensimmäisen lähdön päivämäärä. Jos parametri jätetään tyhjäksi, 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, jossa listan koko on 0 tai 1.

Kaikkien junien seuranta

/live-trains?version=<version>

Esimerkki: live-trains

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 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.

Kaikkien junien seuranta (WebSocket)

Esimerkki: esimerkki

Kuvaus

Websockettiin pistetään junat sitä mukaa kun ne muuttuvat.

Paluuarvo

Palauttaa Junat -tyyppisiä vastauksia.

Liikennepaikan seuranta (WebSocket)

Esimerkki: esimerkki

Kuvaus

Websockettiin pistetään juna, kun sen liikennepaikan pysähdyksen tai lähdön mikä tahansa tieto muuttuu.

Paluuarvo

Palauttaa Junat -tyyppisiä vastauksia.

Yhden junan seuranta (WebSocket)

Esimerkki: esimerkki #1

Esimerkki: esimerkki #2

Kuvaus

Websockettiin pistetään yhden junan juna-tyyppiset tiedot.

Paluuarvo

Palauttaa Junat -tyyppisiä vastauksia.

1.2. Reaaliaikainen seuranta kulkutietoviestien avulla

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 WebSocketeilla (STOMP-protokolla, versiot 1.0 - 1.2).

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 (REST)

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

Esimerkiksi : train-tracking?version=5403053026

Kuvaus

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

Maksimissaan palautetaan 30 minuuttia vanhoja kulkutietoviestejä.

Hakuehdot

  Nimi Formaatti Oletusarvo Esimerkki Selitys
version positive integer 0 5403053026 Versionumero, jota uudemmat kulkutietoviestit palautetaan. Jos tyhjä, ei tehdä versiorajoitusta.

 pakollinen  vapaaehtoinen

Paluuarvo

Palauttaa Kulkutietoviestit -tyyppisen vastauksen.

Yhden junan seuranta (REST)

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

Esimerkki: /train-tracking/1?departure_date=2015-09-30&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)
2014-12-01 Junan ensimmäisen lähdön päivämäärä. Jos tyhjä, 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.

Kaikkien junien seuranta (WebSocket)

URL: /websockets/train-tracking/

Esimerkki: esimerkki

Kuvaus

Websockettiin pistetään kaikkien junien kulkutietoviestit.

Paluuarvo

Palauttaa Kulkutietoviestit -tyyppisiä vastauksia.

Yhden junan seuranta (WebSocket)

URL: /websockets/train-tracking/<train_number>/<departure_date>/

Esimerkki #1: esimerkki 1
Esimerkki #2: esimerkki 2

Kuvaus

WebSockettiin pistetään yhden tietyn junan kulkutietoviestit. Jos departure_date jätetään tyhjäksi, ei tehdä departure_date-rajoitusta.

Paluuarvo

Palauttaa Kulkutietoviestit -tyyppisiä vastauksia.

1.3. Aikataulutietojen haku

Junien aikataulutietojen haku. Tämän osion haut palauttavat vain aikataulutiedot eivätkä ennusteita tai toteumatietoja.

Kaikkien junien haku aikaväliltä

/schedules?departure_date=<departure_date>

Esimerkki: schedules ?departure_date=2015-03-01

Kuvaus

Palauttaa kaikkien junien aikataulutiedot halutulta vuorokaudelta.

Hakuehdot

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

 pakollinen  vapaaehtoinen

Paluuarvo

Palauttaa Junat -tyyppisen vastauksen ilman täsmällisyystietoja (causes ja actualTime -kentät)

Yhden junan haku

/schedules/<train_number>?departure_date=<departure_date>

Esimerkki: schedules/1?departure_date=2015-03-01

Kuvaus

Palauttaa halutun yhden junan aikataulutiedot.

Hakuehdot

  Nimi Formaatti Esimerkki  
train_number 1-99999 1, 3402 Junan numero. Esimerkiksi junan "IC 59" junanumero on 59.
departure_date date
(yyyy-mm-dd)
2014-12-01 Junan ensimmäisen lähdön päivämäärä. Jos parametri jätetään tyhjäksi, juna joka on lähinnä nykyhetkeä rajauksella taaksepäin 4 tuntia ja eteenpäin 16 tuntia.

 pakollinen  vapaaehtoinen

Paluuarvo

Palauttaa Junat -tyyppisen vastauksen ilman täsmällisyystietoja (causes ja actualTime -kentät)

Reittiperusteinen haku

/schedules?departure_station=<departure_station_code> &arrival_station=<arrival_station_code> &departure_date=<departure_date> &from=<from>&to=<to> &limit=<limit>

Esimerkki: schedules?departure_station=HKI&arrival_station=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, ei siis yhteysjunia tms.. Hakutulos ei siis sisällä operaattorin tarjoamia reittivaihtoehtoja, joissa matkustaja joutuu esimerkiksi vaihtamaan junaa.

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  
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)
2014-12-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.
from datetime
(ISO 8601)
2015-05-15T23: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.
to datetime
(ISO 8601)
2015-05-15T23: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 ilman täsmällisyystietoja (causes ja actualTime -kentät)

1.4. Historiatiedon haku

Junien aikataulu- ja toteumatietojen haku menneisyydestä.

Kaikkien junien haku

/history?departure_date=<departure_date>

Esimerkki : history?departure_date=2015-03-01

Kuvaus 

Palauttaa departure_date-parametrin määrittämän vuorokauden aikana kulkevat junat.

(warning) Mikäli haussa on mukana kuluva päivä, palauttaa kysely myös kulussa olevat junat sekä myöhemmin samana päivänä lähtevät. Myös eilisen päivän haku saattaa palauttaa vielä kulussa olevia yöjunia.

Hakuehdot

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

 pakollinen   vapaaehtoinen

Paluuarvo

Palauttaa Junat -tyyppisen vastauksen.

Junanumeroperusteinen haku

/history/<train_number>?departure_date=<departure_date>

Esimerkki: history/1 ?departure_date=2015-03-01

Kuvaus

Palauttaa yhden junan aikataulu- ja toteumatiedot halutulta vuorokaudelta.

Hakuehdot

  Nimi Formaatti Esimerkki Selitys
train_number 1-99999 1 Junan numero. Esimerkiksi junan "IC 59" junanumero on 59.
departure_date date
(yyyy-mm-dd)
2014-12-01  

 pakollinen   vapaaehtoinen

Paluuarvo

Palauttaa Junat -tyyppisen vastauksen.

1.5. Kokoonpanotiedot

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

/compositions/<train_number>?departure_date=<departure_date>

Esimerkki: compositions/1?departure_date=2015-03-05

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)
2014-12-05 Lähtöpäivämäärä

Paluuarvo

Palauttaa Kokoonpanot -tyyppisen vastauksen.

Aikavälin junien kokoonpanohaku

/compositions?departure_date=<departure_date>

Esimerkki: compositions?departure_date=2015-03-06

Kuvaus

Palauttaa junien kokoonpanotiedot halutulta vuorokaudelta.

Hakuehdot

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

Paluuarvo

Palauttaa  Kokoonpanot  -tyyppisen vastauksen.

1.6. Metatiedot

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 Liikennepaikkojen tiedot -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 Operaattotiedot -tyyppisen vastauksen.

Syyluokat

URL: metadata/cause-category -codes

Kuvaus

Palauttaa listan palvelussa käytössä olevista syyluokista. Syyluokat ovat yleisiä kategorioita syytiedoille. Kaikki syyluokat julkaistaan AvoinData-palvelun kautta.

Paluuarvo

Palauttaa Syyluokat -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.

Paluuarvo

Palauttaa 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 Syykoodit -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 Heratepisteet -tyyppisen vastauksen.


2. Vastaustyypit

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

Jokainen tyypin kenttä on kuvattu ikonilla, jotka tarkoittavat:

 Ei voi olla tyhjä

 Voi olla tyhjä

 Komentti, jos tarpeen

2.1. Junat

Järjestetty 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
  •  timeTableRows  Kuvaa saapumisia ja lähtöjä liikennepaikoilta. Järjestetty reitin mukaiseen järjestykseen.
    •  trainStopping
    •  stationShortCode: string  Aseman lyhennekoodi
    •  stationcUICCode: 1-9999  Aseman UIC-koodi
    •  countryCode: "FI" tai "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. 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
    •  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.

2.2. Kokoonpanot

Järjestetty 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 junankokonaispituus metreissä
    • maximumSpeed: positive integer Junan kokoonpanolle ilmoitettu maksiminopeus kilometreina tunnissa

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.

2.4. 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

2.5. 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

2.6 Syyluokat

  •  categoryCode: string  Syyluokan tunnus
  •  categoryName: string  Syyluokan suomenkielinen nimi

2.7. Syykoodit

  •  detailedCategoryCode: string  Syykoodin tunnus
  •  detailedCategoryName: string  Syykoodin suomenkielinen nimi

2.8. Junatyypit

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

2.9. Raideosuudet

  •  station Raideosuuden liikennepaikan lyhenne. Lista liikennepaikoista löytyy täältä.
  •  trackSectionCode 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 Sijainnin alkukohta
      •  track Ratanumero
      •  kilometres Sijainnin kilometri-komponentti. Sijainti kilometreina rataverkon nollapisteestä.
      •  metres Sijainnin metri-komponentti. Eli ylijäävä osuus kilometreistä.
    •  endLocation Sijainnin loppukohta
      •  track Ratanumero
      •  kilometres Sijainnin kilometri-komponentti. Sijainti kilometreina radan alkuosasta
      •  metres Sijainnin metri-komponentti. Eli ylijäävä osuus kilometreistä.

2.10. Herätepisteet

  •  id Herätepisteen yksilöivä numero.
  •  trainRunningMessageTrackSection Kulkutietoviestin raideosuus
  •  trainRunningMessageStationShortCode Kulkutietoviestin liikennepaikka
  •  trainRunningMessageNextStationShortCode 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

3. 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 saattaisi palauttaa seuraavan vastauksen:

[
   {
      "trainNumber":44,
      "departureDate":"2015-03-26",
      "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&version=3657782905, ei junaa 44 palautettaisi ennenkuin se on muuttunut.

Vastaanottajan on siis parsittava vastauksesta suurin versionumero ja käytettävä sitä tulevissa kyselyissä parametrina .

(warning) Versionumeroa käytettäessä tulee olla tarkkana, kun kyselyllä on ns. liikkuva aikaikkuna. Esim. kaikkien junien seuranta live-trains palauttaa lähtöjä neljä tuntia nykyhetkestä eteenpäin. Mikäli kysely tehdään versionumerolla, eivät aikaikkunaan tulevat lähdöt palaudu ennenkuin niihin tulee muutoksia (ennuste, toteuma jne.). Yleensä muutoksia tulee vasta kun juna lähtee liikkeelle.

Oletetaan esimerkiksi tilanne jossa käyttäjä tekee ensin haun ilman versionumeroa saadakseen kaikki neljän tunnin aikaikkunassa olevat junat ja alkaa sen jälkeen tekemään hakuja versionumerolla minuutin välein. Tässä tapauksessa neljän tunnin kuluttua palautuu ainoastaan junia jotka ovat lähteneet liikkelle. Käyttäjän sovellus ei siis enää "näe" tulevia lähtöjä. Tästä syystä on tärkeää tehdä säännöllisesti hakuja myös ilman versionumeroa, mikäli halutaan ylläpitää tietoa myös tulevaisuudessa olevista lähdöistä. Tämä koskee kaikkien junien seurantaa (live-trains) ja liikennepaikan junien seurantaa (live-trains?station=...).

4. Käyttöehdot

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

Digitraffic, jonka tekijä on Liikennevirasto, on lisensoitu Creative Commons Nimeä 4.0 Kansainvälinen -lisenssillä.

Creative Commons -lisenssi

Tämän lisenssin antamia oikeuksia laajempia lupia voi olla saatavilla osoitteessa http://www.liikennevirasto.fi.

Takaisin ylös