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

Tekninen kuvaus - Nimistö (OGC API Features)

Palvelu tarjoaa OGC API Features -kyselyrajapinnan Maanmittauslaitoksen nimistörekisterin paikoille, paikannimille ja karttanimille.

Rajapintapalvelu tarjotaan maksuttomana ja 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/

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

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

TuoteKuvausTiedot
PaikatTuotteen tietoyksikkö on nimetty paikka. Paikan tietoja ovat mm. sijainti ja paikanlaji sekä paikan kaikki nimetXML-skeemaUML-kaavio / Luokat ja attribuutit
PaikannimetTuotteen 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, yksinkertaistettuTuote vastaa Paikannimet-tuotetta ilman rinnakkaisnimiä.XML-skeema / UML-kaavio / Luokat ja attribuutit
KarttanimetTuotteen 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:

TuoteEsimerkkikohteitaFeatureCollection tunniste (OGC API Features)FeatureType
PaikatGeoJSONGMLplacesPlace
PaikannimetGeoJSONGMLplacenamesPlaceName
Paikannimet, yksinkertaistettuGeoJSONGMLplacenames_simplePlaceNameSimple
KarttanimetGeoJSONGMLmapnamesMapName

Koodistot on julkaistu luettelopalvelussa ja niitä käytetään sekä hakuparameteissa että vastausten paikkatietokohteiden ominaisuuksissa. Koodistojen arvolistat ovat suomeksi, ruotsiksi ja englanniksi.

Nimi suomeksiNimi englanniksiKoodilistat
PaikanlajiPlaceTypefin, swe, eng
PaikanlajikuvausPlaceTypeDescriptionfin, swe, eng
PaikanlajiteemaPlaceTypeCategoryfin, swe, eng
PaikanlajiryhmaPlaceTypeGroupfin, swe, eng
PaikanlajialaryhmaPlaceTypeSubgroupfin, swe, eng
KuntaMunicipalityfinsweeng
SeutukuntaSubRegionfinsweeng
MaakuntaRegionfinsweeng
MittakaavarelevanssiScaleRelevancefinsweeng
KieliLanguagefinsweeng
KielenVirallisuusLanguageOfficialityfinsweeng
KielenValtaasemaLanguageDominancefinsweeng
PaikannimenLahdePlaceNameSourcefinsweeng
PaikannimenStatusPlaceNameStatusfinsweeng
KarttatuoteMapProductfinsweeng
MittakaavaluokkaScaleClassfinsweeng
TekstinAakkoslajiTextCasefinsweeng
TekstinKirjasintyyppiTextFontfinsweeng
TekstinVariTextColourfinsweeng
TekstinHarvennusTextSpacingfinsweeng
TekstinEnsisijaisuusTextPreferencefinsweeng
TuoteTapahtumaLajiProductEventTypefin, swe, eng

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: 

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items/PN_40889621 

Sama kysely, vastaus GML 3.2.1-muotoisena:

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items/PN_40889621.gml 

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:

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?limit=100 

Vastauksena tulee siis nuo 100 kohdetta sekä myös linkki seuraaviin 100 kohteeseen, esim.:

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?next=MDo0MDAwMDEwMQ%3D%3D&limit=100

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:

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?bbox=22.15,63.45,22.2,63.5

Rajaaminen ETRS-TM35FIN koordinaateilla (EPSG:3067) onnistuu lisäämällä bbox-crs parametri (joka ei ole osa OGC API Features standardin core-osioita):

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?bbox=490000,6904000,492000,6906000&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067

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):

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?bbox=490000,6904000,492000,6906000&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&crs=http://www.opengis.net/def/crs/EPSG/0/3067

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

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?municipality=837&limit=100

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"):

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?municipality=418,837,980&limit=100

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":

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?municipality=837&spelling_case_insensitive=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"):

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?municipality=837&spelling_case_insensitive=tammer*&placeType=2020115

Lisää hakuesimerkkejä eri käyttötapauksiin sovitettuna alempana kohdassa Esimerkkejä.

Tuotannollinen julkaisu 2023-12-18 - koordinaattijärjestelmien yhdenmukaistaminen ja koordinaattijärjestykset EPSG-standardin mukaisiksi 

Tuotannollinen julkaisu 2020-02

BETA-julkaisu 2019-03

Kyselyesimerkkejä, tuote Paikat

Paikka, jonka paikka-id on 10342733 (Helsinki, Helsingfors, kunta).

GeoJSON: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/places/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeId=10342733

GML: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/places/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeId=10342733

Paikka, jonka nimi on Ivalon lentoasema.

GeoJSON: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/places/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&name.spelling_case_insensitive=ivalon%20lentoasema

GML: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/places/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&name.spelling_case_insensitive=ivalon%20lentoasema

Kaikki kunnat. Hakutulosten lukumäärä on kuntien lukumäärä.

GeoJSON: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/places/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeType=4010125

GML: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/places/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeType=4010125

Lapin maakunnan kaupunkialueet ja taajamat sekä niiden osat.

GeoJSON: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/places/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeType=3010105,3020105&region=19

GML: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/places/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeType=3010105,3020105&region=19

Vesistökohteet, joiden nimi esiintyy MML:n 1:1 milj. ja sitä pienempimittakaavaisissa kartoissa.

GeoJSON: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/places/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeTypeCategory=2&scaleRelevance=1000000,2000000,4500000,8000000

GML: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/places/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeTypeCategory=2&scaleRelevance=1000000,2000000,4500000,8000000

 

 

Kyselyesimerkkejä, tuote Paikannimet

Paikannimi, jonka paikannimi-id on 40342733 (”Helsinki”, kunta)

GeoJSON https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeNameId=40342733

GML https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeNameId=40342733

Kaikki kunnannimet. Hakutulosten lukumäärä on kunnannimien lukumäärää eri kielillä.

GeoJSON: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeType=4010125

GML: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeType=4010125

Kunnannimet, joiden kieli on kunnan enemmistökieli. Hakutulosten lukumäärä on kuntien lukumäärä.

GeoJSON: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeType=4010125&languageDominance=1

GML: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeType=4010125&languageDominance=1

 

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)

GeoJSON: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames_simple/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeNameId=40342734 

GML: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames_simple/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&placeNameId=40342734  

 

Kyselyesimerkkejä, tuote Karttanimet

Yleiskartan 1:4,5 milj. karttanimet, koko Suomi.

GeoJSON: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/mapnames/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&mapProduct=K4500  

GML: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/mapnames/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&mapProduct=K4500 

Peruskartan 1:25 000 karttanimet TM35-karttalehden M5214G alueella.

Haku palauttaa karttanimet, joiden karttatekstin vasen alakulma osuu hakuikkunaan.

GeoJSON: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/mapnames/items?crs=http://www.opengis.net/def/crs/EPSG/0/3067&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&bbox=542000,6822000,548000,6828000&mapProduct=K0025 

GML: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/mapnames/items.gml?crs=http://www.opengis.net/def/crs/EPSG/0/3067&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&bbox=542000,6822000,548000,6828000&mapProduct=K0025