Integraatio-ohje TVV LMJ Liikennöintitietojen Hallinta Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy
MUUTOSHISTORIA Versio Päivämäärä Tekijä Muutokset 0.1 24.10.2013 Pekka Kaarela/MTS Ensimmäinen versio 0.2 30.10.2013 Pekka Kaarela/MTS Täsmennetty palaverin 29.10.2013 perusteella käyttöoikeuksien kannalta sekä pysäkkitietojen siirron kannalta. 0.3 05.11.2013 Pekka Kaarela/MTS calendar_dates.txt täsmennetty 0.4 06.11.2013 Pekka Kaarela/MTS Täsmennyksiä integraatioiden yleiseen toimintatapaan. Täsmennetty ylikirjoitussääntöjä. Pysäkille lisätty URL-tieto. 0.5 12.11.2013 Pekka Kaarela/MTS Lisätty käyttöoikeusmatriisi lukuun 2.2. Täsmennetty validointivaatimusta lukuun 2.4. Lisätty lukuun 5.1 tietoa voimaanastumisesta ja nostettu aikataulukausien määrä viiteen. Lisätty lukuun 5.3 ajastustarve. Täsmennetty eri rajapintojen käyttötarkoitusta. URL:eihin päivietty integraation osoituksia. 0.6 26.11.2013 Pekka Kaarela Täsmennyksiä. Lisätty sääntö, että aineiston haku on mahdollinen vain, jos vyöhyketieto on olemassa kaikilla pysäkeillä. 1.0 24.01.2014 Pekka Kaarela Asiakkaan hyväksyntä 1.1 25.01.2014 Pekka Kaarela Täsmennyksiä luvun 3 alkuun: esimerkiksi tietojen säilyttämiseen liittyen. Poistettu rajoite voimassaololtaan päällekkäisistä kalentereista. Block_id lisätty järjestelmään. 1.2 25.02.2014 Pekka Kaarela agency_id lisätty järjestelmään routes.txt tiedostoon. 1.3 05.03.2014 Pekka Kaarela Täsmennys agency.txt:n käsittelyyn lukuun 5.1 1.4 30.03.2014 Pekka Kaarela Luvussa 3.2.2 mainittu automaattinen vyöhykkeen asettaminen vyöhykkeeksi 1 tilanteessa, jossa vyöhykettä ei anneta, on poistettu. Poistettu luvusta 5.3 rajoite, jonka mukaan liikennöintitietoja ei voi hakea, jos jollain pysäkillä ei ole vyöhykettä. Lukuun 5.1.1 täsmennetty vyöhyketiedon siirtoa. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy
Täsmennetty virheenhallintaa ja poistamisasiaa luvun 5 alkuun sekä lukuun 5.1.1. Täsmennetty tietojen säilyttämistä lukuun 5.1.3 Täsmennetty lukua 5.1.4 1.5 10.04.2014 Pekka Kaarela Kuva 1 päivitetty. lines.txt muutettu routes.txt 1.6 21.05.2014 Pekka Kaarela Rajapintojen URL:ja täsmennetty. Lukuun 2.4 lisätty täsmennys tunnisteisiin. Luku 4 täydennetty. Tarkennettu, että tunnisteet ovat palveluntuottajarekisterissä. 1.7 23.05.2014 Pekka Kaarela Lyhytnimitunnisteiden sijasta käytetään numeromuotoisia tunnisteita. Luku Varikkojärjestelmärajapinta poistettu. 1.8 26.06.2014 Pekka Kaarela Sopimustyyppien numeroarvot muutettu. 1.9 18.08.2014 Pekka Kaarela Sopimustyyppi lisätty. 1.10 06.11.2014 Pekka Kaarela Muunnettu.doc muotoon 1.11 7.11.2014 Anne Seppälä Siirretty LMJ-pohjalle Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy
SISÄLLYSLUETTELO Muutoshistoria... 2 1 Johdanto... 1 1.1 Asiakirjan tarkoitus... 1 1.2 Termit ja lyhenteet... 1 1.3 Viitteet... 1 2 Järjestelmän yleiskuvaus... 2 2.1 Tarkoitus ja toiminta... 2 2.2 Käyttäjäryhmät ja käyttöoikeudet... 2 2.3 Käyttöoikeuksien hallinta... 2 2.4 Käyttöympäristövaatimukset... 3 3 Integraatioiden yleiset toimintaperiaatteet... 4 3.1 Poikkeamat GTFS-standardista... 4 3.1.1 Pysäkkien ja linjojen nimien lokalisointi... 4 3.1.2 TVV:n ja liikennöitsijän sopimustieto... 4 3.2 Täsmennykset GTFS-formaattiin... 5 3.2.1 Tiedoston nimeäminen... 5 3.2.2 Tiedostojen ja kenttien täsmennykset... 5 4 Tunnistautuminen... 7 5 Suunnittelujärjestelmärajapinta... 8 5.1 Liikennöintitietojen tuonti... 8 5.1.1 Pysäkkitietojen siirto... 9 5.1.2 Perustietojen siirto... 10 5.1.3 Koko aikatauluaineiston siirto... 11 5.1.4 Linjakohtainen lähtöjen siirto... 11 5.2 Liikennöintitietojen poistaminen... 12 5.3 Liikennöintitietojen haku... 12 6 Feed-julkaisurajapinta... 13 Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy
1 JOHDANTO 1.1 Asiakirjan tarkoitus Tämä dokumentti on integroitumisohje järjestelmälle, jossa hallinnoidaan toimivaltaisten viranomaisten joukkoliikenteen aikatauluaineistoja. 1.2 Termit ja lyhenteet Tässä dokumentissa käytetään seuraavia erikoiskäsitteitä, termejä ja lyhenteitä: Termi GTFS Liikennöitsijä Syöte TVV Selitys General Transit Feed Specification. Tietomalli ja formaatti aikatauluaineiston siirtämiseksi järjestelmien välillä. [GTFS] Agency. Yhtä tai usempaa linjaa operoiva organisaatio. Feed. GTFS-tiedot sisältävä zip-paketti. Toimivaltainen viranomainen. TVV päättää omalla viranomaisalueellaan mm. joukkoliikenteen palvelutasosta, järjestämistavasta sekä lippu- ja tariffijärjestelmästä. 1.3 Viitteet Viite GTFS GTFS_REFERENCE Dokumentti https://developers.google.com/transit/overview https://developers.google.com/transit/gtfs/reference Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 1(13)
2 JÄRJESTELMÄN YLEISKUVAUS 2.1 Tarkoitus ja toiminta Liikennöintitietojen hallintajärjestelmä hallitsee usean TVV:n joukkoliikenteen liikennöintitietoja ja välittää näitä tietoja eri järjestelmien välillä. Järjestelmiä voivat olla esimerkiksi TVV:n tai liikennöitsijän liikenteen suunnittelujärjestelmä, liikennöitsijän varikkojärjestelmä tai kolmannen osapuolen matkustajainformaatiojärjestelmä. Järjestelmä mahdollistaa aikataulun suunnittelun järjestelmän käyttöliittymässä ja tietojen tuomisen järjestelmään integraation kautta. Integraatioiden kautta tuodaan tiedot järjestelmään GTFS-formaatissa. Järjestelmän palvelimet ovat osa TVV LMJ-palvelinarkkitehtuuria. 2.2 Käyttäjäryhmät ja käyttöoikeudet Taulukossa on esitelty ne käyttäjäryhmät, joilla on oikeus integroitua järjestelmään. Järjestelmää käytetään myös käyttöliittymän kautta ja nämä oikeudet on esitelty erillisessä käyttöohjeessa. Käyttäjäry hmä Oikeudet / Rajapinta Pysäkkitietojen siirto Perustietojen siirto Koko aikatauluai neiston siirto Linjakohtai nen lähtöjen siirto Liikennöintitietojen poistaminen Liikennöintitietojen haku Feed-julkaisurajapinta TVV:n joukkoliike nteen suunnittelij a Oikeus (oma alue) Oikeus (oma alue) Oikeus (oma alue) Oikeus omien linjojen osalta Oikeus (oma alue) Oikeus (oma alue) Oikeus Liikennöits ijän omien linjojen suunnittelij a Ei oikeutta Ei oikeutta Ei oikeutta Oikeus omien linjojen osalta Ei oikeutta Oikeus Oikeus Kolmas osapuoli Ei oikeutta Ei oikeutta Ei oikeutta Ei oikeutta Ei oikeutta Ei oikeutta Oikeus 2.3 Käyttöoikeuksien hallinta Käyttöoikeuksia hallitaan TVV LMJ -järjestelmän yhteisessä käyttöoikeuksien hallintajärjestelmässä. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 2(13)
Käyttäjälle asetetaan organisaatio, organisaation tyyppi ja rooli. Näiden sekä liikennöintitietojen hallintajärjestelmässä erikseen annettujen lisäoikeuksien perusteella järjestelmän käyttöoikeuden omaavat käyttäjät tai järjestelmät voivat katsella ja muokata järjestelmän tietoja. TVV voi merkitä integraatiossa tai järjestelmän käyttöliittymässä haluamiensa linjojen osalta liikennöitsijälle oikeuden muokata linjojen reittejä ja lähtöjä. Tällöin liikennöitsijälle mahdollistuu linjakohtainen lähtöjen siirto. 2.4 Käyttöympäristövaatimukset Järjestelmän rajapinnat on toteutettu RESTful-periaatteiden mukaisesti. Rajapinnan käyttö tulee toteuttaa palvelinten välisellä integraatiolla. Järjestelmään lähetettävä GTFS feed on validoitava ennen käyttöä Googlen validointityökaluin (https://developers.google.com/transit/tools#gtfsvalidation). On huomattavaa, että järjestelmä hyväksyy myös zip-tiedostoja, joista puuttuu GTFS:n pakollisia tiedostoja. Integroijan on tunnistettava nämä virheet sellaisiksi, että ne eivät ole este integraatiolle tietyissä tapauksissa, esimerkiksi pysäkkitietojen siirrossa. Rajapinnoissa käytetyt TVV- ja liikennöitsijätunnisteet ovat tunnisteita palveluntuottajarekisterissä. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 3(13)
3 INTEGRAATIOIDEN YLEISET TOIMINTAPERIAATTEET Järjestelmä hallitsee tietoja GTFS-tietomallin puitteissa. Tiettyjen tietojen osalta GTFS-määritystä on jouduttu laajentamaan, jotta tieto voidaan välittää sekä järjestelmään että järjestelmästä pois päin. Järjestelmässä hallitaan liikennöintitietoja TVV-kohtaisesti. Esimerkiksi järjestelmästä voi hakea tietoja vain yhden TVV:n tiedot kerralla. Järjestelmä tukee tietojen syöttämistä sekä manuaalisesti käyttöliittymästä että integraation avulla järjestelmien välisen liittymän kautta. o Integraatiolla järjestelmään tuodut tiedot ylikirjoittavat järjestelmässä kaiken jo mahdollisesti olevan tiedon käyttöoikeuksien rajoissa säästäen tietyt GTFS:n valinnaiset tiedot. Myös sellaiset tiedot, joita integraatiossa ei tule, poistetaan järjestelmästä. Näin ollen järjestelmään ei ole suotavaa tuoda pelkästään esimerkiksi tulevaisuuden aikataulukautta, mikäli nykyisen aikataulukauden tulee säilyä järjestelmässä. o Tiettyjen GTFS:ssä olevien valinnaisten tietojen osalta integraatio ei ylikirjoita käyttöliittymästä annettua tietoa, mikäli integraatiossa ei kyseistä täydentävää tietoa tule järjestelmässä olemassa olevalle elementille. Näitä ovat pysäkin matkustajatunniste, pysäkin vyöhykkeen tunniste, pysäkin URL ja sopimustieto. Edellytyksenä tälle on se, että tunnisteet pysyvät integraatiosta toiseen samana. Jos valinnaisen tiedon tunniste ei esiinny tiedoston otsikkorivillä, kyseinen tieto säilytetään järjestelmässä. 3.1 Poikkeamat GTFS-standardista 3.1.1 Pysäkkien ja linjojen nimien lokalisointi Syötteen kieli on suomi fi ja järjestelmä vaatii jokaiselle tiedolle vähintään suomen kielisen tekstin. Käyttäjä voi määritellä ruotsinkielisen kieliversion pysäkin ja linjan nimelle. Nämä tiedot välitetään GTFS:n translations.txt-tiedostossa kielikoodilla sv. translations.txt-tiedoston käyttö on epävirallinen laajennus GTFS-standardiin ja se on kuvattu dokumentissa https://support.google.com/transitpartners/answer/2450962 3.1.2 TVV:n ja liikennöitsijän sopimustieto Rajapinnassa välitetään sopimustieto erillisessä tiedostossa contracts.txt. Tiedostoformaatti on vastaava kuin GTFS:n muissa txt-tiedostoissa. Yksi rivi on yksi contract, ja rivin sisällä kentät on pilkulla erotettu. Ensimmäisen rivin pitää sisältää sarakkeiden otsikot pilkuilla erotettuna. Jokaista linjaa (GTFS:n route) kohden täytyy olla yksi sopimusrivi. Tiedoston pakollisuus: Valinnainen Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 4(13)
Kentän nimi Pakollisuus Yksityiskohdat contract_id Pakollinen Sopimukseen liittyvä vapaamuotoinen tunnistetieto, jolla voidaan esimerkiksi viitata johonkin toisessa järjestelmässä olevaan sopimukseen. contract_type Pakollinen contract_type kuvaa TVV:n ja liikennöitsijän sopiman liikenteen järjestämistavan tietyn linjan osalta. Käytettävät arvot ovat: 1 Käyttöoikeussopimusmalli 4 Siirtymäajan liikenne 6 Bruttomalli 10 Markkinaehtoinen liikenne Arvoja voi tulla jatkossa lisää. update_permission Pakollinen update_permission-kentällä annetaan oikeus liikennöitsijälle päivittää tähän sopimukseen liittyvän linjan aikataulutietoja Käytettävät arvot ovat: 0 Ei-oikeutta 1 Päivitysoikeus route_id Pakollinen Linjan id, johon tämä sopimus liittyy. Yhteen linja_id:hen voi liittyä vain yksi sopimus. 3.2 Täsmennykset GTFS-formaattiin 3.2.1 Tiedoston nimeäminen Tiedosto on nimettävä muodossa <TVV:n organisaatiotunniste>.zip esimerkiksi 245.zip. Numero 245 on Tampereen tunniste palveluntuottajarekisterissä. TVV:n organisaatiotunniste on siis se organisaatiotunniste, joka TVV:lle on annettu palveluntuottajarekisteriin. 3.2.2 Tiedostojen ja kenttien täsmennykset Järjestelmä hyödyntää GTFS-formaatista vain pakollisia tiedostoja ja kenttiä taulukossa (Taulukko 1) mainituin täsmennyksin. Taulukko 1. Kenttien täsmennykset Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 5(13)
Tiedosto Kenttä Selite agency.txt agency_id Kenttään tulee laittaa liikennöitsijän se yksilöllinen organisaatiotunniste, joka liikennöitsijälle on annettu palveluntuottajarekisteriin. stops.txt stop_id Kenttään tulee laittaa pysäkin selväkielinen yksilöllinen tunniste esimerkiksi 0504. Samalla pysäkillä tulee olla sama tunniste jokaisessa uudessa datan latauksessa. stop_code Valinnainen kenttä, joka luetaan järjestelmään. zone_id stop_url Kentän käyttö on suositeltavaa, jotta matkustajille voidaan näyttää järkevä pysäkin koodi, mikäli stop_id:ssä käytetään lisätunnistetta esimerkiksi tampere_0502. Valinnainen kenttä, joka luetaan järjestelmään. Mikäli kenttä on annettu, tulee kenttään laittaa numero arvoalueella 1-10. Valinnainen kenttä, joka luetaan järjestelmään. Tähän kenttään voi laittaa esimerkiksi Digiroad-järjestelmässä olevan pysäkin valtakunnallisen tunnisteen. URL:n tulee alkaa http:// tai https:// ja mahdolliset erikoismerkit tulee olla oikein käsitelty (ks: http://www.w3.org/addressing/url/4_uri_recommentations.html). routes.txt agency_id Kentän käyttö on kuitenkin pakollista, jotta voidaan määritellä, mikä liikennöitsijä linjaa ajaa. GTFS:n mukaan valinnainen kenttä, joka luetaan järjestelmään. trips.txt direction_id Valinnainen kenttä, joka luetaan järjestelmään. block_id Kentän käyttö on erittäin suositeltavaa, jotta lähdöt voidaan erotella järjestelmässä suunnittain. Mikäli kenttää ei ole annettu, järjestelmä asettaa kaikkien lähtöjen suunnaksi 1. Valinnainen kenttä, joka luetaan järjestelmään. calendar_dates.txt Kenttää käytetään autokierron tunnisteena. Mikäli aikataulusuunnitelma sisältää erikoispäiviä, tulee käyttää GTFS:n calendar_dates.txttiedostoa GTFS-dokumentaatiossa [GTFS_REFERENCE] määritellyn recommended -mallin mukaisesti. Tiedosto voi sisältää palveluaikoja, joita ei ajeta yhtenäkään viikonpäivänä (päivätyyppinä), mutta joille on tehty päivävaihtoja. Tällaisella järjestelyllä on luotu erikoispäivä, joka ajetaan vain tiettyinä kalenteripäivinä. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 6(13)
4 TUNNISTAUTUMINEN Rajapintojen käyttöön tarvittavat tunnukset ja IP-osoitteet ovat pyydettävissä TVV LMJ -organisaatiolta. Järjestelmän pääkäyttäjä luo rajapintaa käyttävälle järjestelmälle oman teknisen tunnuksen, jonka tiedot toimitetaan tekniselle yhteyshenkilölle sähköpostilla. Tietoturvasyistä tunnus ja salasana toimitetaan erillisissä sähköposteissa. Mikäli tunnukseen liittyen on ongelmia tai salasanaa on tarve vaihtaa, tekee järjestelmän pääkäyttäjä tarvittavat toimenpiteet. Teknistä tunnusta ei saa käyttää mihinkään muuhun tarkoitukseen kuin rajapinnan autentikointiin. Yhteyden autentikointi tapahtuu SAML ECP-profiililla. Katso tarkemmat ohjeet mekanismin toteuttamisesta dokumentista Piletti Web Services Authentication For Third Parties.docx Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 7(13)
5 SUUNNITTELUJÄRJESTELMÄRAJAPINTA Suunnittelujärjestelmärajapinnan kautta järjestelmässä voi hallita kaikkia liikennöintiin liittyviä tietoja käyttöoikeuksien puitteissa. Järjestelmään voi tuoda tietoja seuraavilla tavoilla: Täydellisiä aikatauluaineistoja tässä dokumentissa määritellyin laajennuksin Perustiedot, sisältäen liikennöitsijätiedot, sopimukset, pysäkit, linjat ja kalenterin Yksittäisten linjojen aikatauluja Pysäkkien tietoja Mikäli integraation yhteydessä tapahtuu virhe, järjestelmä palauttaa tiedot integraatiota edeltäneeseen tilanteeseen. Järjestelmästä voi poistaa yksittäisiä aikataulukausia. Järjestelmästä voi hakea aikatauluaineistoja sisältäen dokumentissa määritellyt laajennukset. Esitellyissä osoitteissa kohtaan {authority} laitetaan palveluntuottajarekisterissä oleva TVV:n tunniste. Esimerkiksi Tampereen tunniste on 245. 5.1 Liikennöintitietojen tuonti Huomioitavia seikkoja Tiedostojen tulee täyttää vaatimukset, jotka on listattu GTFS-määrittelyn [GTFS_REFERENCE] kohdassa File Requirements Järjestelmään voi tuoda vain täydellisiä aineistoja sisältäen perustiedot. Näin viite-eheydet ovat oikein tietoja siirrettäessä. Järjestelmä siirtää datasta järjestelmään vain ne osat, joihin käyttäjällä on oikeus. Jotta linjakohtainen siirto on mahdollista, pitää perustietojen id:t (agency_id, stop_id, route_id, service_id) pitää samoina aikatauluaineiston siirrosta toiseen. Vain näin voi toinen osapuoli hakea perustiedot ja rikastaa ne aikataulutiedolla omassa järjestelmässään Järjestelmä käyttää agency.txt-tiedostosta vain id-tietoa. Järjestelmään ei siis siirretä agency.txttiedoston sisältämiä tietoja, vaan järjestelmä ylläpitää liikennöitsijöiden tietoja erillisellä integraatiolla palveluntuottajien hallintajärjestelmästä. Järjestelmään tulee siirtää aina kaikki tiedot, joihin käyttäjällä on oikeus, sillä järjestelmässä olevat tiedot korvataan uudella aineistolla. Esimerkiksi jos käyttäjällä on oikeus tuoda järjestelmään linjojen A ja B aikatauluaineisto, täytyy molemmat aikatauluaineistot tuoda kerralla järjestelmään. o Perustietoja voi täydentää siirtämällä vain ne järjestelmään. Tällöinkin korvataan järjestelmässä jo olevat perustiedot huomioiden kohdassa 3 Integraatioiden yleiset toimintaperiaatteet mainitut seikat. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 8(13)
Kun järjestelmään siirretään perustietoja tai lähtöjä, jotka ovat voimassa, nämä ovat välittömästi integraation päättymisen jälkeen muiden järjestelmien hyödynnettävissä. Aineisto lähetetään POST-metodilla content-typen ollessa multipart/form-data Järjestelmässä voi säilyttää vain viiden aikataulukauden aineistoa, esimerkiksi o kaksi aikatauluaineistoa, joiden voimassaoloaika on päättynyt o nykyinen aikataulukausi o kaksi seuraavaa aikataulukautta TVV:n Liikennöintitiedot Lähdöt Koko aikatauluaineiston siirto stops.txt routes.txt contracts.txt agency.txt calendar.txt calendar_dates.txt trips.txt stop_times.txt translations.txt Perustietojen siirto stops.txt routes.txt contracts.txt agency.txt calendar.txt calendar_dates.txt translations.txt Kalenteri Linjat - sopimukset Liikennöitsijät Pysäkit Pysäkkitietojen siirto stops.txt translations.txt Linjakohtainen lähtöjen siirto stops.txt routes.txt contracts.txt agency.txt calendar.txt calendar_dates.txt trips.txt stop_times.txt Kuva 1 Erilaiset tavat tuoda järjestelmään tietoja. Kuvassa Kuva 1 esitellään erilaiset tavat tuoda järjestelmään tietoja. Vahvennetulla tekstillä merkityt tiedostot siirretään järjestelmään. 5.1.1 Pysäkkitietojen siirto Mikäli käyttäjällä on oikeus pysäkkien muokkauksessa järjestelmään, järjestelmä toimii seuraavasti: Rajapinta on tarkoitettu toimivaltaisen viranomaisen käyttöön pysäkkitietojen siirtoa varten, jotta tämän jälkeen liikenne voidaan suunnitella tuotujen pysäkkitietojen pohjalta järjestelmän käyttöliittymässä. Rajapinnalla voidaan myös ylläpitää pysäkkitietoja, mikäli esimerkiksi pysäkkien koordinaatteja ylläpidetään pääasiallisesti toisessa järjestelmässä. Ensimmäistä kertaa tietoja siirrettäessä järjestelmä siirtää kaikki pysäkkien tiedot järjestelmään. Mikäli seuraavissa integraatioissa vyöhyketieto ei ole integraatiossa mukana, järjestelmässä olevien pysäkkien tiedot päivitetään muilta kuin vyöhyketiedon osalta. Näin käyttäjä voi ylläpitää vyöhyketietoa järjestelmän käyttöliittymässä edellyttäen, että käyttäjä ei muuta pysäkin tunnistetta integraatioiden välillä. Vyöhyketiedon poisjättäminen tarkoittaa sitä, että tiedostosta tulee jättää kokonaan zone_id-otsikko pois tiedoston otsikkoriviltä. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 9(13)
Ne pysäkit, joita integraatiossa ei ole mukana, poistetaan järjestelmästä tai annetaan virheilmoitus, jos poistaminen ei ole mahdollista. Poistaminen ei ole esimerkiksi mahdollista, jos jokin reitti käyttää puuttuvaa pysäkkiä. Pysäkkitietojen siirrossa muut perustiedot ja aikatauluaineistotiedot pysyvät ennallaan. URL: POST http(s)://{ip-address}:{port}/tdm-service/rest/data/authorities/{authority}/stops Huomioitavia seikkoja järjestelmä hyväksyy pelkän pysäkkitietojen päivityksen Siirrossa siirretään järjestelmään seuraavat tiedostot: stops.txt translations.txt valinnainen 5.1.2 Perustietojen siirto URL: POST http(s)://{ip-address}:{port}/tdm-service/rest/data/authorities/{authority}/basedata Huomioitavia seikkoja Rajapinta on tarkoitettu toimivaltaisen viranomaisen käyttöön liikennöinnin perustietojen siirtoa varten, jotta liikennöitsijät voivat tämän jälkeen tuoda oman liikenteen suunnitelman järjestelmään. Integraatio säilyttää järjestelmässä mahdollisesti jo olevat lähdöt. Mikäli kannassa on jo olemassa aikatauluaineistoa, tulee siirrettävien tiedostojen viite-eheys olla voimassa kannassa olevien tietojen kanssa. Toisin sanoen samoille pysäkeille, linjoille ja kalentereille tulee ylläpitää samoja id-tietoja (stop_id, route_id, agency_id ja service_id). Järjestelmässä jo olevat perustiedot korvataan huomioiden kohdassa 3 Integraatioiden yleiset toimintaperiaatteet mainitut seikat. Järjestelmästä poistetaan ne tiedot, joihin ei ole viittauksia integraatiossa olevissa tiedoissa tai annetaan virheilmoitus, jos poistaminen ei ole mahdollista. Perustietojen siirrossa siirretään järjestelmään vain seuraavat tiedostot: agency.txt stops.txt routes.txt calendar.txt calendar_dates.txt valinnainen, mikäli ei ole määritelty poikkeuksia kalenteriin translations.txt valinnainen contracts.txt valinnainen Järjestelmä hyväksyy siis zip:n, josta puuttuvat trips.txt ja stop_times.txt -tiedostot. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 10(13)
5.1.3 Koko aikatauluaineiston siirto URL: POST http(s)://{ip-address}:{port}/tdm-service/rest/data/authorities/{authority} Huomioitavia seikkoja Rajapinta on tarkoitettu toimivaltaisen viranomaisen käyttöön koko aikatauluaineiston siirtoa varten järjestelmään. Järjestelmästä poistetaan ne TVV:n hallinnoimat olemassa olevat tiedot, joihin ei ole viittauksia integraatiossa olevissa tiedoissa. Kaikkien tarvittavien aikataulukausien tulee siis olla siirrossa mukana. Rajapinta säilyttää liikennöitsijän syöttämät reitit ja lähdöt. Toisaalta rajapinta palauttaa virheilmoituksen, mikäli syötteestä puuttuu tietoja, joihin liikennöitsijöiden määrittelemät reitit ja lähdöt viittaavat. Järjestelmässä jo olevat perustiedot korvataan huomioiden kohdassa 3 Integraatioiden yleiset toimintaperiaatteet mainitut seikat. Siirrossa siirretään järjestelmään seuraavat tiedostot: agency.txt stops.txt routes.txt trips.txt stop_times.txt calendar.txt calendar_dates.txt valinnainen, mikäli ei ole määritelty poikkeuksia kalenteriin translations.txt valinnainen contracts.txt valinnainen 5.1.4 Linjakohtainen lähtöjen siirto URL: POST http(s)://{ip-address}:{port}/tdm-service/rest/data/authorities/{authority}/trips Huomioitavia seikkoja Rajapinta on suunniteltu liikennöitsijän käyttöön, jotta liikennöitsijä voi tuoda järjestelmään vain oman liikenteensä. Jotta rajapinnan kautta voi välittää tietoja, on toimivaltaisen viranomaisen täytynyt tähän erikseen antaa järjestelmässä oikeus. Rajapinnan avulla myös toimivaltainen viranomainen voi päivittää pelkästään omat lähdöt. Rajapintaa käyttävän järjestelmän on ensin haettava järjestelmästä pysäkit, liikennöitsijät, linjat ja kalenterit (5.3 Liikennöintitietojen haku), joihin lähdöt liitetään. Lähdöt liitetään niihin tunnisteisiin, jotka perustiedoissa tulevat. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 11(13)
Järjestelmään tulee siirtää aina kaikki tiedot, joihin käyttäjällä on oikeus, sillä järjestelmässä olevat tiedot korvataan uudella aineistolla. Esimerkiksi jos käyttäjällä on oikeus tuoda järjestelmään linjojen A ja B aikatauluaineisto, täytyy molemmat aikatauluaineistot tuoda kerralla järjestelmään. Mikäli integraatiossa tulee mukana aineistoa, johon käyttäjällä ei ole muokkausoikeutta. Näitä tietoja ei päivitetä järjestelmään. Siirrossa tulee olla mukana seuraavat tiedostot: agency.txt stops.txt routes.txt calendar.txt trips.txt (vain tämän tiedoston sisältö integroidaan järjestelmään) stop_times.txt (vain tämän tiedoston sisältö integroidaan järjestelmään) 5.2 Liikennöintitietojen poistaminen Liikennöintitietoja voi poistaa metodilla DELETE: URL: DELETE http(s)://{ip-address}:{port}/tdmservice/rest/data/authorities/{authority}/calendars/{service_id} Komennolla poistetaan kaikki ne lähdöt ja kyseinen kalenteri, jotka viittaavat mainittuun service-id:hen. Tietokannasta ei poisteta liikennöitsijöitä, sopimuksia, pysäkkejä ja linjojen perustietoja. Rajapinta on tarkoitettu toimivaltaisen viranomaisen käyttöön. 5.3 Liikennöintitietojen haku URL: GET http(s)://{ip-address}:{port}/tdm-service/rest/data/authorities/{authority} Komennolla haetaan koko TVV:n aikatauluaineisto sisältäen sopimustiedot. Rajapinta on tarkoitettu toimivaltaisen viranomaisen ja liikennöitsijän käyttöön koko aikatauluaineiston hakua varten. Esimerkiksi varikkojärjestelmät käyttävät tätä rajapintaa. Rajapinnasta tulee pääsääntöisesti hakea tiedot tiettynä kellonaikana yöaikaan. Jokaiselle toimivaltaiselle viranomaiselle ja liikennöitsijälle annetaan ylläpidon toimesta kellonaika, jolloin haku tulee tehdä. Satunnaisesti rajapintaa voi kutsua myös mihin tahansa muuhun aikaan esimerkiksi pikapäivityksen tuotantoon ottoa varten. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 12(13)
6 FEED-JULKAISURAJAPINTA Rajapinta on tarkoitettu sellaisia kolmansien osapuolten järjestelmiä varten, jotka tarvitsevat joukkoliikenteen suunnittelutietoja. FEED-julkaisurajapinta eroaa seuraavasti suunnittelujärjestelmärajapinnasta - rajapinnan kautta on saatavilla järjestelmässä aamuyön eräajossa ennalta muodostettua aineistoa - rajapintaa tulee kolmannen osapuolen kutsua korkeintaan kerran päivässä jokaista TVV-aluetta kohden - rajapinnan kautta on saatavilla koko järjestelmässä oleva suunnitteluaineisto ja sopimustiedot - rajapinta palauttaa vain voimassaolevat ja tulevat aikataulukaudet - rajapinta palauttaa vain niitä aikataulukausia, joille on suunnitteluaineistoa olemassa URL: GET http(s)://{ip-address}:{port}/tdm-service/rest/public/feeds Palauttaa listan järjestelmässä olevista feedeistä. Esimerkiksi: { } "feed":[ {"authority":"245"}, {"authority":"229"} ] URL: GET http(s)://{ip-address}:{port}/tdm-service/rest/public/feeds/{authority} Palauttaa organisaation feedin zipattuna.. Copyright @ 2014 TVV lippu- ja maksujärjestelmä Oy 13(13)