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: [email protected]

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 aineistopalvelusta 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=getCapabilities

 

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 on päivitetty uuteen CEN/TS 17268:2018 -standardiin, TN-ITS standardi. Digiroad-aineistossa tapahtuvat muutokset julkaistaan kerran vuorokaudessa TN-ITS-rajapinnassa. Muutostiedot välitetään loppukäyttäjille TN-ITS CEN TS 17268:2018 -standardin mukaisina dataset-XML-tiedostoina, jossa sijainti ilmoitetaan OpenLR -kirjastolla muodostettuna.

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

Muutostietoa jaetaan rajapintapalvelun lisäksi tiedostokoontina Väyläviraston aineistopalvelun kautta. 

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.

 

<RestDatasetRefList xmlns="http://www.ptvag.com/tnits/dataexchange/rest" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" xsi:schemaLocation="http://www.ptvag.com/tnits/dataexchange/rest https://avoinapi.vaylapilvi.fi/tnits/public/schemas/api/TN-ITS.xsd">
    <RestDatasetRef xlink:href="https://avoinapi.vaylapilvi.fi/tnits/public/download/readDataSet?dataSetID=%2BQBW3IlFSIWYYPDwF4Vc%2FQAAAYBOyKC7AAABgFPuEls%3D"/> <!-- Linkki yksittäiseen datasettiin (luotu 23.4.2022) -->
    <RestDatasetRef xlink:href="https://avoinapi.vaylapilvi.fi/tnits/public/download/readDataSet?dataSetID=%2BQBW3IlFSIWYYPDwF4Vc%2FQAAAYBT7hJbAAABgFkUbEQ%3D"/> <!-- Linkki yksittäiseen datasettiin (luotu 24.4.2022) -->
    <RestDatasetRef xlink:href="https://avoinapi.vaylapilvi.fi/tnits/public/download/readDataSet?dataSetID=%2BQBW3IlFSIWYYPDwF4Vc%2FQAAAYBZFGxEAAABgF46yZ4%3D"/> <!-- Linkki yksittäiseen datasettiin (luotu 25.4.2022) -->
</RestDatasetRefList>

 

 

HTTP error responses:

HTTP 400 (BadRequest), jos

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

Muut mahdolliset virheet


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

 

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>
            <!-- Datasetin id -->
            <!-- Muodostuu muutosten hakuajoista (alku ja loppu) sekä datasetin tarjoajan Väyläviraston uuid tunnuksesta -->
            <datasetId>+QBW3IlFSIWYYPDwF4Vc/QAAAYBOyKC7AAABgFPuEls=</datasetId>
            <!-- Datasetin luontiaika UTC-muodossa -->
            <datasetCreationTime>2022-04-23T00:59:12.859Z</datasetCreationTime>
        </Metadata>
    </metadata>
    <!-- Datasetin tyyppi "update" pitää sisällään päivitystietoa (vain tämä käytössä tällä hetkellä). Toinen mahdollinen arvo "snapshot" kuvaa datan tietyn hetkistä tilannetta vrt. irrotus -->
    <type>Update</type>
    <!-- Pitää sisällään yksittäisen muutoksen tiedot. Voi olla joko tyhjä <roadFeatures /> tai näitä voi olla useampi ( 0..* ) -->
    <!-- Tarkemmin yksittäisien tietolajien muutossanoman sisällöstä löytyy alasivuilta -->
    <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