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.
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
- 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.
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 http://uptime.statuscake.com/?TestID=KIvdE8ZaAe.
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.
Kaikkien junien tiedot (WebSocket)
Esimerkki: esimerkki
Kuvaus
Websockettiin pistetään kaikki junat sitä mukaa kun ne muuttuvat.
Paluuarvo
Palauttaa junat-tyyppisiä vastauksia.
Liikennepaikan tiedot (WebSocket)
Esimerkki: esimerkki
Kuvaus
Websockettiin pistetään muuttunut juna, jos sillä on lähtö tai saapuminen parametrina annetulla liikennepaikalla.
Paluuarvo
Palauttaa junat-tyyppisiä vastauksia.
Yhden junan tiedot (WebSocket)
Esimerkkejä:
Kuvaus
Websockettiin pistetään yhden junan juna-tyyppiset tiedot.
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ä:
- /live-trains/station/HKI
- /live-trains/station/HKI?arrived_trains=5&arriving_trains=5&departed_trains=5&departing_trains=5&include_nonstopping=false
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.
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
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/latest/<train_number>?bbox=<points>
Esimerkki: /train-locations/latest/1
Kuvaus
Palauttaa junan GPS-sijainnin, jos se on ollut aktiivinen viimeisen 15 minuutin sisällä. Historiatietojen kysely tulossa myöhemmin.
Nimi | Formaatti | Esimerkki | Selitys | |
---|---|---|---|---|
![]() | train_number | 1-99999 | 1 | Junan numero. Esimerkiksi junan “IC 59” junanumero on 59. |
![]() | 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.
Sijainnit (MQTT)
Topic: train-locations/<departure_date>/<train_number>/
Osia topic:sta voidaan korvata wildcard-merkeillä “#” ja “+”. Esimerkiksi voidaan kuunnella topic:a “train-locations/#”. Lisätietoa täältä
Aiemmista Websocket-toteutuksista poiketen GPS-sijainnit jaetaan MQTT:lla. MQTT-palvelin löytyy osoitteesta rata-mqtt.digitraffic.fi:9001
. Myös ei-Websocket -yhteys on mahdollinen (portti 1883).
Esimerkkitoteutus Websocketilla löytyy osoitteesta http://jsfiddle.net/k8sfd4an/5/
Paluuarvo
Palauttaa GPS-sijainnit -tyyppisen vastauksen.
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 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.
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.
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.
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 | |
---|---|---|---|---|
![]() | 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ä:
- /train-tracking/station/PSL/2017-01-01/293
- /train-tracking/station/PSL/latest/293
- /train-tracking/station/PSL/latest/293?limit=150
Kuvaus
Palauttaa liikennepaikan raideosuuden kulkutietoviestit.
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 | |
---|---|---|---|---|
![]() | 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.
Kaikkien junien seuranta (WebSocket)
Esimerkki: esimerkki
Kuvaus
Websockettiin pistetään kaikkien junien kulkutietoviestit.
Paluuarvo
Palauttaa Kulkutietoviestit-tyyppisiä vastauksia.
Yhden junan seuranta (WebSocket)
Esimerkkejä:
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.
Kokoonpanotiedot (/compositions)
Kokoonpanotietoja tulee junille 0-5 tuntia ennen junan lähtö tai pysähdystä, jossa kokoonpano muuttuu.
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
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
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.
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/?
.
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ä:
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
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ä.
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
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ä.
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
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.