Digitraffic
magnifying glass

Rautatieliikenne

Junien aikataulut, toteumatiedot, sijainnit ja kokoonpanot.

Tämän avoimen rajapinnan tarkoituksena on jakaa tietoa Suomen rataverkolla kulkevien junien aikatauluista, sijainneista, kokoonpanoista sekä täsmällisyystiedoista. Palvelun omistaa Fintraffic ja tietolähteenä toimii Fintrafficin 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?
  • Millaisia matkustajatiedotteita on voimassa asemalla A liittyen junaan B?

Saatavilla on GraphQL-rajapinta sekä Swagger-dokumentaatio

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

Avoimeen dataan tuotavaa tietoa koostetaan eri lähteistä. Lähdejärjestelmien tiedoissa voi olla puutteita tai virheitä, tietoa ei aina saada tai tieto jää jostakin syystä välittymättä avoimeen dataan. Arkaluonteisia tietoja ei tuoda avoimeen dataan lainkaan. Näistä syistä emme suosittele aineiston käyttämistä turvallisuuskriittisissä sovelluksissa.

Sisältö

  1. Yleistä
    1. Palvelun kehittäjäyhteisö
    2. Suunnittellut ominaisuudet
    3. Toteutetut ominaisuudet
    4. HTTPS
    5. Dataa tukevat rajapinnat / työkalut
  2. REST-rajapinnat
    1. GraphQL
    2. Junien tiedot (/trains)
    3. Aktiivisten junien seuranta (/live-trains)
    4. Junien GPS-sijainnit (/train-locations)
    5. Tarkempi seuranta kulkutietoviestien avulla (/train-tracking)
    6. Kokoonpanotiedot (/compositions)
    7. Kulkutievaraukset (/routesets)
    8. Ratatyötiedot (/trackwork-notifications) ja liikenteen rajoitetiedot (/trafficrestriction-notifications)
    9. Metatiedot (/metadata)
    10. Matkustajainformaation tiedotteet (/passenger-information)
  3. WebSocket (MQTT)
    1. Yleistä MQTT:stä
    2. Junien kuuntelu
    3. Kokoonpanojen kuuntelu
    4. GPS-sijaintien kuuntelu
    5. Kulkutietoviestien kuuntelu
    6. Kulkutievarauksien kuntelu
  4. Vastaustyypit
    1. Junat
    2. Kokoonpanot
    3. GPS-sijainnit
    4. Kulkutietoviestit
    5. Liikennepaikat
    6. Operaattorit
    7. Syyluokat
    8. Syykoodit
    9. Kolmannen tason syykoodit
    10. Junalajit
    11. Junatyypit
    12. Raideosuudet
    13. Herätepisteet
    14. Aikataulukaudet ja muutosajankohdat
    15. Versiohistoria
    16. Matkustajainformaation tiedotteet
  5. Versionumeroiden käyttö
  6. 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”.

Toteutetut ominaisuudet

  • 5.9.2023
    • Matkustajainformaation tiedotteiden rajapinta (/passenger-information)
  • 13.10.2020
    • GraphQL:n v2, jossa dataa pystyy käsittelemään monipuolisemmin
  • 13.5.2020
    • Kalustoyksikkönumero lähiliikenteen sähkömoottorijunille
  • 26.3.2020
    • Rajapinnat ratatyö- ja liikenteen rajoite-ilmoituksille
  • 15.10.2019
    • Rajapinta, josta voi hakea junien ja kokoonpanojen versiohistorian
  • 20.8.2019
    • Liikennepaikan junia mahdollista suodattaa lunalajilla (matkustajajunien erottelu tavarajunista)
  • 19.8.2019
    • Sijainnilliset vastaukset saa puhtaassa GeoJSON-muodossa
  • 20.5.2019
    • Kulkutievaraukset (routeset-viestit)
  • 22.1.2019
    • Suojattu MQTT-yhteys
  • 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 / työkalut

REST-rajapinnat

Rest-rajapintoja on kahta eri tyyyppiä:

  1. GraphQL-rajapinta
  2. Staattiset rajapinnat

GraphQL-rajapinta tarjoaa mahdollisuuden valita miten tietoa filtteröidään, järjestetään ja mitä kenttiä otetaan mukaan vastaukseen

Staattiset rajapinnat palauttavat tiedot aina samassa formaatissa. Tietojen filtteröinti, järjestäminen ja kenttien määrittely ei ole mahdollista

Staattiset rajapinta on jaettu kahdeksaan osaan:

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.

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.

Käytettävä versio rajapinnasta kerrotaan osoitteessa. Esimerkiksi https://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.

Palvelun tilaa voi seurata osoitteessa https://status.digitraffic.fi/.

GraphQL

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

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

Kuva schemasta löytyy osoitteesta https://rata.digitraffic.fi/api/v2/graphql/schema.svg . Schemasta käy ilmi kyselyt, niiden parametrit sekä mihin tietoihin voidaan yhdistyä

GraphQL schema

Kaikille kyselyille ja niihin liittyville tiedoille voi antaa

  • filtterin (tai useampia) where-parametrilla
  • järjestyksen (tai useampia) orderBy-parametrilla
  • kappalemäärän skip- ja take-parametrilla

Rajoituksia

  • Kyselyssä ei saa olla sama kenttä kahdesti. Esimerkiksi kysely train { compositions { train } } on laiton
  • contains:a ei voi käyttää kahdesti samassa where-argumentissä. Esimerkiksi where: {compositions: {contains: {journeySections: {contains: {maximumSpeed: {greaterThan: 50}}}}}} on laiton

Esimerkkejä

Kaikki kulussa olevat VR:n junat ja niille viimeisin sijainti, jossa nopeus on yli 30 km/h kokeile

{
  currentlyRunningTrains(where: {operator: {shortCode: {equals: "vr"}}}) {
    trainNumber
    departureDate
    trainLocations(where: {speed: {greaterThan: 30}}, orderBy: {timestamp: DESCENDING}, take: 1) {
      speed
      timestamp
      location
    }
  }
}

Kaikki junat tietyltä päivämäärältä, joiden operaattori on VR ja lähilinjaliikennetunnus ei ole Z järjestettynä laskevasti junanumeron mukaan kokeile

{
  trainsByDepartureDate(
    departureDate: "2020-10-05", 
    where: {and: [ {operator: {shortCode: {equals: "vr"}}}, {commuterLineid: {unequals: "Z"}}]}, 
    orderBy: {trainNumber: DESCENDING}) 
  {
    trainNumber
    departureDate
    commuterLineid
    operator {
      shortCode
    }
  }
}

Kulussa olevat junat järjestetynä operaattorilla ja junanumerolla kokeile

{
  currentlyRunningTrains(orderBy: [{operator:{shortCode:ASCENDING}},{trainNumber:ASCENDING}]) {
    operator {
      shortCode
    }
    trainNumber
  }
}

Junat, jotka kulkevat Ylöjärven kautta kokeile

{
  trainsByDepartureDate(departureDate: "2020-10-06", 
    where: {timeTableRows:{contains:{station:{shortCode:{equals:"YLÖ"}}}}}
    ) {
    trainNumber
    departureDate
    timeTableRows {
      station {
        name
        uicCode
      }
    }
  }
}

Päivän juniin liittyvät matkustajainformaation tiedotteet

{
  passengerInformationMessages(
    where: {trainDepartureDate: {equals: "2024-06-11"}}
  ) {
    trainNumber
    video {
      text {
        fi
        sv
        en
      }
    }
    audio {
      text {
        fi
        sv
        en
      }
    }
  }
}

GraphQL-kysely omassa sovelluksessa

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

HTTP-pyyntöön tulee lisätä otsikot Content-Type: application/json ja Accept-Encoding: gzip

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

{"query":"{  trainsByDepartureDate(departureDate:\"2020-10-05\", where: {and: [{operator: {shortCode: {eq: \"vr\"}}}, {commuterLineid: {ne: \"Z\"}}]}, orderBy:{trainNumber:DESCENDING}) {    trainNumber\n    departureDate\n    commuterLineid\n    operator {\n      shortCode\n    }\n  }\n}","variables":null,"operationName":null}

Kysely kokonaisuudessaan curl:lla:

curl 'https://rata.digitraffic.fi/api/v2/graphql/graphql' --compressed -H 'content-type: application/json' --data-binary '{"query":"{\n  currentlyRunningTrains(where: {operator: {shortCode: {equals: \"vr\"}}}) {\n    trainNumber\n    departureDate\n    trainLocations(where: {speed: {greaterThan: 30}}, orderBy: {timestamp: DESCENDING}, take: 1) {\n      speed\n      timestamp\n      location\n    }\n  }\n}","variables":null,"operationName":null}'

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/<departure_date>/<train_number>

Esimerkkejä

Kuvaus

Palauttaa yhden junan tiedot

Hakuehdot

    NimiFormaattiEsimerkkiSelitys
pakollinentrain_number1-999991, 3402Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
vapaaehtoinendeparture_datedate(yyyy-mm-dd)2017-01-01Junan ensimmäisen lähdön päivämäärä Suomen ajassa. 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.
vapaaehtoinenversionpositive integer159123295871Versiorajoitus. Jos juna ei ole muuttunut sitten määritellyn version, palautetaan tyhjä tulos.
vapaaehtoineninclude_deletedbooleanfalsePalautetaanko vastauksessa myös poistetut junat. Oletuksena false

pakollinen Pakollinen vapaaehtoinen 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

    NimiFormaattiEsimerkki 
pakollinendeparture_datedate (yyyy-mm-dd)2017-01-01 
vapaaehtoineninclude_deletedbooleanfalsePalautetaanko vastauksessa myös poistetut junat. Oletuksena false

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa junat-tyyppisen vastauksen.

Kaikkien junien tiedot

URL: /trains?version

Esimerkki: /trains?version=1234567891234

Kuvaus

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

Hakuehdot

    NimiFormaattiEsimerkkiSelitys
vapaaehtoinenversionpositive integer159123295871Versiorajoitus. Palauttaa kaikki junat, jotka ovat muuttuneet sitten version-version. Jos versionumeroa ei anneta, palautetaan uusimmalla versionumerolla muuttuneet junat.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa junat-tyyppisen vastauksen.

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

Lisäksi on tarjolla reaaliaikafeedit gtfs-rt-locations ja gtfs-rt-updates. Nämä feedit tarjoavat reaaliaikaista GTFS-dataa protobuf-muodossa.

  • gtfs-rt-locations sisältää junien sijainnit ja se päivitetään 10s välein.
  • gtfs-rt-updates sisältää junien muutostiedot, ennusteet, toteumatiedot ja perumiset ja se päivitetään minuutin välein.

Paluuarvo

Staattiset rajapinnat palauttavat GTFS-muodossa olevan zip-paketin. Reaaliaikaiset rajapinnat palauttavat tiedot protobuf-muodossa.

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

Junan versiohistoria

URL: /trains/history/{departure_date}/{train_number}

Esimerkki: /trains/history/2019-10-14/1

Kuvaus

Palauttaa junan kaikki versiot. Historiatietoa säilytetään tallessa 14 päivää

Hakuehdot

    NimiFormaattiEsimerkkiSelitys
pakollinentrain_number1-999991, 3402Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
pakollinendeparture_datedate(yyyy-mm-dd)2017-01-01Junan ensimmäisen lähdön päivämäärä Suomen ajassa.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa versiohistoria-tyyppisen vastauksen, jossa json-kenttä on muotoa junat.

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.

 NimiFormaattiOletusarvoEsimerkkiSelitys
pakollinenstationstring “HKI”Aseman lyhenne. Esimerkiksi HKL, TPE, PSL. Lista lyhenteistä löytyy täältä.
vapaaehtoinenarrived_trainspositive integer, 1-600520Kuinka monta saapunutta junaa palautetaan maksimissaan.
vapaaehtoinenarriving_trainspositive integer, 1-600520Kuinka monta saapuvaa junaa palautetaan maksimissaan.
vapaaehtoinendeparted_trainspositive integer, 1-600520Kuinka monta lähtenyttä junaa palautetaan maksimissaan.
vapaaehtoinendeparting_trainspositive integer, 1-600520Kuinka monta lähtevää junaa palautetaan maksimissaan.
vapaaehtoineninclude_nonstoppingtrue/falsefalsetruePalautetaanko aseman ohi pysähtymättä ajavat junat.
vapaaehtoinentrain_categoriesstring Commuter,Long-distanceJunalaji-rajaus pilkulla eroteltuna. Lista junalajeista löytyy täältä
vapaaehtoinenversionpositive integer 159123295871Versiorajaus. Palauttaa kaikki junat, jotka ovat muuttuneet sitten version-version. Jos versionumeroa ei anneta, palautetaan uusimmat tiedot.

pakollinen Pakollinen vapaaehtoinen 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

Esimerkkejä:

warning Aikaväliä rajoittavia parametrejä käytettäessä on kaikille niistä annettava arvo, jotta rajoitus toimii.

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

    NimiFormaattiOletusarvoEsimerkkiSelitys
pakollinenstationstring “HKI”Aseman lyhenne. Esimerkiksi HKL, TPE, PSL. Lista lyhenteistä löytyy täältä.
pakollinenminutes_before_departurepositive integer, 0-1440 20Kuinka monta minuuttia juna näytetään ennen sen lähtöä. Aikaväliä rajoittavia parametrejä käytettäessä on kaikille niistä annettava arvo, jotta rajoitus toimii.
pakollinenminutes_after_departurepositive integer, 0-1440 20Kuinka monta minuuttia juna näytetään sen lähdön jälkeen. Aikaväliä rajoittavia parametrejä käytettäessä on kaikille niistä annettava arvo, jotta rajoitus toimii.
pakollinenminutes_before_arrivalpositive integer, 0-1440 20Kuinka monta minuuttia juna näytetään ennen sen saapumista. Aikaväliä rajoittavia parametrejä käytettäessä on kaikille niistä annettava arvo, jotta rajoitus toimii.
pakollinenminutes_after_arrivalpositive integer, 0-1440 20Kuinka monta minuuttia juna näytetään sen saapumisen jälkeen. Aikaväliä rajoittavia parametrejä käytettäessä on kaikille niistä annettava arvo, jotta rajoitus toimii.
vapaaehtoineninclude_nonstoppingtrue/falsefalsetruePalautetaanko aseman ohi pysähtymättä ajavat junat.
vapaaehtoinentrain_categoriesstring Commuter,Long-distanceJunalaji-rajaus pilkulla eroteltuna. Lista junalajeista löytyy täältä
vapaaehtoinenversionpositive integer 159123295871Versiorajoitus. Palauttaa kaikki junat, jotka ovat muuttuneet sitten version-version. Jos versionumeroa ei anneta, palautetaan uusimmat tiedot.

pakollinen Pakollinen vapaaehtoinen 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

    NimiFormaattiEsimerkkiSelite
pakollinendeparture_stationstring“HKI”Lähtöaseman lyhenne. Lyhennekoodit löytyvät täältä.
pakollinenarrival_stationstring“RI”Määränpääaseman lyhenne. Lyhennekoodit löytyvät täältä.
vapaaehtoinendeparture_datedate(yyyy-mm-dd)2017-01-01Päivämäärä jolta junia haetaan. Jos lähtöpäivämäärä on tyhjä, etsitään seuraavan 24 tunnin aikana lähteviä junia.
vapaaehtoinenstartDatedatetime(ISO 8601)2017-01-01T23:28:59.564Zdeparture_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.
vapaaehtoinenendDatedatetime(ISO 8601)2017-01-01T23:28:59.564ZTämä parametri määrittelee aikavälin lopun. Jos tämä parametri jätetään tyhjäksi, haetaan junia seuraavalle 24 tunnille asti.
vapaaehtoinenlimitpositive integer15Rajaa palautettavien junien määrää. Oletusarvo on 1000.
vapaaehtoineninclude_nonstoppingtrue/falsefalsePalautetaanko aseman ohi pysähtymättä ajavat junat.

pakollinen Pakollinen vapaaehtoinen 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

    NimiFormaattiEsimerkkiSelitys
pakollinenversionpositive integer6403053026Versiorajoitus. Palauttaa kaikki junat, jotka ovat muuttuneet sitten version-version. Jos versionumeroa ei anneta, palautetaan uusimmat tiedot.

pakollinen Pakollinen vapaaehtoinen 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ä 6 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>

Kuvaus

Palauttaa kaikkien junien GPS-tiedot, jotka ovat olleet aktiivisia viimeisen 15 minuutin sisällä.

    NimiFormaattiEsimerkkiSelitys
vapaaehtoinenbbox4 numeroa: [vasen ala long (x), vasen ala lat (y), oikea ylä long (x), oikea ylä lat (y)]24.896417,60.149976,24.980804,60.190234Maantieteellinen rajaus WSG84-koordinaateilla. Kahdesta ensimmäisestä ja kahdesta viimeisestä numerosta muodostetaan rajausneliön määrittelevät pisteet

pakollinen Pakollinen vapaaehtoinen 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ä.

    NimiFormaattiEsimerkkiSelitys
pakollinentrain_number1-999991Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
pakollinendeparture_datedate(yyyy-mm-dd)2017-01-01Junan ensimmäisen lähdön päivämäärä Suomen ajassa. Jos arvo on “latest” (esim. train-locations/latest/1), palautetaan uusin, vähintään 15 minuutin sisällä päivittynyt GPS-sijainti.
vapaaehtoinenbbox4 numeroa: [vasen ala long (x), vasen ala lat (y), oikea ylä long (x), oikea ylä lat (y)]24.896417,60.149976,24.980804,60.190234Maantieteellinen rajaus WSG84-koordinaateilla. Kahdesta ensimmäisestä ja kahdesta viimeisestä numerosta muodostetaan rajausneliön määrittelevät pisteet

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa GPS-sijainnit -tyyppisen vastauksen.

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.

Sijainnit GeoJSON-muodossa

Lisää osoitteen perään .geojson

Esimerkkejä:

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

    NimiFormaattiEsimerkkiSelitys
vapaaehtoinenversionpositive integer6403053026Versionumero, jota uudemmat kulkutietoviestit palautetaan. Jos versionumeroa ei anneta, palautetaan kulkutietoviestit uusimmalla versionumerolla

pakollinen Pakollinen vapaaehtoinen 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

    NimiFormaattiEsimerkkiSelitys
pakollinentrain_number1-999991, 3402Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
pakollinendeparture_datedate(yyyy-mm-dd)2017-01-01Junan ensimmäisen lähdön päivämäärä Suomen ajassa. 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.
vapaaehtoinenversionpositive integer159123295871Versiorajoitus. Jos juna ei ole muuttunut sitten määritellyn version, palautetaan tyhjä tulos. Jos tyhjä, ei tehdä versiorajoitusta.

pakollinen Pakollinen vapaaehtoinen 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.

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

    NimiFormaattiEsimerkkiSelitys
pakollinenstationstring“HKI”Liikennepaikan lyhenne. Lyhennekoodit löytyvät täältä
pakollinendeparture_datedate(yyyy-mm-dd)2017-01-01Junan ensimmäisen lähdön päivämäärä Suomen ajassa. Palauttaa lisäksi kulkutietoviestit ilman lähtöpäivämäärää hakuparametria seuraavalta päivältä kello 16:00 asti.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa Kulkutietoviestit-tyyppisen vastauksen.

Raideosuuden seuranta

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

Esimerkkejä:

Kuvaus

Palauttaa liikennepaikan raideosuuden 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

    NimiFormaattiEsimerkkiSelitys
pakollinenstationstring“HKI”Liikennepaikan lyhenne. Lyhennekoodit löytyvät täältä
pakollinentrack_sectionstring“001”Liikennepaikan raideosuuden lyhenne. Lyhennekoodit löytyvät täältä
pakollinendeparture_datedate (yyyy-mm-dd)2017-01-01Kulkutietoviestiin liittyvän Junan ensimmäisen lähdön päivämäärä Suomen ajassa. 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ä.
vapaaehtoinenlimitpositive integer100Kuinka 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 Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa Kulkutietoviestit-tyyppisen vastauksen.

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

    NimiFormaattiSelitys 
pakollinentrain_number1-999991Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
pakollinendeparture_datedate(yyyy-mm-dd)2017-01-01Lähtöpäivämäärä

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa Kokoonpanot-tyyppisen vastauksen.

Junien kokoonpanohaku

URL: /compositions/<departure_date>

Esimerkki: /compositions/2017-01-01

Kuvaus

Palauttaa junien kokoonpanotiedot halutulta vuorokaudelta.

Hakuehdot

    NimiFormaattiEsimerkki
pakollinendeparture_datedate(yyyy-mm-dd)2017-01-01

pakollinen Pakollinen vapaaehtoinen 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

    NimiFormaattiEsimerkkiSelitys
vapaaehtoinenversionpositive integer6403053026Versiorajoitus. Palauttaa kaikki kokoonpanot, jotka ovat muuttuneet sitten version. Jos versionumeroa ei anneta, palautetaan uusin kokoonpano.

pakollinen Pakollinen vapaaehtoinen 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ä.

Kokoonpanojen versiohistoria

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

Esimerkki: /compositions/history/2019-01-01/1

Kuvaus

Palauttaa junan kokoonpanojen kaikki versiot. Historiatietoa säilytetään tallessa 14 päivää

Hakuehdot

    NimiFormaattiSelitys 
pakollinentrain_number1-999991Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
pakollinendeparture_datedate(yyyy-mm-dd)2017-01-01Lähtöpäivämäärä

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa versiohistoria-tyyppisen vastauksen, jossa json-kenttä on muotoa kokoonpanot.

Kulkutievaraukset (/routesets)

Jotta juna voi kulkea eteenpäin, sen tarvitsee varata edestään turvallinen kulkutie. Kulkutievaraukset kertovat yksityiskohtaisesti (raideosuus/opastin/vaihe-tasolla), millainen kulkutie edestä on varattu.

Kaikkien kulkutievarauksien seuranta

URL: /routesets?version=<version>

Esimerkki: /routesets?version=12349873459128375

Kuvaus

Palauttaa kaikki kulkutievaraukset, jotka ovat uudempia kuin version

Paluuarvo

Palauttaa Kulkutievaraukset-tyyppisen vastauksen järjestettynä version-kentän mukaan nousevasti.

Hakuehdot

    NimiFormaattiEsimerkkiSelitys
vapaaehtoinenversionpositive integer6403053026Versiorajoitus. Palauttaa kaikki kulkutievaraukset, jotka ovat muuttuneet sitten version. Jos versionumeroa ei anneta, palautetaan uusin kulkutievaraus.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Yhden junan kulkutievaraukset

URL: /routesets/<departure_date>/<train_number>

Esimerkki: /routesets/2019-05-20/1

Kuvaus

Palauttaa yksittäisen junan kulkutievaraukset tiettynä päivämääränä järjestettynä nousevasti messageTime- ja sectionOrder-kentän mukaan

Hakuehdot

    NimiFormaattiEsimerkki 
pakollinentrain_number1-999991Junan numero. Esimerkiksi junan “IC 59” junanumero on 59.
pakollinendeparture_datedate(yyyy-mm-dd)2017-01-01Lähtöpäivämäärä

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa Kulkutievaraukset-tyyppisen vastauksen.

Liikennepaikan kulkutievaraukset

URL: /routesets/station/<station>/<departure_date>

Esimerkki: /routesets/station/JY/2019-05-20

Kuvaus

Palauttaa liikennepaikan kulkutievaraukset.

Hakuehdot

    NimiFormaattiEsimerkki 
pakollinenstationstring“HKI”Liikennepaikan lyhenne. Lyhennekoodit löytyvät täältä
pakollinendeparture_datedate (yyyy-mm-dd)2017-01-01Kulkutievaraukseen liittyvän junan ensimmäisen lähdön päivämäärä Suomen ajassa. Palauttaa lisäksi kulkutievaraukset ilman lähtöpäivämäärää ajalta 00:00 - 24:00.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa Kulkutievaraukset-tyyppisen vastauksen järjestettynä nousevasti messageTime- ja sectionOrder-kentän mukaan

Ratatyötiedot (/trackwork-notifications) ja liikenteen rajoitetiedot (trafficrestriction-notifications)

Ratatyöilmoitukset ja liikenteen rajoite-ilmoitukset ovat peräisin RUMA-järjestelmästä. Kuvaus tietosisällöstä löytyy täältä.

Ratatyöilmoitukset

Ratatyöilmoitukset ovat versioituvia. Avoimeen dataan ei tuoda kaikkia tietoje, joten peräkkäiset versiot voivat olla tietosisällöltään identtisiä.

Ratatyöilmoitusten haku aikavälillä

URL: /trackwork-notifications.{json/geojson}

Esimerkki: /trackwork-notifications.json?state=ACTIVE

Kuvaus Palauttaa ratatyöilmoitukset JSON tai GeoJSON-muodossa. Annettava aikaväli rajaa ilmoituksia version luontihetken eli modified-kentän perusteella. Aikavälille osuvasta ilmoituksesta palautetaan aina uusin versio.

Hakuehdot

    NimiFormaattiEsimerkki 
vapaaehtoinenstatestring“ACTIVE”Ilmoituksen tila, arvot: SENT, ACTIVE, PASSIVE, FINISHED. Oletusarvo ACTIVE.
vapaaehtoinenschemabooleantrueNäytetäänkö ilmoituksen kaaviosijainnit? Oletusarvo false.
vapaaehtoinenstartdate2019-01-01T00:00:00.000ZAikavälin alku. Oletusarvo nykyhetki - 7 päivää.
vapaaehtoinenenddate2019-02-04T00:00:00.000ZAikavälin loppu. Oletusarvo nykyhetki.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Ratatyöilmoitusten uusimpien versioiden haku aikavälillä

URL: /trackwork-notifications/status

Esimerkki: /trackwork-notifications/status

Kuvaus Palauttaa aikavälille osuvien ilmoituksen tunnisteet ja uusimmat versiot.

Hakuehdot

    NimiFormaattiEsimerkki 
vapaaehtoinenstartdate2019-01-01T00:00:00.000ZAikavälin alku. Oletusarvo nykyhetki - 7 päivää.
vapaaehtoinenenddate2019-02-04T00:00:00.000ZAikavälin loppu. Oletusarvo nykyhetki.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo Palauttaa vastauksena joukon Ilmoituksen status-tyyppisiä alkioita järjestettynä nousevasti modified- ja id-kentän mukaan.

Ratatyöilmoitusten kaikkien versioiden palautus

URL: /trackwork-notifications/<id>

Esimerkki: /trackwork-notifications/1.2.246.586.7.1.166700

Kuvaus Palauttaa tietyn ilmoituksen kaikki versiot.

Hakuehdot

    NimiFormaattiEsimerkki 
vapaaehtoinenschemabooleantrueNäytetäänkö ilmoituksen kaaviosijainnit? Oletusarvo false.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Ratatyöilmoitusten tietyn version palautus

URL: /trackwork-notifications/<id>/<version>

Esimerkki: /trackwork-notifications/1.2.246.586.7.1.166700/5

Kuvaus Palauttaa tietyn ilmoituksen tietyn version.

Hakuehdot

    NimiFormaattiEsimerkki 
vapaaehtoinenschemabooleantrueNäytetäänkö ilmoituksen kaaviosijainnit? Oletusarvo false.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Liikenteen rajoite-ilmoitukset

Liikenteen rajoite-ilmoitukset ovat versioituvia. Avoimeen dataan ei tuoda kaikkia tietoje, joten peräkkäiset versiot voivat olla tietosisällöltään identtisiä.

Liikenteen rajoite-ilmoitusten haku aikavälillä

URL: /trafficrestriction-notifications.{json/geojson}

Esimerkki: /trafficrestriction-notifications.json?state=SENT

Kuvaus Palauttaa ilmoitukset JSON tai GeoJSON-muodossa. Annettava aikaväli rajaa ilmoituksia version luontihetken eli modified-kentän perusteella. Aikavälille osuvasta ilmoituksesta palautetaan aina uusin versio.

Hakuehdot

    NimiFormaattiEsimerkki 
vapaaehtoinenstatestring“ACTIVE”Liikenteen ilmoituksen tila, arvot: SENT, FINISHED. Oletusarvo SENT.
vapaaehtoinenschemabooleantrueNäytetäänkö ilmoituksen kaaviosijainnit? Oletusarvo false.
vapaaehtoinenstartdate2019-01-01T00:00:00.000ZAikavälin alku. Oletusarvo nykyhetki - 7 päivää.
vapaaehtoinenenddate2019-02-04T00:00:00.000ZAikavälin loppu. Oletusarvo nykyhetki.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Liikenteen rajoite-ilmoitusten uusimpien versioiden haku aikavälillä

URL: /trafficrestriction-notifications/status

Esimerkki: /trafficrestriction-notifications/status

Kuvaus Palauttaa aikavälille osuvien ilmoitusten tunnisteet ja uusimmat versiot.

Hakuehdot

    NimiFormaattiEsimerkki 
vapaaehtoinenstartdate2019-01-01T00:00:00.000ZAikavälin alku. Oletusarvo nykyhetki - 7 päivää.
vapaaehtoinenenddate2019-02-04T00:00:00.000ZAikavälin loppu. Oletusarvo nykyhetki.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo Palauttaa vastauksena joukon Ilmoituksen status-tyyppisiä alkioita järjestettynä nousevasti modified- ja id-kentän mukaan.

Liikenteen rajoite-ilmoituksen kaikkien versioiden palautus

URL: /trafficrestriction-notifications/<id>

Esimerkki: /trafficrestriction-notifications/1.2.246.586.7.2.102883

Kuvaus Palauttaa tietyn ilmoituksen kaikki versiot.

Hakuehdot

    NimiFormaattiEsimerkki 
vapaaehtoinenschemabooleantrueNäytetäänkö ilmoituksen kaaviosijainnit? Oletusarvo false.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Liikenteen rajoite-ilmoituksen tietyn version palautus

URL: /trafficrestriction-notifications/<id>/<version>

Esimerkki: /trafficrestriction-notifications/1.2.246.586.7.2.102883/1

Kuvaus Palauttaa tietyn ilmoituksen tietyn version.

Hakuehdot

    NimiFormaattiEsimerkki 
vapaaehtoinenschemabooleantrueNäytetäänkö ilmoituksen kaaviosijainnit? Oletusarvo false.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Metatiedot (/metadata)

Palvelun metatietojen hakurajapinta.

Liikennepaikkatiedot

URL:

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.

Junalajit

URL: metadata/train-categories

Kuvaus

Palauttaa listan palvelussa käytössä olevista junalajeista (esim. Cargo, Long-distance, Commuter).

Paluuarvo

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

Matkustajainformaation tiedotteet (/passenger-information)

Rajapinnan kautta on saatavilla suomalaisilla rautatieasemilla nähtäviä ja kuultavia matkustajatiedotteita. Ne sisältävät mm. sekä yleisiä tiedotteita että ajankohtaista tietoa rataliikenteen häiriöstä ja aikataulumuutoksista.

Matkustajainformaatiotiedote liittyy asemaan tai asemiin ja/tai johonkin junanumeroon ja junan lähtöpäivämäärään. Tiedotteen voimassaoloaika kerrotaan alku- ja loppupäivämäärillä ja yksittäinen tiedote voi myös ajan mittaan päivittyä, mikä ilmaistaan versionumerolla. Rajapinnat palauttavat aina kunkin tiedotteen ( yksilöidään tunnisteella id) uusimman version (version).

Tiedotteesta on olemassa audio- tai videomuotoinen julkaisu tai molemmat. Rajapinnasta saatava tieto sisältää erimuotoisten julkaisujen tekstitetyt sisällöt sekä niiden esittämiseen mahdollisesti liittyviä sääntöjä. Tiedotteen tekstisisällöt ovat yleensä saatavilla suomeksi, ruotsiksi ja englanniksi.

Voimassa olevat tiedotteet

URL: /passenger-information/active

Esimerkki: /passenger-information/active?station=HKI

Kuvaus

Palauttaa kaikki mahdollisin hakuehdoin rajatut tiedotteet, joiden startValidity on menneisyydessä ja endValidity tulevaisuudessa.

Hakuehdot

    NimiFormaattiEsimerkkiSelitys
vapaaehtoinenstationstringHKIAseman (liikennepaikan) lyhenne. Lyhennekoodit löytyvät täältä. Palauttaa asemaan liittyvät tiedotteet.
vapaaehtoinentrain_number1-999997Palauttaa annettuun junanumeroon liittyvät tiedotteet.
vapaaehtoinentrain_departure_datedate(YYYY-MM-DD)2023-10-20Palauttaa annettuna päivämääränä lähteviin juniin liittyvät tiedotteet.
vapaaehtoinenonly_generalbooleantruePalauttaa vain “yleiset” tiedotteet (jotka eivät liity tiettyyn junaan vaan ainoastaan asemaan/asemiin). Oletusarvo false.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa Matkustajainformaation tiedotteet -tyyppisen vastauksen.

Annetun ajankohdan jälkeen päivittyneet tiedotteet

URL: /passenger-information/updater-after/{date}

Esimerkki: /passenger-information/updated-after/2023-09-01T12:00?only_active=false

Kuvaus

Palauttaa kaikki mahdollisin hakuehdoin rajatut tiedotteet, joiden creationDateTime on polkuparametrin {date} päivämääränä tai sen jälkeen. creationDateTime on yhden tiedotteen yhden version luontiaika, jolloin toisin sanoen rajapinta palauttaa ne tiedotteet, jotka ovat joko luotu (uusin versionumero

1) tai päivitetty (uusin versionumero > 1) annettuna päivämääränä tai sen jälkeen.

Hakuehdot

    NimiFormaattiEsimerkkiSelitys
pakollinendatedate(ISO 8601)2023-10-20T13:00+0300 
vapaaehtoinenstationstringHKIAseman (liikennepaikan) lyhenne. Lyhennekoodit löytyvät täältä. Palauttaa asemaan liittyvät tiedotteet.
vapaaehtoinentrain_number1-999997Palauttaa annettuun junanumeroon liittyvät tiedotteet.
vapaaehtoinentrain_departure_datedate(YYYY-MM-DD)2023-10-20Palauttaa annettuna päivämääränä lähteviin juniin liittyvät tiedotteet.
vapaaehtoinenonly_generalbooleantruePalauttaa “yleiset” tiedotteet (jotka eivät liity tiettyyn junaan vaan ainoastaan asemaan/asemiin). Oletusarvo false.
vapaaehtoinenonly_activebooleantrueMikäli arvo on false, palauttaa myös ei-voimassaolevat tiedotteet. Oletusarvo true.

pakollinen Pakollinen vapaaehtoinen Vapaaehtoinen

Paluuarvo

Palauttaa Matkustajainformaation tiedotteet -tyyppisen vastauksen.

WebSocket (MQTT)

Aktiivisen hakemisen sijasta dataa voidaan myös kuunnella. Tähän käytetään MQTT-protokollaa.

Yleistä MQTT:stä

MQTT vastaa kolmesta portista

  1. Suojattu WebSocket osoitteessa rata.digitraffic.fi:443. Esimerkki: https://jsfiddle.net/m20ocg9f/
  2. Suojaamaton WebSocket osoitteessa rata.digitraffic.fi:80. Esimerkki: https://jsfiddle.net/5x96Lo7n/
  3. Normaalin TCP-yhteyden kautta osoitteessa rata-mqtt.digitraffic.fi:1883. TCP-porttiin ei voi selaimessa ottaa suoraan yhteyttä, joten esimerkkiä ei ole mahdollista muodostaa

MQTT:ssä kuunneltava data määritellään topicin avulla. Osia topic:sta voidaan korvata wildcard-merkeillä “#” ja “+”. Esimerkiksi voidaan kuunnella kaikki kokoonpanoja topicista compositions/# tai vain yksittäisen junan kokoonpanoa topicista compositions/+/5/#. Lisätietoa täältä

Junien kuuntelu

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

Esimerkki: https://jsfiddle.net/t6gjuknf/

Paluuarvo

Palauttaa junat-tyyppisiä vastauksia.

Liikennepaikan junien kuuntelu

Topic: trains-by-station/<station>

Esimerkki: https://jsfiddle.net/hm0wute4/

Paluuarvo

Palauttaa junat-tyyppisiä vastauksia.

GPS-sijaintien kuuntelu

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

Esimerkki: https://jsfiddle.net/4fae25yw/

Paluuarvo

Palauttaa GPS-sijainnit-tyyppisiä vastauksia.

Kulkutietoviestien kuuntelu

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

Esimerkki: https://jsfiddle.net/ov94zmep/

Paluuarvo

Palauttaa kulkutietoviestit-tyyppisiä vastauksia.

Kulkutievarauksien kuuntelu

Topic: routesets/<departure_date>/<train_number>

Esimerkki: https://jsfiddle.net/L0v2enb9/

Paluuarvo

Palauttaa kulkutievaraukset-tyyppisiä vastauksia.

Kokoonpanojen kuuntelu

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

Esimerkki: https://jsfiddle.net/g5x9ywnh/

Paluuarvo

Palauttaa kokoonpanot-tyyppisiä vastauksia.

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.

  • Required trainNumber: 1-99999 Info Junan numero. Esim junan “IC 59” junanumero on 59
  • Required departureDate: date Info Junan ensimmäisen lähdön päivämäärä Suomen ajassa
  • Required operatorUICCode: 1-9999 Info Junan operoiman operaattorin UIC-koodi
  • Required operatorShortCode: vr, vr-track, destia, … Info Lista operaattoreista löytyy täältä.
  • Required trainType: IC, P, S, …
  • Required trainCategory: lähiliikenne, kaukoliikenne, tavaraliikenne, …
  • Optional commuterLineID: Z, K, N….
  • Required runningCurrently: true/false Info Onko juna tällä hetkellä kulussa
  • Required cancelled: true/false Info Totta, jos junan peruminen on tehty 10 vuorokauden sisällä. Yli 10 vuorokautta sitten peruttuja junia ei palauteta rajapinnassa laisinkaan.
  • Required version: positive integer Info Versionumero, jossa juna on viimeksi muuttunut
  • Required timetableType: REGULAR tai ADHOC. Info Kertoo onko junan aikataulu haettu säännöllisenä (REGULAR) vai kiireellisenä yksittäistä päivää koskevana (ADHOC).
  • Required timetableAcceptanceDate: datetime. Info Ajanhetki jolloin viranomainen on hyväksynyt junan aikataulun.
  • Optional deleted: true,false Info Kertoo onko juna poistettu eli peruttu yli kymmenen päivää ennen lähtöä.
  • Required timeTableRows Info Kuvaa saapumisia ja lähtöjä liikennepaikoilta. Järjestetty reitin mukaiseen järjestykseen.
    • Required trainStopping true,false Info Pysähtyykö juna liikennepaikalla
    • Required stationShortCode: string Info Aseman lyhennekoodi
    • Required stationcUICCode: 1-9999 Info Aseman UIC-koodi
    • Required countryCode: “FI”, “RU”
    • Required type: “ARRIVAL” tai “DEPARTURE” Info Pysähdyksen tyyppi
    • Optional commercialStop: boolean Info 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.
    • Optional commercialTrack: string Info 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.
    • Required cancelled: true/false Info Totta, jos lähtö tai saapuminen on peruttu
    • Required scheduledTime: datetime Info Aikataulun mukainen pysähtymis- tai lähtöaika
    • Optional liveEstimateTime: datetime Info Ennuste. Tyhjä jos juna ei ole matkalla
    • Optional estimateSource: datetime Info Ennusteen lähde
    • Optional unknownDelay: boolean Info 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
    • Optional actualTime: datetime Info Aika jolloin juna saapui tai lähti asemalta
    • Optional differenceInMinutes: integer Info Vertaa aikataulun mukaista aikaa ennusteeseen tai toteutuneeseen aikaan ja kertoo erotuksen minuutteina
    • Required causes Info Syytiedot. Kuvaavat syitä miksi juna oli myöhässä tai etuajassa pysähdyksellä. Kaikkia syyluokkia ja -tietoja ei julkaista.
      • Required categoryCodeId Info Yleisen syyluokan yksilöivä tunnus. Lista syyluokista löytyy osoitteesta täältä
      • Required categoryCode Info Yleisen syyluokan koodi. Huom. ei yksilöivä.
      • Optional detailedCategoryCodeId Info Tarkemman syykoodin yksilöivä tunnus. Lista syykoodeista löytyy täältä
      • Optional detailedCategoryCode Info Tarkempi syykoodin koodi. Huom. ei yksilöivä
      • Optional thirdCategoryCodeId Info Kolmannen tason syykoodin tunnus. Lista kolmannen tason syykoodeista löytyy täältä
      • Optional thirdCategoryCode Info Kolmannen tason syykoodin koodi. Huom. ei yksilöivä
    • Optional trainReady Info Junan lähtövalmius. Operaattorin tulee tehdä lähtövalmiusilmoitus liikenteenohjaajalle aina kun junan kokoonpanovaihtuu tai se lähtee ensimmäiseltä pysäkiltään.
      • Required source Info Tapa, jolla lähtövalmiusilmoitus on tehty.
      • Required accepted Info Onko lähtövalmiusilmoitus hyväksytty.
      • Required timestamp Info Aika jolloin lähtövalmiusilmoitus on päätetty.

Kokoonpanot

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

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

GPS-sijainnit

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

Kulkutietoviestit

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

Kulkutievaraukset

  • Required version: positive integer Info Versionumero, jossa kulkutievaraus on viimeksi muuttunut
  • Required messageTime: datetime Info Aikaleima jolloin kulkutievaraus on luettu
  • Required trainNumber: string Info Junan numero. Esim junan “IC 59” junanumero on 59
  • Optional departureDate: date Info Junan ensimmäisen lähdön päivämäärä Suomen ajassa. Voi olla tyhjä tapauksissa, jossa junan aikataulua ei tunneta.
  • Required routeType: character Info Varauksen tyyppi. T=junakulkutie, S=vaihtokulkutie ja C=kulkutien purkaminen
  • Required clientSystem: string Info Kulkutievarauksen luoneen kauko-ohjausjärjestelmän nimi
  • Required routesections Info Lista raideosuuksista/vaihteista/elementeistä, jotka on varattu kulkutieksi
    • Required sectionId: string Info Varattavan osuuden tunnus
    • Required stationCode: string Info Liikennepaikka, jossa varaus sijaitsee
    • Optional commercialTrackId: string Info Raiteen kaupallinen tunnus

Liikennepaikat

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

Operaattorit

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

Syyluokat

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

Syykoodit

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

Kolmannen tason syykoodit

  • Required id: positive integer Info Kolmannen tason syykoodin yksilöivä tunnus
  • Required thirdCategoryCode: string Info Kolmannen tason syykoodin tunnus
  • Required thirdCategoryName: string Info Kolmannen tason syykoodin suomenkielinen nimi
  • Required validFrom: string Info Ajanhetki jolloin kolmannen tason syykoodin astuu voimaan. Ajanhetki viittaa junan lähtöpäivämäärään.
  • Optional validTo: string Info 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.
  • Optional passengerTerm Info Matkustajatiedotustermi. Matkustajaläheinen kuvaus kolmannen tason syykoodista
    • Required fi: string Info Suomenkielinen käännös
    • Required en: string Info Englanninkielinen käännös
    • Required sv: string Info Ruotsinkielinen käännös

Junalajit

  • Required name: string Info Junalajin nimi

Junatyypit

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

Raideosuudet

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

Herätepisteet

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

Aikataulukaudet ja muutosajankohdat

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

Versiohistoria

  • Required version: positive integer Info Versionumero
  • Required id Info Versiotiedon yksilöivät tiedot
    • Required trainNumber: positive integer Info Junanumero
    • Required departureDate: date Info Junan ensimmäisen lähdön päivämäärä Suomen ajassa
    • Required fetchDate: date Info Ajanhetki, jolloin versio on syntynyt
  • Required json: json Info Version json-sisältö

Ilmoituksen status

  • Required id: string Info Ilmoituksen yksilöivä OID-tunniste
  • Required version: positive integer Info Uusin versionumero
  • Required modified: date Info Uusimman version muokkausaika

Matkustajainformaation tiedotteet

  • Required id: string Info Tiedotteen yksilöivä merkkijonotunniste
  • Required version: positive integer Info Tiedotteen uusin versionumero
  • Required creationDateTime: date Info Tiedotteen uusimman version luontipäivämäärä
  • Required startValidity: date Info Tiedotteen voimassaolon alkupäivämäärä
  • Required endValidity: date Info Tiedotteen voimassaolon loppupäivämäärä
  • Required stations: string[] Info Lista tiedotteeseen liittyvien asemien lyhenteistä
  • Optional trainNumber: positive integer Info Tiedotteeseen liittyvän junan numero
  • Optional trainDepartureDate: date Info Tiedotteeseen liittyvän junan lähtöpäivämäärä
  • Optional audio: object Info Tiedotteen audioversion tekstisisällöt ja esityssäännöt
    • Optional text: object Info Tiedotteen tekstisisällöt
      • Optional fi: string Info Tiedotteen tekstisisältö suomeksi
      • Optional sv: string Info Tiedotteen tekstisisältö ruotsiksi
      • Optional en: string Info Tiedotteen tekstisisältö englanniksi
    • Optional deliveryRules: object Info Tiedotteen audiosisältöön liittyvät esityssäännöt
      • Optional startDateTime: date Info Esityksen alkupäivämäärä
      • Optional endDateTime: date Info Esityksen loppupäivämäärä
      • Optional startTime: date Info Esityksen alkuaika
      • Optional endTime: date Info Esityksen loppuaika
      • Optional weekDays: string[] Info Lista viikonpäivistä, joina tiedotetta esitetään
      • Optional deliveryType: enum[“NOW”, “DELIVERY_AT”, “REPEAT_EVERY”, “ON_SCHEDULE”, “ON_EVENT”] Info NOW: tiedote esitetään sen luontihetkellä DELIVERY_AT: Tiedote esitetään kentän deliveryAt osoittamana ajankohtana. REPEAT_EVERY: Tiedotetta toistetaan päivämäärästä startDateTime ja kellonajasta startTime päivämäärään endDateTime ja kellonaikaan endTime asti. Tiedotetta toistetaan kentän repetitions osoittama määrä kentän repeatEvery osoittaman minuuttivälin mukaisesti niinä viikonpäivinä, jotka ovat listassa weekDays. ON_SCHEDULE: Tiedote esitetään siihen liittyvän junan aikataulunmukaisena saapumisaikana. ON_EVENT: Tiedote esitetään, kun siihen liittyvä juna joko saapuu tai lähtee asemalta kentän eventType (esim. ARRIVING) mukaisesti listassa stations määritellyllä asemalla.
      • Optional repeatEvery: integer Info Tiedotteen esitysväli minuutteina kun deliveryType on REPEAT_EVERY
      • Optional repetitions: integer Info Tiedotteen esityksen toistojen määrä kun deliveryType on REPEAT_EVERY
      • Optional eventType: enum[“ARRIVING”, “DEPARTING”] Info Tapahtuma, jonka yhteydessä tiedote esitetään kun deliveryType on ON_EVENT
      • Optional deliveryAt: date Info Ajankohta, jona tiedote esitetään kun deliveryType on DELIVERY_AT
  • Optional video: object Info Tiedotteen videoversion tekstisisällöt ja esityssäännöt
    • Optional text: object Info Tiedotteen tekstisisällöt
      • Optional fi: string Info Tiedotteen tekstisisältö suomeksi
      • Optional sv: string Info Tiedotteen tekstisisältö ruotsiksi
      • Optional en: string Info Tiedotteen tekstisisältö englanniksi
    • Optional deliveryRules: object Info Tiedotteen videosisältöön liittyvät esityssäännöt
      • Optional startDateTime: date Info Esityksen alkupäivämäärä
      • Optional endDateTime: date Info Esityksen loppupäivämäärä
      • Optional startTime: date Info Esityksen alkuaika
      • Optional endTime: date Info Esityksen loppuaika
      • Optional weekDays: string[] Info Lista viikonpäivistä, joina tiedotetta esitetään
      • Optional deliveryType: enum[“CONTINUOS_VISUALIZATION”, “WHEN”] Info * CONTINUOS_VISUALIZATION: Tiedotetta esitetään jatkuvasti välillä startDateTime - endDateTime. Mikäli startTime on määritelty, alkaa tiedotteen esittäminen sen osoittamaan kellonaikaan kentän startDateTime mukaisena päivämääränä (tällöin kentän startDateTime kellonajalla ei ole merkitystä). Sama pätee kenttiin endTime ja endDateTime esityksen loppuajankohdan suhteen. WHEN: Tiedotetta esitetään päivämäärävälillä startDateTime - endDateTime ainoastaan kenttien startTime ja endTime osoittamien kellonaikojen välillä kentässä weekDays määriteltyinä viikonpäivinä.*

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.

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

bug_reportLöysitkö virheen? Auta meitä parantamaan tätä sivua.