Rajapinnat

Digiroad-rajapinnat

Digiroad-aineistolla on WMS-katselurajapinta sekä WFS-latausrajapinta joita hyödyntämällä tiedonsiirto Digiroadin ylläpitäjiltä aineiston hyödyntäjille, niin kuntien työntekijöille, julkisille palveluntuottajille kuin yrityksillekin, on tehokasta.

Tieto päivittyy WMS- ja WFS- rajapintoihin joka viikonloppu Digiroadin tietokannasta. TN-ITS muutostietoa julkaistaan päivittäin.

Rajapintamme ovat kehitysvaiheessa, joten laitathan meille rohkeasti palautetta niin toiminnallisuuksista kuin mahdollisista aineiston virheistä Väyläviraston Palauteväylän kautta tai suoraan Digiroad-operaattorille osoitteeseen: info@digiroad.fi

Suomen liikennemerkkien symbolit ovat vapaasti ladattavissa QGIS-paikkatieto-ohjelmaan Väyläviraston kuvakirjastosta. Palvelu ja latausohjeet.

WMS-KATSELURAJAPINTA

Digiroadin WMS-katselurajapinnasta voit tarkastella Digiroadin eri tietolajeja ja käyttää niitä visualisointiin sovelluksissa tai kartoissa. Rajapinnassa on tällä hetkellä kaikki Digiroadin tietolajit ja lisäksi tielinkin ominaisuustieto suunnittelu- ja rakennusvaiheen geometriasta.
Otamme mielellämme palautetta niin WMS -rajapinnan visualisointitavoista kuin itse aineistostakin.

WMS-rajapintoja voi katsella esimerkiksi Paikkatietoikkunassa, Suomen Väylät -karttapalvelussa sekä Digiroad -karttaikkunassa. WMS-rajapinta (Web Map Service) on rajapinta, joka palauttaa paikkatietoaineiston karttakuvana. Aineistoa voi katsella, mutta sen ulkoasua ei voi muuttaa, eikä sille voi tehdä paikkatietokyselyitä. Digiroad-aineistojen WMS-palvelut sisältävät kuitenkin mahdollisuuden tehdä info-kyselyitä aineistoon paikkatieto-ohjelman info-työkalulla.

Digiroad avoin WMS (uusi) (metatiedot):

https://avoinapi.vaylapilvi.fi/vaylatiedot/digiroad/ows?service=wms&request=getCapabilities

WFS-LATAUSRAJAPINTA

Digiroadin WFS-suoratilausrajapinnasta saat ladattua haluamasi alueen aineiston käytettäväksi paikallisesti esimerkiksi paikkatieto-ohjelmilla. Tällä hetkellä suositeltu aluejako lataukseen on kuntataso. Koko Suomen Digiroad-aineisto on kooltaan hyvin suuri, joten suosittelemme lataamaan pieniä alueita kerrallaan rajapinnan suorituskyvyn optimoimiseksi. Rajapintaa ei myöskään ole suunniteltu käytettäväksi suoraan sovelluksissa ja suosittelemme aineiston lataamista paikallisesti.

Jos tarvitset käyttöösi dataa suuremmalta alueelta, Väyläviraston aineiston välityspalvelusta saa tuttuun tapaan ladattua koko aineiston viimeisimmän julkaisun. Aineiston voi ladata koko Suomen kattavana Geopackagena tai shape-tiedostona maakuntiin jaoteltuina.

WFS-rajapintaa suositellaan käytettäväksi kunta-aluejaolla ja WFS-rajapinnasta (Web Feature Service) ladattua aineistoa voi hyödyntää kuin mitä tahansa paikkatietotasoa.
Aineiston saa kyseltyä esimerkiksi QGIS-ohjelmistolla SQL-haulla:

SELECT * FROM HALUTTUTIETOLAJI WHERE HALUTTUTIETOLAJI.KUNTAKOODI=esim. 179

Täydennä HALUTTUTIETOLAJI tilalle tietolajin nimi rajapinnassa ja 179 (Kuntanumero) haluamasi kunta.

Huomioithan, että etenkin viivamaiset tietolajit ovat hyvin raskaita, ja suurten kuntien alueella yhteys voi olla hidas.

Digiroad avoin WFS (uusi) (metatiedot).

https://avoinapi.vaylapilvi.fi/vaylatiedot/digiroad/ows?service=wfs&request=getCapabilitiesTämä on ulkoinen linkki

Rajapintaan yhdistäminen QGIS-ohjelmistolla

1. Luo uusi WFS-yhteys

2. Anna yhteydelle haluamasi nimi

3. Kopioi WFS-URL -osoite kenttään. Saat tarvittavan osoitteen kopioimalla yllä olevan linkin.

4. Paina OK. Rajapinta ei tarvitse tunnistautumista.

5. Lisää uusi WFS-taso navigoimalla layer --> 6. Add layer --> 7. Add WFS-layer

8. Etsi pudotusvalikosta nimeämäsi yhteys ja paina Connect. Valitse ilmestyvältä listalta yksi haluamasi tietolaji.

9. Rajaa aineistosta yksittäinen kunta painamalla "Build query"

10. Kopioi kenttään kuntarajauskysely SQL-kielellä esimerkiksi: SELECT * FROM DR_VALAISTU_TIE WHERE DR_VALAISTU_TIE.KUNTAKOODI=95 .Tämä kysely palauttaa valaistutie -tietolajin Helsingin kaupungin alueelta. Huom! Vaiheessa 8. valitsemasi tietolajin tulee olla SQL-kyselyssä tietolajin paikalla, jotta kysely menee läpi. Jos haluat vaihtaa tietolajin, peruuta kysely painamalla cancel -painiketta ja valitse haluamasi tietolaji.

TN-ITS-MUUTOSRAJAPINTA

TN-ITS rajapinta perustuu CEN/TS 17268:2018 -standardiin. Digiroad-aineistossa tapahtuvat muutokset julkaistaan kerran vuorokaudessa TN-ITS-rajapinnassa. Muutostiedot välitetään loppukäyttäjille dataset-XML-tiedostoina, jossa Digiroad-kohteiden muutosten sijainti ilmoitetaan OpenLR -sijaintiviitteellä.

TN-ITS-rajapinnan etuna on tiedonkäsittelyn nopeus ja helppous, kun koko aineiston latauksen sijaan päästään kiinni suoraan muuttuneisiin kohteisiin.

Tarjolla olevat TN-ITS-rajapinnat

Palauttaa TN-ITS:n tämän hetkiset tiedot:
https://avoinapi.vaylapilvi.fi/tnits/public/download/queryDataSets

Rajapinnan esittely

/download/queryDataSets

Palauttaa listauksen olemassa olevista dataseteistä kronologisessa järjestyksessä vanhimmasta uusimpaan.

Datasetit ovat yksittäisiä muutossanomia, johon on listattu kaikki datasetin määrittämällä aikavälillä tapahtuneet muutokset Digiroadin tietolajeissa (tarkempi listaus rajapinnan tarjoamista tietolajeista löytyy alapuolella olevanpääotsikon"TN-ITS: GET /download/readDataSet - Yksittäisen datasetin tiedot", alta).

Autentikointi

Rajapinnan käyttö ei vaadi autentikointia.

Parametrit

lastValidDataSetID (optional): Viimeisimpänä haetun datasetin url enkoodattu id. Mikäli määritetty, listaa haku kaikki määritetyn datasetin jälkeen luodut datasetit. Muuten palauttaa listauksen kaikista olemassa olevista dataseteistä.

Paluuarvot

HTTP-200 (OK):
XML-muotoinen vanhimmasta uusimpaan aikajärjestetty listaus tarjolla olevista dataseteistä. Yksittäinen dataset määritetään "RestDatasetRef"-elementillä, jonka "xlink:href"-attribuutti määrittää url:in datasetin sijaintiin.

HTTP error responses:

HTTP 400 (BadRequest), jos

Pyynnön käsittelyssä tapahtuu sisäinen virhe.

Muut mahdolliset virheet

TN-ITS rajapinta on toteutettu AWS API Gatewaytä hyödyntäen. Mahdollisia API Gateway peräisiä virheviestejä on listattu AWS:n sivuilla (https://docs.aws.amazon.com/apigateway/latest/api/CommonErrors.html).

Content-type:

application/xml

Versiot:

2022-03 Initial

Esimerkit:

Esimerkki 1. (Kutsu prod-ympäristöön): Listaa kaikki olemassa olevat datasetit.

curl https://avoinapi.vaylapilvi.fi/tnits/public/download/queryDataSets

Esimerkki paluuarvon sisällöstä ja rakenteesta: queryDataSets-example1.xml

Esimerkki 2. (Kutsu prod-ympäristöön): Listaa ainoastaan datasetin (id: %2BQBW3IlFSIWYYPDwF4Vc%2FQAAAYBT7hJbAAABgFkUbEQ%3D) jälkeen luodut datasetit.

curl https://avoinapi.vaylapilvi.fi/tnits/public/download/queryDataSets?lastValidDataSetID=%2BQBW3IlFSIWYYPDwF4Vc%2FQAAAYBT7hJbAAABgFkUbEQ%3D

Esimerkki paluuarvon sisällöstä ja rakenteesta: queryDataSets-example2.xml

Palauttaa yksittäisen datasetin tiedot:
https://avoinapi.vaylapilvi.fi/tnits/public/download/readDataSet

Rajapinnan esittely:

/download/readDataSets

Palauttaa kysellyn datasetin sisällön. Dataset sisältää tietyllä aikavälillä Digiroadissa tapahtuneet tietolajien lisäykset, muokkaukset sekä poistot. Muutossanoman sisältö on toteutettu TN-ITS CEN TS 17268-standardin mukaan.

Datasettejä muodostetaan automaattisesti kerran päivässä.

HUOM! Rajapinta käyttää redirectejä, jonka vuoksi redirectit täytyy olla kyselyssä käytössä. (Ks. kappale Paluuarvot; HTTP-302)

Toteutus pitää sisällään seuraavien tietolajien muutostietoja:

Nopeusrajoitukset
Suurin sallittu -tietolajit:
- Ajoneuvon tai ajoneuvoyhdistelmän suurin sallittu pituus
- Ajoneuvon suurin sallittu leveys
- Ajoneuvon suurin sallittu korkeus
- Ajoneuvon suurin sallittu akselimassa
- Ajoneuvon suurin sallittu massa
- Ajoneuvoyhdistelmän suurin sallittu massa
Pakollinen pysähtyminen
Esterakennelmat
Suojatie
Ajoneuvokohtainen rajoitus
Varoitusmerkit

Digiroad-kohteiden muutosten sijainti ilmoitetaan OpenLR -sijaintiviitteellä. Muuttuneen Digiroad-kohteen vaikutussuunta kerrotaan seuraavasti:

Yhteen suuntaan vaikuttavan viivamaisen Digiroad-kohteen muutoksesta muodostetaan saman suuntainen OpenLR-sijaintiviite.
Molempiin suuntiin vaikuttavan viivamaisen Digiroad-kohteen muutoksesta muodostetaan kaksi erillistä roadFeatures-elementtiä, joilla molemmilla on yksisuuntainen OpenLR-sijaintiviite. Molemmat roadFeatures-elementit viittaavat samaan Digiroad-kohteeseen.
Pistemäisten pakollisen pysähtymisen ja varoitusmerkkien vaikutussuunnasta muodostetaan Orientation-tieto OpenLR-sijaintiviitteeseen.
Datasetissä on OpenLR-sijaintiviitteen lisäksi geometrian sijaintiviite gml-merkkijonona, mutta siinä ei huomioida mitenkään kohteen vaikutussuuntaa.

OpenLR -sijaintiviite: https://www.openlr.org/

OpenLR -sijaintiviitteen voi purkaa demo.tomtom.com -verkkosivulla.

Autentikointi:

Rajapinnan käyttö ei vaadi autentikointia.

Parametrit

dataSetID: Kyseltävän datasetin url enkoodattu id, jonka sisältö halutaan hakea. Saatavilla olevien muutossanomien url enkoodatut id:t saa haettua datasettien listaus kutsun avulla (Yläpuolella olevan pääotsikon: TN-ITS: GET /download/queryDataSets - Tämän hetkiset tiedot, alta), joka palauttaa täydelliset url:t datasettien lukemiseen xml listauksena.

Paluuarvot

HTTP-302 (Found): Uudelleen ohjaa location-headerin avulla kyselijän tiedoston sijaintiin. Dataset on XML-muotoinen järjestämätön listaus muutoksista, jotka ovat tapahtuneet datasetissä määritellyllä aikavälillä.

<RoadFeatureDataset xmlns="http://spec.tn-its.eu/schemas/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:gml="http://www.opengis.net/gml/3.2" xmlns:xlink="http://www.w3.org/1999/xlink" xsi:schemaLocation="http://spec.tn-its.eu/schemas/ http://spec.tn-its.eu/schemas/TNITS.xsd">
<metadata>
<Metadata>


<datasetId>+QBW3IlFSIWYYPDwF4Vc/QAAAYBOyKC7AAABgFPuEls=</datasetId>

<datasetCreationTime>2022-04-23T00:59:12.859Z</datasetCreationTime>
</Metadata>
</metadata>

<type>Update</type>


<roadFeatures />
</RoadFeatureDataset>

HTTP error responses:

HTTP 400 (BadRequest), jos

dataSetID parametri puuttuu tai se on virheellinen

Muut mahdolliset virheet

TN-ITS rajapinta on toteutettu AWS API Gatewaytä hyödyntäen. Mahdollisia API Gateway peräisiä virheviestejä on listattu AWS:n sivuilla (https://docs.aws.amazon.com/apigateway/latest/developerguide/supported-gateway-response-types.html).

Content-type:

application/xml

Versiot:

2022-03 Initial

Esimerkki:

Esimerkki: (Kutsu prod-ympäristöön): Hakee datasetin (id: "+QBW3IlFSIWYYPDwF4Vc/QAAAYBOyKC7AAABgFPuEls=" url enkoodattuna: "%2BQBW3IlFSIWYYPDwF4Vc%2FQAAAYBOyKC7AAABgFPuEls%3D") sisällön.

curl -L https://avoinapi.vaylapilvi.fi/tnits/public/download/readDataSet?dataSetID=%2BQBW3IlFSIWYYPDwF4Vc%2FQAAAYBOyKC7AAABgFPuEls%3D

Esimerkki paluuarvon sisällöstä ja rakenteesta:
%2BQBW3IlFSIWYYPDwF4Vc%2FQAAAYBOyKC7AAABgFPuEls%3D.xml

Rajapinnat

WMS-KATSELURAJAPINTA

WMS -katselurajapinnan käyttöönotto

WFS-LATAUSRAJAPINTA

WFS -latausrajapinnan käyttöönotto

TN-ITS-MUUTOSRAJAPINTA

Tarjolla olevat TN-ITS-rajapinnat

TN-ITS:GET /download/queryDataSets - Tämän hetkisen tiedot

TN-ITS:GET /download/readDataSet -Yksittäisen datasetin tiedot