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

Tekninen kuvaus Geokoodauspalvelu (REST) v1

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

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:

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

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:

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

Samat palvelupyynnöt, mutta haku kohdistuen rakennuksien osoitteisiin:

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

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/reverse?&lang=fi&sources=addresses&boundary.circle.radius=10&request-crs=EPSG:3067&crs=EPSG:3067&point.lon=385000&point.lat=6675000 

Mikäli haluaa selvittää tarkan sijainnin perusteella palstan tiedot (esim. kiinteistötunnus) tulee käyttää boundary.circle.radius=0 parametria:

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/reverse?&lang=fi&sources=cadastral-units&boundary.circle.radius=0&request-crs=EPSG:3067&crs=EPSG:3067&point.lon=386069.217&point.lat=6678102.476

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:

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/searchterm/decode?text=jyr%C3%A4%20Heinola%20koski

Palvelu sovittaa hakusanoja ja termejä regionplacetypeplacetypegroupplacetypecategory 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":

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/searchterm/similar?size=10&text=m%C3%A4ntyk