Tekninen kuvaus - Nimistö (OGC API Features)
Palvelu tarjoaa OGC API Features -kyselyrajapinnan Maanmittauslaitoksen nimistörekisterin paikoille, paikannimille ja karttanimille.
Rajapintapalvelu tarjotaan maksuttomana avoimena rajapintana sekä maksullisena sopimusrajapintana.
Avoin rajapinta tarjotaan Maanmittauslaitoksen avoimen rajapintapalvelun käyttöehtojen mukaisesti. Rajapinnan käyttö vaatii API-avaimen liittämistä pyyntöihin. Ohjeet tähän löydät sivulta Ohje API-avaimen käyttöön. Rajapintapalvelu on saatavilla osoitteesta: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/
Sopimusrajapinta vaatii käyttäjätunnukset. Jos teet sopimuksen avoimien paikkatietojen kyselypalvelusta, saat samalla sopimuksella mahdollisuuden käyttää muitakin avoimien paikkatietojen kyselypalveluita. Jos olet kiinnostunut palvelusta, ota yhteyttä verkkopalveluiden asiakastukeen osoitteeseen: verkkopalvelut@maanmittauslaitos.fi.
Sopimusrajapintapalvelu on saatavilla osoitteesta: https://sopimus-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/.
- GeoJSON (ensijainen tiedostomuoto OGC API Features palveluissa, soveltuu hyvin simple feature kohteiden esittämiseen, mutta myös complex feature kohteiden esittäminen mahdollista)
- GML (taaksepäin yhteensopivuussyistä tuettu tiedostomuoto, tässä palvelussa GML 3.2.1)
Oletuskoordinaatisto on OGC API Features -standardin ja GeoJSON-spesifikaation mukaisesti WGS84 lon-lat (tunniste CRS84) maantieteellinen koordinaatisto. Palvelu tukee myös ETRS-TM35FIN, ETRS-TM34..36 ja ETRS-GK19..31FIN projisoituja koordinaatistoja, WGS84-koordinaatistoa EPSG:4326 tunnisteella, ETRS89 (2D) maantieteellistä koordinaatistoa sekä Web Mercator -koordinaatistoa.
Osa kyselyparametreista ja paikkatietokohteiden ominaisuustiedoista on mallinnettu koodistoarvoina, joiden selitystekstit on julkaistu erillisen luettelopalvelun kautta.
Aineistot ja tuotteet
Aineisto
Nimistön tietopalveluiden aineistolähde, Maanmittauslaitoksen nimistörekisteri on nimettyjen paikkojen ja tarkistettujen paikannimien sekä erimittakaavaisten karttanimistöjen valtakunnallinen tietovaranto. Nimistörekisterin suomen- ja ruotsinkieliset paikannimet tarkistetaan Kotimaisten kielten keskuksessa ja saamenkieliset Oulun yliopistossa. Nimettyjä paikkoja ja paikannimiä on noin 800 000. Karttanimistöjä ylläpidetään yhdeksässä mittakaavassa ja ne vastaavat Karttapaikan karttarastereita. Paikkojen sijaintitietona on lähellä sen keskipistettä ja joen tapauksessa sen suuta oleva piste. Paikat on luokiteltu hierarkkisesti yhdeksän paikanlajiteeman mukaan. Paikannimen kieli voi olla suomi, ruotsi, pohjoissaame, inarinsaame tai koltansaame. Kaikilla paikoilla ja paikannimillä on pysyvät yksilöivät tunnukset.
Tarkistettu nimistöaineisto ja siihen perustuvat tuotteet palvelevat esimerkiksi täsmällistä viestintää ja luotettavan nimitiedon tarvetta yleensä sekä paikkatietoinfrastruktuuria ja sen palveluiden kehittämistä.
Nimistön (OGC API Features) aineisto päivittyy jatkuvasti.
Lisätietoa nimistörekisterin paikoista, paikannimistä ja karttanimistä sekä niiden aineistolähteistä löytyy tuotekuvauksesta ja Paikkatietohakemistossa julkaistuissa metatiedoissa.
Tuotteet
Nimistön kyselypalvelutuotteita on neljä. Tuotteet Paikat, Paikannimet ja Paikannimet, yksinkertaistettu sisältävät nimettyjen paikkojen ja paikannimien tietoja. Tuote Karttanimet sisältää Maanmittauslaitoksen yhdeksän vakiokarttatuotteen karttanimistöt peruskartasta 1:25 000 Yleiskarttaan 1: 8 milj.
Jokaisesta tuotteesta on kuvattu vastaussanoman rakenne ja sisältö UML-kaaviona sekä attribuutit mahdollisine koodistoineen. Koodistoissa selitetään attribuuttien arvoina käytetyt koodit suomeksi, ruotsiksi ja englanniksi. Erilaisia käyttötapauksia valaisevia kyselyesimerkkejä löytyy tältä sivulta alempana kohdassa Esimerkkejä.
| Tuote | Kuvaus | Tiedot |
|---|---|---|
| Paikat | Tuotteen tietoyksikkö on nimetty paikka. Paikan tietoja ovat mm. sijainti ja paikanlaji sekä paikan kaikki nimet | XML-skeema / UML-kaavio / Luokat ja attribuutit |
| Paikannimet | Tuotteen tietoyksikkö on paikannimi. Paikannimen tietoja ovat mm. tarkistettu kirjoitusasu ja kieli, mahdolliset rinnakkaisnimet sekä kyseisen nimetyn paikan tiedot (mm. sijainti ja paikanlaji). | XML-skeema / UML-kaavio / Luokat ja attribuutit |
| Paikannimet, yksinkertaistettu | Tuote vastaa Paikannimet-tuotetta ilman rinnakkaisnimiä. | XML-skeema / UML-kaavio / Luokat ja attribuutit |
| Karttanimet | Tuotteen tietoyksikkö on karttanimi. Karttanimen tietoja ovat mm. karttanimiteksti ja sen sijoittelu- ja typografiatiedot sekä tärkeimmät kyseisen paikannimen ja nimetyn paikan tiedot. Tuotteen tietojen avulla on mahdollista tuottaa MML:n karttatuotteita vastaava karttanimistö. | XML-skeema / UML-kaavio / Luokat ja attribuutit |
Rajapinnan kyselypalvelutuotteet
Tämän OGC API Features-rajapintapalvelun tarjoamat kyselypalvelutuotteet:
| Tuote | Esimerkkikohteita | FeatureCollection tunniste (OGC API Features) | FeatureType |
|---|---|---|---|
| Paikat | GeoJSON, GML | places | Place |
| Paikannimet | GeoJSON, GML | placenames | PlaceName |
| Paikannimet, yksinkertaistettu | GeoJSON, GML | placenames_simple | PlaceNameSimple |
| Karttanimet | GeoJSON, GML | mapnames | MapName |
Koodistot on julkaistu luettelopalvelussa ja niitä käytetään sekä hakuparameteissa että vastausten paikkatietokohteiden ominaisuuksissa. Koodistojen arvolistat ovat suomeksi, ruotsiksi ja englanniksi.
| Nimi suomeksi | Nimi englanniksi | Koodilistat |
| Paikanlaji | PlaceType | fin, swe, eng |
| Paikanlajikuvaus | PlaceTypeDescription | fin, swe, eng |
| Paikanlajiteema | PlaceTypeCategory | fin, swe, eng |
| Paikanlajiryhma | PlaceTypeGroup | fin, swe, eng |
| Paikanlajialaryhma | PlaceTypeSubgroup | fin, swe, eng |
| Kunta | Municipality | fin, swe, eng |
| Seutukunta | SubRegion | fin, swe, eng |
| Maakunta | Region | fin, swe, eng |
| Mittakaavarelevanssi | ScaleRelevance | fin, swe, eng |
| Kieli | Language | fin, swe, eng |
| KielenVirallisuus | LanguageOfficiality | fin, swe, eng |
| KielenValtaasema | LanguageDominance | fin, swe, eng |
| PaikannimenLahde | PlaceNameSource | fin, swe, eng |
| PaikannimenStatus | PlaceNameStatus | fin, swe, eng |
| Karttatuote | MapProduct | fin, swe, eng |
| Mittakaavaluokka | ScaleClass | fin, swe, eng |
| TekstinAakkoslaji | TextCase | fin, swe, eng |
| TekstinKirjasintyyppi | TextFont | fin, swe, eng |
| TekstinVari | TextColour | fin, swe, eng |
| TekstinHarvennus | TextSpacing | fin, swe, eng |
| TekstinEnsisijaisuus | TextPreference | fin, swe, eng |
| TuoteTapahtumaLaji | ProductEventType | fin, swe, eng |
Kyselyt ja esimerkit
Yhteensopivuus ja tuotteet
Kehitettäessä OGC API Features asiakassovelluksia kannattaa ensin tutustua OGC API - Features - Part 1: Core -standardiin (http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)
Tämä OGC API Features -palvelu on yhteensopiva standardin kanssa ja tukee seuraavaa standardilaajennusta:
- laajennus: laajennettu koordinaatistotuki bbox-suorakaiderajauksissa (bbox-crs -parametri) ja vastauksien geometrioissa (crs-parametri)
Tuetut yhteensopivuusluokat (conformance classes):
https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/conformance
Palvelun tarjoamat tuotteet (collections) ja tuetut koordinaatistot:
https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections
Open API kuvaukset
Open API 3.0.1 kuvauksessa on kerrottu tarkemmin kuinka palvelusta voidaan hakea metatietoa ja nimistörekisterin mukaisia paikkatietokohteita OGC API Features mukaisilla palvelupyynnöillä:
https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/api
Luettelopalvelun Codelist API tarjoaa myös indeksisivun jossa on lueteltu palvelun käyttämät koodilistat. Lisätietoa koodilistojen ja koodien selitteiden hakemisesta Open API 3.0.1 kuvauksesta:
https://beta-paikkatieto.maanmittauslaitos.fi/catalogue/openapi.json
https://beta-paikkatieto.maanmittauslaitos.fi/catalogue/openapi.yaml
OGC API Features palvelun käyttäminen
Tässä on lyhyt ohje kuinka käyttää OGC API Features rajapintapalvelua, esimerkkitapauksena tuote Paikannimet. Luonnollisesti vastaavat kyselyt mahdollisia myös muille palvelun tuotteille. Open API kuvauksessa on kuvattu tarkemmin eri tuotteille mahdolliset palvelupyynnöt ja niiden hakuparametrit.
Paikkatietokohteen haku tunnisteella
Oletuksena vastaus on GeoJSON-muotoista:
Sama kysely, vastaus GML 3.2.1-muotoisena:
Vastausten sivutus
OGC API Features rajapinnan mukaisesti toteutettuna palvelussa on hyvä tuki paikkatietokohteiden kokoelmien sivutukselle. Esimerkiksi seuraava kysely palauttaa osajoukon paikannimien kokoelmasta eli ensimmäiset 100 kohdetta:
Vastauksena tulee siis nuo 100 kohdetta sekä myös linkki seuraaviin 100 kohteeseen, esim.:
Tämä puolestaan palauttaa linkin sitä seuraavaan osajoukkoon jne.
Koordinaatistot ja suorakaiderajaukset
Oletuksena BBOX-suorakaiderajaus ja vastauksena palautettavien paikkatietokohteiden geometriat sisältävät WGS 84 koordinaatteja (CRS84), esimerkiksi:
Rajaaminen ETRS-TM35FIN koordinaateilla (EPSG:3067) onnistuu lisäämällä bbox-crs parametri (joka ei ole osa OGC API Features standardin core-osioita):
Edellinen esimerkki palauttaa vastauksen paikkatietokohteiden geometriat edelleen WGS 84 koordinaatteina. Jos myös vastaus halutaan projisoida toiseen koordinaatistoon, niin tähän voi käyttää crs parametria (myöskään ei osa OGC API Features standardin core-osioita):
Tuettujen koordinaatistojen tunnisteet on lueteltu:
https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections
Rajaus ominaisuustiedoilla
Tämä esimerkki hakee municipality-parametria käyttäen yhden kunnan (837 = Tampere) kaikki paikannimet 100 kohteen osajoukoissa, ensimmäinen erä:
Useamman kunnan paikannimet voidaan hakea yhdellä kyselyllä listaamalla kuntakoodit pilkulla erotettuna (jolloin arvojen käsittely toimii OR-operaation mukaisesti, tässä esimerkissä siis "418 tai 837 tai 980"):
Eri parametrien välinen käsittely tapahtuu AND-operaattorin mukaisesti. Alla oleva kysely rajaa sekä kuntakoodilla (municipality-parametri) että paikannimen kirjoitusasulla (spelling_case_insensitive-parametri, tässä wildcard-hakuna), ja palauttaa kaikki paikannimet Tampereelta, joiden aakkoslajeja erottamaton kirjoitusasu alkaa sanalla "tammer":
Edellinen kysely palauttaa 5 paikannimikohdetta sisältäen mm. "Tammerkoski" ja "Tammerfors". Kun kyselyyn lisätään vielä paikanlajirajaus käyttäen placeType-parametria (tässä esimerkissä koodiarvo 2020115, joka tarkoittaa paikanlajia "Koski"), niin vastaus palauttaa täsmälleen yhden kohteen ("Tammerkoski"):
Lisää hakuesimerkkejä eri käyttötapauksiin sovitettuna alempana kohdassa Esimerkkejä.
Versiohallinta
Tuotannollinen julkaisu 2023-12-18 - koordinaattijärjestelmien yhdenmukaistaminen ja koordinaattijärjestykset EPSG-standardin mukaisiksi
Tuotannollinen julkaisu 2020-02
BETA-julkaisu 2019-03
Esimerkkejä
Kyselyesimerkkejä, tuote Paikat
Paikka, jonka paikka-id on 10342733 (Helsinki, Helsingfors, kunta).
Paikka, jonka nimi on Ivalon lentoasema.
Kaikki kunnat. Hakutulosten lukumäärä on kuntien lukumäärä.
Lapin maakunnan kaupunkialueet ja taajamat sekä niiden osat.
Vesistökohteet, joiden nimi esiintyy MML:n 1:1 milj. ja sitä pienempimittakaavaisissa kartoissa.
Kyselyesimerkkejä, tuote Paikannimet
Paikannimi, jonka paikannimi-id on 40342733 (”Helsinki”, kunta)
Kaikki kunnannimet. Hakutulosten lukumäärä on kunnannimien lukumäärää eri kielillä.
Kunnannimet, joiden kieli on kunnan enemmistökieli. Hakutulosten lukumäärä on kuntien lukumäärä.
Hirviaiheiset saarien tai luotojen sekä saari- ja luotoryhmien nimet.
GeoJSON: rajapintakutsu (sisältää ? ja * merkkejä)
GML: rajapintakutsu (sisältää ? ja * merkkejä)
Korkeintaan kolmikirjaimiset ruotsinkieliset luonnonpaikkojen nimet.
GeoJSON: rajapintakutsu (sisältää ? ja * merkkejä)
GML: rajapintakutsu (sisältää ? ja * merkkejä)
Vähintään 30-kirjaimiset suomenkieliset luonnonpaikkojen nimet.
GeoJSON: rajapintakutsu (sisältää ? ja * merkkejä)
GML: rajapintakutsu (sisältää ? ja * merkkejä)
Kyselyesimerkki, tuote Paikannimet, yksinkertaistettu
Paikannimi, jonka paikannimi-id on 40342734 (”Helsingfors”, kunta)
Kyselyesimerkkejä, tuote Karttanimet
Yleiskartan 1:4,5 milj. karttanimet, koko Suomi.
Peruskartan 1:25 000 karttanimet TM35-karttalehden M5214G alueella.
Haku palauttaa karttanimet, joiden karttatekstin vasen alakulma osuu hakuikkunaan.