Digiroad-rajapinnat

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

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

 

 

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