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
Geokoodauspalvelusta on tarjolla rinnan versiot v2 ja v1.
Geokoodauspalvelun versio v2 kannattaa ottaa käyttöön jo nyt. Palvelun versio v1 suljetaan lokakuussa 2023 version käyttämien taustapalvelujen alasajon myötä.
Geokoodauspalvelun OpenAPI kuvauksessa kuvataan molemmat rajapintaversiot v1,v2 sekä molemmat palvelukanavat avoin ja sopimus.
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)ja WGS84 (EPSG:4326) koordinaatistoja kaikissa palvelun hyödyntämissä aineistoissa.
Palvelu on pääasiassa tarkoitettu tukemaan käyttöliittymäsovellusten paikan hakua.
Massa-aineiston lataamiseen voi olla tarkoituksenmukaista käyttää samoja rajapintapalveluita, joiden varaan myös koko geokoodauspalvelun toiminta perustuu.
Tilanteissa, joissa tarvitaan suuri osa aineistosta voi olla järkevää ladata aineisto Karttapaikan Lataa paikkatietoaineistoja -osiosta jatkojalostamista varten.
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 | |
| Rakennuksen osoitteet | search | addresses | Väestötietojärjestelmän rakennusten osoitteet Rakennustietojen kyselypalvelu (WFS) |
| 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 Kiinteistötietojen kyselypalvelu (OGC API Features) |
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/v2/pelias/search | Paikan haku etsimällä annettuun hakusanaan parhaiten sopivia paikannimiä, osoitteita tai muita paikkatietokohteita. |
| Käänteinen geokoodaus | /geocoding/v2/pelias/reverse | Paikannimen, osoitteen tai muun paikkatietokohteen haku annetun paikan (esim. sijaintipisteellä määriteltynä) läheisyydestä. |
| Hakusanojen tulkinta | /geocoding/v2/searchterm/decode | Hakusanan tunnistus vertailemalle hakusanaa luettelopalvelussa saatavilla oleviin koodilistojen koodien selitteisiin. Jos sopiva selite löytyy, palautetaan vastaava koodiarvo. |
| Samankaltaiset hakusanat | /geocoding/v2/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/v2/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/v2/pelias/search?text=tammerkoski&sources=geographic-names&crs=EPSG:3067&lang=fi
- Paikannimi "Tammerkoski"
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/search?text=pasila%20isojoki&sources=geographic-names&crs=EPSG:3067&lang=fi
- Isojoen kunnassa sijaitseva paikannimi "Pasila"
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/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. Nämä alla olevat esimerkit myös edellyttävät että aineistolähde on tarkasti määritelty käyttäen sources parametria.
Karttalehdet (TM35)
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/search?text=N512&sources=mapsheets-tm35&crs=EPSG:3067&lang=fi
- tuettuna vain ETRS-TM35FIN karttalehtiaineiston käyttötarkoituksen vuoksi
Laskennalliset tiestön osoitteet (tässä hakien "Mannerheimintie 3 Helsinki" tai "Mannerheimvägen 3 Helsingfors"):
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/search?text=Mannerheimintie%203%20Helsinki&sources=interpolated-road-addresses&crs=EPSG:3067&lang=fi
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/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/v2/pelias/search?text=Mannerheimintie%203%20Helsinki&sources=addresses&crs=EPSG:3067&lang=fi
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/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:
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/search?text=%22Pohjoinen%20Makasiinikatu%22%207%20Helsinki&sources=interpolated-road-addresses&crs=EPSG:3067&lang=fi
- "Pohjoinen Makasiinikatu" 7 Helsinki
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/search?text=Pohjoinen%20Makasiinikatu%207%20Helsinki&sources=interpolated-road-addresses&crs=EPSG:3067&lang=fi
- Pohjoinen Makasiinikatu 7 Helsinki
- tämä muoto ilman lainausmerkkejä toimii palvelun versiossa v2
Osoitteiden hakuehdon tulkintaan on tehty parannuksia mm. moniosaisten katunimien käsittelyyn, esim. seuraavat hakuehdot toimivat versiossa v2
- IV Linja
- IV Linja 1
- IV Linja Forssa
- IV Linja 1 Forssa
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/search?text=IV%20Linja%201%20Forssa&sources=interpolated-road-addresses&crs=EPSG:3067&lang=fi
Osoitehakuehtoon otettavat osat hakuehdosta
- osoitehakuun otetaan katunimi ja numero
- postitoimipaikkatieto toimii vain, jos on samalla myös kunnan nimi
- postinumero hakuehtona on tuettu vain addresses tietolähteessä (eli rakennusten osoitteiden haussa)
- postinumeron voi valita huomioitavaksi optiolla use_postal_code, jolloin postinumero ottaa postinumeron mukaan addresses tietolähteen parametriksi (ks. ohjetta lisäoptioiden käytöstä alempaa)
- postinumeroa ei käytetä hakuparametrina interpolated-road-addresses (laskennallisten osoitteiden) tietolähteessä, jossa tietoa ei käsitellä
Kiinteistöt
- Esim. hakuehto 91-17-16-1
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/search?text=91-17-16-1&sources=cadastral-units
- kiinteistöt haetaan aina yksittäisen kiinteistön kiinteistötunnuksella. Hyväksyttävät hakuehdon muodot ovat tunnus väliviivoin 91-17-16-1 sekä ns. tietokantamuoto 09101700160001 - tai epävirallinen 091-017-0016-0001
- vastaukset ovat kiinteistötunnuksien sijainteja kiinteistön palstoilla ja vastauksia voi siten olla 0-n kappaletta
- laajempaan kiinteistöjen aineistojen hankintaan ominaisuus- ja sijaintirajauksilla voi käyttää Kiinteistötietojen kyselypalvelu OGC API Features palvelua, jota myös geokoodauspalvelun v2 versio käyttää
Hakuehdot, jotka palauttavat satoja tai tuhansia kohteita
- Halutun vastauksen saamiseksi kannattaa rajata hakua esim. kunnan nimellä tai paikkatyypillä
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/search?text=m%C3%A4nnikk%C3%B6&sources=geographic-names&sort=placetypegroup&size=1000
- Esim. hakuehto männikkö salla
- options lisävalinta options=nowildcard,use_any_codelist_lang_match vähentää myös palautettavien kohteiden lukumäärää, jos haetaan vain täsmälleen tietyn nimistö kohdetta
- kuntarajaus karsii hyvin kohteita, joita on paljon, esim. hakuehtona männikkö rautavaara
Hakuehdon ja kohteiden rajaaminen kunnalla
- hakuehtoon voi syöttää lisämääreenä kunnan nimen, esim.
- soukka espoo
- sökö esbo
- vastaava haku painottaen lajiteltuna lajittelee alkuun taajaman osan sökö
Kohteiden rajaaminen paikkatyyppien ja muiden koodilistojen avulla
- Paikannimirekisterin hakuehtoon voi syöttää lisämääreenä kunnan nimen, paikkatyypin ja muita rajauksia, esim:
- autiotupa kohteet Lapin maakunnasta
- autiotupa kohteet Sodankylän kunnasta
- kansallispuistot varsinais-suomesta
- kansallispuistot varsinais-suomesta EPSG:4326
Vastausrakenteen tietoja
-
"distance" elementissa on epäyhtenäiset yksiköt eri koordinaatistoissa
-
EPSG:4326 yksikkö on kilometri (km),
-
EPSG:3067 yksikkö on metriä (m)
-
-
vastausten etäisyydet ovat viitteellisiä - etäisyydet lasketaan nimien ja muiden kohteiden pistemäisten sijaintien perusteella, joiden asettelu on aineistokohtaista
Vastausrakenteen kielistys
- lang -parametri vaikuttaa vastausrakenteeseen tulostuviin koodiarvojen selitteisiin, jotka erottuvat 'label:' alkuliittestä
- lang -parametrin oletusarvo on fi eli suomen kieli
- lang -parametrin vaihtoehdot ovat suomi ja ruotsi eli fi, sv tai fin ja swe
- eri saamenkieliset nimet lisätään aina vastauksen label elementtiin
- Vastauksiin listataan koodiarvojen lisäksi niitä vastaavat selitteet label: alkuliitteellä erotettuna
- esimerkki
- lang=fi tai lang=fin
- "municipality" : "049",
- "placeType" : 8030115, ...
- "label:municipality" : "Espoo",
- "label:placeType" : "Uimaranta tai uimapaikka",...
- lang=sv tai lang=swe
- "municipality" : "049",
- "placeType" : 8030115,...
- "label:municipality" : "Esbo",
- "label:placeType" : "Simstrand eller simplats", ...
- lang=fi tai lang=fin
Vastausten lajittelu
- nimistön kohteiden oletuslajittelu on vastauksen otsikon 'label' mukaan
- nimistön kohteiden lajittelua voi painottaa paikanimen tyypin perusteella parametrilla sort=placetypegroup
- vastaukset lajitellaan painotetusti paikkatyyppikoodin mukaan
- painotuksessa lajitellaan alkuun mm. kuntakeskukset, liikennepaikat, luonnonsuojelualueet, taajamat
Vastausrakenteen metatietoelementti
- vastauksen "geocoding" elementtiin on koottu metatietoa hakutermin tulkinnasta ja vastauksen muodostamisesta, joista hyödyllisiä voivat olla seuraavat
- geocoding / metadata
- tietoja hakuehdon tulkinnasta sekä koodilistoista, joihin hakutermi osuu
- geocoding / sources
- tietolähdekohtaisesti tilatietoa
- "status" tilatietona success, failure sen mukaan onnistuiko taustapalveluhaku
Palvelupyynnön options -parametrin tarjoamat lisävalinnat
- geokoodauspalvelun versioon v2 lisättiin options -parametri, jolla voi muokata haun suoritusta
- options -parametrilla hakuehdon tulkintaan voi antaa muutamia arvoja, joilla voi parantaa vastauksen osuvuutta.
- options -parametrin optiot lisätään parametriin pilkulla erottaen
- options -parametrin oletusarvo, jos sitä ei ole annettu
- oletusarvo on options=use_geographic_names_places,use_any_codelist_lang_match
- oletuksena siis haetaan paikkoja eli places sekä tulkitaan hakuehtoa koodiston selitteisiin nähden riippumatta kielistyksestä
- palvelu myös lisää vanhastaan aina * wildardin hakuehtoon
- kun options parametri lisätään kyselyyn mitkään oletusarvot eivät ole voimassa, vaan kaikki käyttöön otettavat optiot tulkitaan parametrin arvosta
- nowildcard
- tämä optio ei ole oletusarvona valittu, joten oletuksena, ilman tätä optiota, palvelu lisää * wildcardin hakuehdon loppuun, mikä ei aina ole toivottavaa ja voi tuoda vastauksia, jotka eivät vastaa asiakkaan toivetta.
- wildcardin lisäyksen voi estää ottamalla käyttöön options=nowildcard yhdistellen muutamaan lisäoptioon
- optio kannattaa useimmiten käyttää yhdessä use_any_codelist_lang_match option kanssa, jotta koodistojen tulkinta on mahdollisimman laajaa kieliasusta riippumatta
- esim. options=nowildcard,use_any_codelist_lang_match
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/search?text=s%C3%B6k%C3%B6,esbo&sources=geographic-names&sort=placetypegroup&options=nowildcard,use_any_codelist_lang_match
- use_any_codelist_lang_match
- tämä optio on oletusarvona valittu, jos options -parametria ei ole annettu lainkaan
- kun tämä on valittu hakuehdon tekstin perusteella etsitään koodiarvoja kaikista eri kielisistä koodistojen selitteistä, jotta voidaan parametroida taustapalveluhakuja,
- esim. kuntien nimet tai paikkatyypit (esim. autiotupa) löytyvät riippumatta annetun lang- kieliparametrin arvosta
- jos use_any_codelist_lang_match -optiota ei ole asetettu, etsitään koodilistojen arvoja lang -parametrilla annetun kielen mukaisista selitteistä
- use_addresses_firsthousenumber
- tämä optio palauttaa osoitehausta vain ensimmäisen kohteen, jos katunumeroa ei ole annettu hakuehdossa
- use_geographic_names_places
- tämä optio on oletusarvona valittu, jos options -parametria ei ole annettu lainkaan
- tällä optiolla nimistörekisteristä haetaan paikka -kohteita eli places
- tämä optio vaikuttaa, jos geographic-names on valittu sources parametrilla
- vain joko use_geographic_names_places tai use_geographic_names_placenames kerrallaan käytössä
- tämä optio on käytössä esim. paikkatietoikkunan hakutoiminnossa
- use_geographic_names_placenames
- tällä optiolla haetaan nimistörekisterin paikannimi -kohteita eli placenames
- tämä optio vaikuttaa vain, jos geographic-names on valittu sources parametrilla
- vain joko use_geographic_names_places tai use_geographic_names_placenames kerrallaan käytössä
- tämä voi toimia joissain sovelluksissa paremmin
- tämä optio on käytössä esim. karttapaikan hakutoiminnossa
- use_postal_code
- tämä ei ole tuettu muissa kuin addresses tietolähteessä eli rakennusten osoitteilla
- jos optio on valittu mukaan, asetetaan osoitehakuun (addresses) parametriksi hakuehdosta tulkittu postinumero
Palvelupyynnön sources ja options lisävalintojen esimerkkejä
- suositeltava uusiin integraatioihin, todennäköisimmin vastaa asiakastarvetta
- options=nowildcard,use_any_codelist_lang_match
- tämä options -yhdistelmä voi palauttaa käyttäjän näkökulmasta parempia vastauksia kuin palvelun v1 ja v2 versioiden oletusvalinnat
- tässä tapauksessa käyttäjän tai asiakassovelluksen tulee lisätä * tai ? wildcard hakuehtoon, jos niin halutaan
- esim. optiot, joilla saa vastaavat hakutulokset kuin paikkatietoikkunan paikkahaussa
-
options=nowildcard,use_addresses_firsthousenumber,
use_any_codelist_lang_match,use_geographic_names_places -
sources=geographic-names,cadastral-units,interpolated-road-addresses
- paikkatietoikkunassa on oma vastausten lajittelutoteutus
-
- esim. optiot, joilla saa vastaavat hakutulokset kuin karttapaikan haussa
-
options=nowildcard,use_addresses_firsthousenumber,use_any_codelist_lang_match,use_geographic_names_placenames
-
sources=geographic-names,cadastral-units,interpolated-road-addresses
- karttapaikassa on oma vastausten lajittelutoteutus
-
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 kiinteistötunnuksen
- https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/reverse?&lang=fi&sources=cadastral-units&request-crs=EPSG:3067&crs=EPSG:3067&point.lon=386069.217&point.lat=6678102.476
- geokoodauspalvelu ei käytä boundary.circle.radius parametria lainkaan eikä siis puskuroi hakurajausta vaan hakurajauksena on aina piste
- geokoodauspalvelu on tarkoitettu yksittäisten kiinteistöjen hakuun tunnuksella ja pistemäisellä sijainnilla
- laajempaan kiinteistöjen aineistojen hankintaan ominaisuus- ja sijaintirajauksilla voi käyttää Kiinteistötietojen kyselypalvelu OGC API Features palvelua, jota myös geokoodauspalvelun v2 versio käyttää
- haku saattaa palauttaa usean kiinteistön tietoja, jos annettu sijainti osuu kiinteistöjaotukseen
Hakusanojen tulkinta
Hakusanojen tulkintaa (eli luettelopalvelun koodiselitteiden tunnistus koodiarvoiksi) kutsutaan seuraavasti:
/geocoding/v2/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/v2/searchterm/decode?text=helsinki
Hakusana "museo" puolestaan osuu yhteen museoita luokittelevan paikkatyypin (placetype koodilistasta) kanssa:
https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/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/v2/pelias/searchterm/similar?size=...&text=...
Esimerkiksi alla oleva kysely palauttaa 10 parhaiten samankaltaista paikannimeä syötteelle "mäntyk":