Ohjeet Ryhti-järjestelmän avoimien rajapintojen käyttöön
Rajapintojen kautta saat käyttöösi rakennetun ympäristön tietojärjestelmän sisältämiä avoimia paikkatietoja. Tälle sivulle on koottu yleisiä ohjeita rajapintojen hyödyntämiseen.
Jotta voit käyttää rajapintapalveluita, käytössäsi tulee olla paikkatieto-ohjelmisto tai muu ohjelmisto, joka tekee pyynnöt rajapintaan.
Rajapintojen kautta saat aina viimeisimmät tiedot, eikä sinun tarvitse ladata tietoja omaan ympäristöösi.
Rajapintaosoitteet
Rajapintaosoitteet saat Ryhti-sivuston tiedon hyödyntäjille tarkoitetulta alasivulta.
Osoitteet on myös listattu INSPIRE-jaottelun mukaisesti Syken paikkatietorajapinnat-sivulla.
Käyttölupa ja vastuut
Avointen rajapintojen käyttö on maksutonta.
Käyttö ei vaadi API-avainta, mutta mikäli aiot käyttää rajapintoja pidempikestoisesti kehittämässäsi tai ylläpitämässäsi sovelluksessa tai muussa kuormitusta aiheuttavassa ratkaisussa, edellytämme sovelluskohtaisen yksilöivän tunnisteen käyttöä.
Tutustu myös rajapintojen käyttöehtoihin ennen kuin otat palvelut käyttöön.
Tietojen päivittyminen
Rajapintojen tarjoamat tiedot päivittyvät kerran päivässä.
Rajapintojen tyypit – WMS vai OGC?
Rajapintoja on kahta erilaista tyyppiä. Valitse käyttötarkoitukseesi sopiva rajapintatyyppi.
Usein eri rajapintojen yhdistäminen on toimiva ratkaisu: kartalla näkyvä aineisto haetaan WMS-palvelusta, mutta tarvittaessa tehdään tarkentavat kyselyt OGC-rajapintaan. Esimerkkinä tästä on esimerkiksi valitun kohteen korostaminen kartalla, jolloin vain valittu kohde on haettu OGC-rajapinnasta.
WMS
WMS-palvelut ovat paras vaihtoehto karttavisualisointiin, sillä ne tarjoavat paremman suorituskyvyn sekä käyttäjän sovelluksen että karttapalvelimen kannalta.
Karttavisualisoinnin lisäksi WMS-rajapinta mahdollistaa kohteiden ominaisuustietojen kyselyn tietyssä pisteessä GetFeatureInfo-kutsuilla.
Sen sijaan monimutkaisempien kyselyjen tekeminen ei ole mahdollista (esim. aluerajauksen tai ominaisuustietojen perusteella). Kyselyt eivät myöskään palauta kohteen geometriaa eli sijaintitietoa. Lisätietoa WMS-rajapinnan käytöstä löydät esim. GeoServerin dokumentaatiosta
OGC API Features
Standardinmukainen OGC Api Feature -rajapintapalvelu, joka palauttaa vektorimuotoista dataa.
Valitse OGC-rajapinta silloin kuin pelkkä tietojen kuvallinen esittäminen ja yksinkertaiset ominaisuustietokyselyt eivät riitä. Tämä vaihtoehto sopii tilanteisiin, joissa haluat esimerkiksi hakea tietyllä alueella olevat kohteet, hakea kohteet, joilla on tietty ominaisuustieto tai saada vastauksena kohteiden geometrian (koordinaatit).
Vektorirajapinnoissa on aina rajoitteet palautettavien kohteiden maksimimäärälle. Tämä tarkoittaa, että niitä käytettäessä on huolehdittava kutsujen jakamisesta osiin (pagination).
OGC API Features on modernimpi toteutus, joka vastaa pitkälti aikaisempia WFS-palveluita (OGC Web Feature Service).
Metatietokuvaukset
Metatietokuvauksista näet tarkempia tietoa Syken aineistoista ja palveluista. Avoimille rajapinnoille on omat kuvauksensa.
Metatietokuvaukset
Häiriötiedotus
Käyttökatkot rajapinnoissa pyritään minimoimaan. Mahdollisista käyttökatkoista ilmoitetaan Ryhti-sivuston häiriötiedotteilla.
Usein kysytyt kysymykset
Miten pääsen alkuun OGC API Features -rajapintojen kanssa?
Voit tutkia rajapinnan tietoja menemällä selaimella sen osoitteeseen.
Esim. https://paikkatiedot.ymparisto.fi/geoserver/ryhti_permit/ogc/features/v1
Tulet ensimmäiseksi laskeutumissivulle. Alasivuilta löydät seuraavaa tietoa.
- API definition: palvelun rajapintakuvaus
- Collections: kuvaus palvelun kokoelmista eli aineistokokonaisuuksista
- Conformance: yhteensopivuusluettelo
- Contact information: yhteystiedot
Millä ohjelmistolla voin testata rajapintoja?
Voit testata rajapintoja käyttämälläsi paikkatietoohjelmistolla.
Jos käytössäsi ei ole paikkatieto-ohjelmistoa, suosittelemme testaamiseen maksutonta, avoimeen lähdekoodiin perustuvaa QGIS-ohjelmistoa.
OGC API Features -rajapintoja voit testata myös selaimella kirjoittamalla rajapinnan osoitteen selaimen osoiteriville ja rajaamalla hakua parametreilla.
Miksi aineistoja ei ole saatavissa CSV-muodossa?
Aineistot saa haettua suoraan rajapintojen kautta. Aineistot päivittyvät päivittäin, joten rajapintoja käyttämällä voi varmistua siitä, että käytössä on aina ajantasainen aineisto.
Sain haettua rajapinnasta vain 3000 rakennuskohdetta. Miten saan haettua loputkin?
Kohteiden haulle on asetettu 3000 kohteen raja liiallisen kuormituksen välttämiseksi. Kytkemällä kutsut toisiinsa saat haettua useampia kohteita.
Esimerkiksi paikkatieto-ohjelmisto QGIS osaa hakea kohteet osissa. Jos kutsut rajapintaa muuten, saat haettua kohteet käyttämällä sivutusta (pagination). Sivutus on OGC API Features -standardissa saatavilla sisäänrakennettuna.
Jos et saa haettua enempää kuin 3000 kohdetta, kokeile lisätä kutsusi perään parametri &limit=3000. Tämä lisää vastaukseen linkin seuraavan sivun hakemiseen.
Esimerkkikutsu:
https://paikkatiedot.ymparisto.fi/geoserver/ryhti_building/ogc/features/v1/collections/open_address/items?&limit=3000
Haluan hakea rajapinnasta vain tietyn kunnan rakennuskohteet. Onnistuuko se?
Voit toteuttaa rajauksen paikkatieto-ohjelmasi puolella tai kokeilla sitä suoraan OGC API Features -rajapinnan osoitteeseen lisättävillä parametreilla. Tee rajaus hyödyntämällä esimerkiksi kuntatunnusta tai aluerajauksella (bounding box, bbox).
Esimerkki: rajaus Vaasan rakennuksiin
/items?filter=municipality_number=905&limit=3000(siirryt toiseen palveluun)
Esimerkki: aluerajaus
Rajaus aluerajauksella eli bounding boxilla siten, että haettava alue on rajattu Suomen virallisen koordinaatiston (ETRS TM35FIN eli EPSG:3067) mukaisesti.