Hyppää pääsisältöön

Tekninen kuvaus Osoitteet (OGC API Features) BETA

Uuden osoitetietojärjestelmän koekäyttöpalvelut sulkeutuvat ja palvelusta saatavien tietojen päivittäminen päättyy syyskuun 2021 aikana. Osoitteet (OGC API Features) BETA -palvelu sulkeutuu 30.9.2021. Kiitämme kaikkia beta-palvelun koekäyttöön osallistuneita ja palautetta antaneita!

Maanmittauslaitos jatkaa valtakunnallisen osoitetietojärjestelmän kehittämistä. Kehittämisen edistymisestä tiedotetaan https://www.maanmittauslaitos.fi/osoitetietojarjestelma -sivustolla.

 

Rajapintapalvelu perustuu OGC API Features standardiin ja rajapinnan tekninen kuvaus on julkaistu OpenAPI 3.0 spesifikaation mukaisena. Osoitetietoa voidaan hakea ID-tunnisteilla, ominaisuustiedoilla ja suorakaiderajauksella (bbox). Vastaukset palautetaan GeoJSON-tiedostomuodossa.

Oletuskoordinaatisto on OGC API Features -standardin ja GeoJSON-spesifikaation mukaisesti WGS 84 maantieteelliset koordinaatit. Palvelu tukee myös ETRS-TM35FIN, ETRS34..36 ja ETRS-GK19..31FIN projisoituja koordinaatistoja sekä ETRS89 maantieteellistä koordinaatistoa.

Osa kyselyparametreista ja osoitetiedon ominaisuustiedoista on mallinnettu koodiarvoina. Kuntien kuntanumerot ovat nähtävillä Digi- ja väestötietoviraston kuntaluettelossa.

Aineistolähteet ja käsitemalli

Kyselypalvelu perustuu Peruspaikkatietojen tuottajien koekäyttöympäristöön tallennettuihin osoitetietoihin, jotka koostuvat tällä hetkellä Tampereen, Jyväskylän ja Savonlinnan kaupunkien sekä ja Digi- ja väestötietoviraston aineistoista. 

Rajapinnan käyttö on sallittua vain testaus-, koekäyttö- ja koulutustarkoituksessa. Aineiston edelleen jakelu samoin kuin kaikenlainen julkaisu on kiellettyä. Aineiston tuotannollinen käyttö on kiellettyä. 

Osoitetieto on tarkistettu Laatuvahti-palvelulla, ja alkuperäisestä aineistosta on suodatettu pois laatusääntöjen vastaisia tietoja. Laatuvahdin laatusäännöt perustuvat Osoitteet-tietomalliin. Beta-vaiheessa aineiston sisältöön saattaa tulla muutoksia ilman erillistä ilmoitusta.

Osoitteet-tietomalli, jossa on kuvattu mm. osoitetiedon kohdeluokat, löytyy osoitteesta: https://tietomallit.suomi.fi/model/ostieto/

GeoJSON-skeemat

Tässä vaiheessa Osoitteet-tietomallin perusteella on mallinnettu Address GeoJSON-skeema, joka sisältää Osoitteet-tietomallin Osoitekohde- ja Osoitepiste-kohteiden tietoja. Jokainen Osoitepiste-kohde muodostaa yhden Address-kohteen. Jos yksi osoitekohde on linkittynyt moneen osoitepisteeseen (eli yhdessä osoitteessa on useita rakennuksia tai osoitteelle on annettu sijainti sekä alueen että rakennuksen mukaan), osoitekohteen tiedot toistuvat jokaisen osoitepisteen Address-kohteessa. Address-kohteen id-attribuutti on yhdistelmä osoitepisteen ja osoitekohteen tunnisteista. PId-attribuutti (persistent ID) on osoitepisteen tunniste.

Myöhemmässä vaiheessa mallinnetaan GeoJSON-skeemat, jotka sisältävät Osoitteet-tietomallin sisäänkäynti- ja kulkupistekohteiden tietoja.

Palvelun käyttämät GeoJSON-skeemat ovat ns. simple feature -tyyppisiä, eli tietorakenteissa ei ole sisäkkäisiä alikohteiden rakenteita. 

Palvelun tuottamien osoitetietojen ominaisuustiedon kyselyparametrit ovat tällä hetkellä: 

  • id-attribuutti on palvelukohtainen tunniste (string-tyyppiä)
  • yhteiset ominaisuudet
    • VTJprt (Pysyvä rakennustunnus)
    • sourceId (Tunnus lähdejärjestelmässä)
    • nameFI (Osoitenimi suomi)
    • nameSV (Osoitenimi ruotsi)
    • nameSE (Osoitenimi pohjoissaame)
    • number (Osoitenumero)
    • municipality (Kuntanumero)
    • validFrom (Osoitetiedon voimassaolon alkuhetki)
    • validUntil (Osoitetiedon voimassaolon päättymishetki)
    • targetType (Osoitteen osoittaman kohteen tyyppi)

Lisäksi osoitetiedosta riippuen, tiedolla voi olla myös muita ominaisuustietoja, kun aineiston määrä palvelussa kasvaa. Tässä vaiheessa palvelusta ei ole vielä saatavilla sisäänkäynti- ja kulkupistetietoa. Koska palvelun kehitys on aktiivisesti käynnissä, yllä oleva lista voi erota ajan tasalla pidettävässä Osoitetiedon OpenAPI-kuvauksessa nähtävistä ominaisuuksista.

Osoitetiedon ominaisuuksien tietosisällön tarkempi kuvaus löytyy Osoitteet-tietomallista.

Rajapinnan kyselypalvelutuotteet

Kyselypalvelutuotteiden (collection) tarkempi kuvaus ja tuetut koordinaatistot osoitetiedon osalta ovat nähtävillä osoitteesta:
https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections

Osoitetiedon OpenAPI-kuvaus löytyy osoitteesta:
https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/api

Skeemarakenne käy ilmi hakemalla esimerkkiaineistoa kyselyllä (tässä esimerkkiaineiston 50 ensimmäistä tulosta on haettu BBOX-lisärajauksella)
https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?bbox=25.69,60.4,25.7,60.5&limit=50

Yhteensopivuus ja tuotteet

Kehittäessä OGC API Features asiakassovelluksia kannattaa ensin tutustua OGC API Features standardiin.

Tämä OGC API Features BETA-palvelu on yhteensopiva standardin kanssa lukuun ottamatta seuraavia poikkeuksia ja laajennuksia:

•    laajennus (epävirallinen): laajennettu koordinaatistotuki bbox-suorakaiderajauksissa (bbox-crs parametri) ja vastauksien geometrioissa (crs parametri)

Tuetut yhteensopivuusluokat (conformance classes) ovat nähtävillä täältä: https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/conformance 

OpenAPI kuvaukset

OpenAPI 3.0 kuvauksessa on kerrottu tarkemmin, kuinka palvelusta voidaan hakea metatietoa ja osoitetietoa OGC API Features mukaisilla palvelupyynnöillä:
https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/api 

Osoitetiedon haku

Lyhyt ohje OGC API Features palveluiden eri hakutavoista (esim. paikkatietokohteen haku tunnisteella, vastausten sivutus, koordinaatistot ja suorakaiderajaukset, rajaus ominaisuustiedoilla) löytyy Nimistö (WFS 3.0) BETA palvelun dokumentaation kohdasta Kyselyt ja esimerkit. Ohjeessa kuvattuja hakutapoja voi soveltaa myös Osoitteiden (OGC API Features) BETA palveluun, kuitenkin siten että kohdeluokat skeemoineen ja hakuparametrit ovat tuotekohtaisia.

Alla muutama esimerkkihaku Osoitteiden (OGC API Features) beta-palveluun. Haut ovat merkkikoko riippuvaisia (case sensitive) eli hauissa tulee huomioida isot ja pienet kirjaimet.

Yhden (määrittelemättömän) osoitetiedon haku:
https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?limit=1

Osoitetiedon haku BBOX-rajauksella (ETRS-TM35FIN) siten että myös vastauksessa geometriat palautetaan ETRS-TM35FIN-koordinaatistossa: https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?bbox=327000,6822000,327300,6822300&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&crs=http://www.opengis.net/def/crs/EPSG/0/3067

Osoitetiedon haku (rajoituksena 100 kpl) tietyn kunnan alueelta (tässä esimerkissä Tampere):
https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?municipality=837&limit=100

Useamman kunnan osoitetiedot voidaan hakea yhdellä kyselyllä listaamalla kuntakoodit pilkulla erotettuna (jolloin arvojen käsittely toimii OR-operaation mukaisesti)
https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?municipality=418,837,980&limit=100

Osoitetietoa voidaan hakea myös eri kielisten osoitenimien perusteella. Tässä esimerkissä on haettu suomenkielisten osoitteiden joukosta Vähä-Koveron tie -nimistä osoitetietoa:
https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?nameFI=V%C3%A4h%C3%A4-Koveron%20tie

Erilaisia ominaisuustietoja voidaan yhdistellä ja käyttää rajaukseen. Tässä esimerkissä on haettu Tampereen kunnasta Itsenäisyydenkatu-nimistä osoitetta numerolla 18:
https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?municipality=837&nameFI=Itsen%C3%A4isyydenkatu&number=18

Kyselyparametrit nameFI, nameSE, nameSV ja number tukevat ns. villikortti-merkkejä (wildcard). Tällöin kysymysmerkki (?) on jokerimerkki mille tahansa yksittäiselle kirjaimelle, ja tähtimerkkillä (*) haetaan ne tiedot, jotka vastaavat merkkiä edeltävää merkkijonoa. Villikorttien käyttöä voidaan hyödyntää esimerkiksi tilanteessa, jossa halutaan etsiä rakennusta 4 A, mutta ei tiedetä tarkalleen onko tämä tietojärjestelmässä 4a, 4A, 4 a tai jotain muuta. Tässä esimerkissä haetaan kaikki ne Tampereen kunnan osoitetiedot, joiden nimi alkaa ”Pelto” sanalla:
https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?municipality=837&nameFI=Pelto*

Muuttuneita kohteita voidaan hakea datetime-parametrin avulla. Tämä parametri kohdistuu versionStartTime-attribuutin arvoihin. Parametrille voidaan antaa arvoksi aikaväli tai ajanhetki. Tässä esimerkissä haetaan kaikki vuoden 2020 lokakuun aikana syntyneet versiot:

https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?datetime=2020-10-01T00:00:00Z/2020-11-01T00:00:00Z

Perushaku palauttaa myös ne lakanneet kohteet, jotka on linkitetty voimassa olevaan osoitepisteeseen. Lakanneet osoitekohteet voidaan suodattaa pois seuraavan esimerkin mukaisesti

https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?validFrom=/2020-11-09&validUntil=2020-11-09/,null&limit=10

Yllä olevassa kyselyssä aikaväli on erotettu merkillä ”/” ja aikaväli on toiselta puolelta avoin. Lisäämällä null-parametri aikavälin tai ajankohdan perään, palvelu ottaa mukaan myös ne kohteet, joilla attribuutin arvo on null (eli pilkku toimii OR-operaationa).

Palvelun kautta on saatavilla myös aluemaisiin kohteisiin kohdistuvia osoitetietoja. Kysely voidaan kohdistaa aluemaisiin kohteisiin targetType-kentän avulla. TargetTypen koodiarvolistan mukaan arvo 1 kohdistuu rakennuksiin ja arvo 2 kohdistuu alueisiin. Esimerkiksi:

https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/items?targetType=2&limit=10

Hakuparametreina käytettävissä olevat ominaisuudet on lueteltu kattavammin rajapinnan OpenAPI-kuvauksessa sekä osoitteessa https://beta-paikkatieto.maanmittauslaitos.fi/address-kky/features/v1/collections/address/queryables