Huom! Palvelun versio v1 suljetaan lokakuussa 2023 samalla kun palvelun käyttämä Kiinteistötietojen kyselypalvelu (WFS 2.0) suljetaan. Suosittelemme käyttämään palvelun v2 versiota.
Palvelu tarjoaa rajapinnan geokoodaukseen ja käänteiseen geokoodaukseen hyödyntäen Maanmittauslaitoksen eri avoimia aineistolähteitä kuten nimistöä, laskennallisia tiestön osoitteita, kiinteistöjaotuksen tietoja ja karttalehtiä. Lisäksi käytetään Väestötietojärjestelmän rakennusten osoitetietoja.
Rajapintapalvelun Open API 3.0 kuvaus:
Avoin rajapinta (vaatii API-avaimen):
https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/openapi.json
Sopimuskäyttö (vaatii käyttäjätunnukset):
https://sopimus-paikkatieto.maanmittauslaitos.fi/geocoding/openapi.json
Rajapintapalvelu perustuu osittain Pelias API spesifikaatioon joillakin muutoksilla (esimerkiksi koordinaatisto- ja kielituen parametrit lisätty). Palvelu palauttaa vastaukset GeoJSON-muodossa laajennuksin.
Palvelu tukee ETRS-TM35FIN (EPSG:3067) koordinaatistoa kaikissa palvelun hyödyntämissä aineistoissa.
Lisäksi palvelussa on osittainen tuki WGS84 maantieteellisille koordinaateille (EPSG:4326) joidenkin aineistolähteiden osalta (Huom! tällä hetkellä vain paikannimet).
Aineistot ja tuotteet
Geokoodauspalvelun rajapinnan toteutus hyödyntää seuraavia aineistolähteitä (linkkien käyttö vaatii API-avaimen):
|
Aineisto |
Esimerkkihaku |
Source id |
Source product information |
|---|---|---|---|
| Paikannimet | search | geographic-names | Nimistörekisteri |
| Rakennuksen osoitteet | search | addresses | Väestötietojärjestelmän rakennusten osoitteet |
| Laskennalliset tiestön osoitteet | search | interpolated-road-addresses | Maastotietokanta (laskennalliset tiestön osoitteet tuotettu maastotietokannan tiestöaineistosta) |
| Karttalehdet (TM35) | search | mapsheets-tm35 | JHS 197 kansallinen suositus |
| Rekisteriyksiköt | search | cadastral-units | Kiinteistörekisteri |
Geokoodauspalvelu hyödyntää näitä aineistolähteitä taustapalveluiden kautta käsitellessään suoran geokoodauksen tai käänteisen geokoodauksen palvelupyyntöjä. Aineistolähteet palauttavat paikannimiä, osoitteita tai muita paikkatietokohteita, joiden ominaisuudet ja tietomallit eroavat toisistaan. Geokoodauspalvelu hyödyntää soveltuvia aineistolähteiden kohteiden tietoja rajausparametreina ja vastaustietorakenteissa on tarjolla myös kohdetyyppikohtaisia tietoja.
Rajapinnan tarjoamat palvelupyyntöjen tyypit:
|
Operation |
Path |
Description |
|---|---|---|
| Suora geokoodaus | /geocoding/v1/pelias/search | Paikan haku etsimällä annettuun hakusanaan parhaiten sopivia paikannimiä, osoitteita tai muita paikkatietokohteita. |
| Käänteinen geokoodaus | /geocoding/v1/pelias/reverse | Paikannimen, osoitteen tai muun paikkatietokohteen haku annetun paikan (esim. sijaintipisteellä määriteltynä) läheisyydestä. |
| Hakusanojen tulkinta | /geocoding/v1/searchterm/decode | Hakusanan tunnistus vertailemalle hakusanaa luettelopalvelussa saatavilla oleviin koodilistojen koodien selitteisiin. Jos sopiva selite löytyy, palautetaan vastaava koodiarvo. |
| Samankaltaiset hakusanat | /geocoding/v1/searchterm/similar | Samankaltaisten termien haku vertaamalla hakusanaa paikannimiin ja palauttamalla parhaiten saatuun syötteeseen sopivat. |
Taustatietoa Pelias API-spesifikaation mukaisista rajapintapalveluista:
- suora geokoodaus (forward geocoding)
- käänteinen geokoodaus (reverse geocoding)
Rajapinnan ominaisuuksia, palvelupyyntöjä ja niissä käytettävissä olevia hakuparametreja on tarkemmin kuvattu Open API 3.0 kuvauksessa (linkki tämän sivun alussa).
Kyselyt ja esimerkit
Suora geokoodaus
Huom! Esimerkkilinkkien käyttö edellyttää API-avaimen käyttöä.
Paikan haku hakusanalla rajapinnasta on muotoa:
/geocoding/v1/pelias/search?text=...&sources=...&crs=...&lang=...
Vastaukset ovat GeoJSON FeatureCollection rakenteisia laajennuksilla varustettuna.
Alla muutama esimerkki paikan sijainnin hakemisesta käyttäen paikannimiä hakusanana:
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/search?text=tammerkoski&sources=geographic-names&crs=EPSG:3067&lang=fi
- Paikannimi "Tammerkoski"
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/search?text=pasila%20isojoki&sources=geographic-names&crs=EPSG:3067&lang=fi
- Isojoen kunnassa sijaitseva paikannimi "Pasila"
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/search?text=hossa%20suomussalmi%20kansallispuisto&sources=geographic-names&crs=EPSG:3067&lang=fi
- Paikannimi "Hossa", joka on kansallispuisto Suomussalmen kunnassa
Edelliset esimerkit palauttivat hakusanaan sopivien paikkatietokohteiden sijaintitiedot ETRS-TM35FIN koordinaatteina. Myös WGS 84 koordinaatteina voidaan pyytää joko jättämällä kokonaan crs parametri palvelupyynnöstä pois tai pyytämällä sitä erityisesti: crs=EPSG:4326.
Seuraavissa esimerkeissä hakusanaa sovitetaan muihin paikkatietokohteisiin kuin paikannimiin. Niiden osalta tuettuna on vain ETRS-TM35FIN koordinaatit. Nämä alla olevat esimerkit myös edellyttävät että aineistolähde on tarkasti määritelty käyttäen sources parametria.
Karttalehdet (TM35)
Laskennalliset tiestön osoitteet (tässä hakien "Mannerheimintie 3 Helsinki" tai "Mannerheimvägen 3 Helsingfors"):
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/search?text=Mannerheimintie%203%20Helsinki&sources=interpolated-road-addresses&crs=EPSG:3067&lang=fi
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/search?text=Mannerheimvägen%203%20Helsingfors&sources=interpolated-road-addresses&crs=EPSG:3067&lang=sv
Samat palvelupyynnöt, mutta haku kohdistuen rakennuksien osoitteisiin:
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/search?text=Mannerheimintie%203%20Helsinki&sources=addresses&crs=EPSG:3067&lang=fi
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/search?text=Mannerheimvägen%203%20Helsingfors&sources=addresses&crs=EPSG:3067&lang=sv
Hakusanat on suositeltavaa URL-enkoodata palvelupyynnöissä, esimerkiksi seuraava haku etsii Helsingistä osoitetta "Pohjoinen Makasiinikatu" käyttäen rakennusten osoitteita:
Yllä olevaan pyyntöön voidaan lisätä katunumero seuraavalla tavalla:
Käänteinen geokoodaus
Käänteistä geokoodausta mahdollistaa tietyn paikan tai sijaintipisteen läheltä lähimpien paikkatietokohteiden hakemisen.
Vastaukset ovat GeoJSON FeatureCollection rakenteisia laajennuksilla varustettuna.
Esimerkiksi seuraava kysely palauttaa lähimmät rakennuksen osoitteet ETRS-TM35FIN koordinaatistossa annetun sijaintipisteen läheltä (10 m säteellä):
Mikäli haluaa selvittää tarkan sijainnin perusteella palstan tiedot (esim. kiinteistötunnus) tulee käyttää boundary.circle.radius=0 parametria:
Hakusanojen tulkinta
Hakusanojen tulkintaa (eli luettelopalvelun koodiselitteiden tunnistus koodiarvoiksi) kutsutaan seuraavasti:
/geocoding/v1/pelias/searchterm/decode?text=...
Vastaukset ovat GeoJSON FeatureCollection rakenteisia laajennuksilla varustettuna.
Esimerkiksi hakusana "helsinki" osuu yhteen subregion and municipality koodilistoista löytyvien selitteiden kanssa:
https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/searchterm/decode?text=helsinki
Hakusana "museo" puolestaan osuu yhteen museoita luokittelevan paikkatyypin (placetype koodilistasta) kanssa:
https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/searchterm/decode?text=museo
Hakusana voi sisältää useita termejä eroteltuna URL-enkoodatulla välimerkillä. Seuraava esimerkki hakee "jyrä", "Heinola" ja "koski" termeihin osuvia koodilistojen koodeja:
Palvelu sovittaa hakusanoja ja termejä region, placetype, placetypegroup, placetypecategory ja municipality koodilistojen kanssa. Lisätietoa koodilistojen sisällöstä luettelopalvelun indeksisivulta.
Samankaltaiset hakusanat
Hakusana kanssa samankaltaisten paikannimien haku muotoa:
/geocoding/v1/pelias/searchterm/similar?size=...&text=...
Esimerkiksi alla oleva kysely palauttaa 10 parhaiten samankaltaista paikannimeä syötteelle "mäntyk":