Tekninen kuvaus Geokoodauspalvelu (REST) v2

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

Geokoodauspalvelun OpenAPI kuvauksessa kuvataan 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. Oletuksena vastaukset ja pyynnöt käyttävät GeoJSONissa yleisesti käytettyä koordinaatistoa CRS84 (WGS84 Longitude, Latitude) .

Palvelu tukee ETRS-TM35FIN (EPSG:3067) ja CRS84 (WGS84 Longitude, Latitude) 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.

Laskutettavien hakujen muodostuminen ja ylläpitomaksun kertyminen

Geokoodauspalvelun laskutus perustuu laskutettavien hakujen lukumäärään. 

Asiakassovelluksen toteutus vaikuttaa laskutettavien hakujen muodostumiseen. Esimerkiksi, käynnistääkö jokainen kirjoitettu kirjain haun, vai käynnistyykö haku vasta enter/hae-painikkeella.

Seuraavassa esimerkissä paikannimihaku käynnistyy jokaisen kirjaimen jälkeen.  

  • K -> Ei hakua, koska liian lyhyt hakuehto, ei käytönseurannan tapahtumia 
  • Ku-> Ei hakua, koska liian lyhyt hakuehto, ei käytönseurannan tapahtumia  
  • Kum-> (Vastauksia x kpl) -> yksi laskutettava haku kirjautuu käytönseurantalokiin 
  • Kumm -> (vastauksia x kpl) -> yksi haku 
  • Kumma -> (vastauksia x kpl) -> yksi haku  
  • Kummak -> (vastauksia x kpl) -> yksi haku  
  • Kummaki -> (vastauksia x kpl) -> yksi haku  
  • Kummakiv ->  (vastauksia x kpl) -> yksi haku  
  • Kummakivi -> (vastauksia 1 kpl) -> yksi haku

Käyttäjältä kirjautuu tästä kyselystä yhteensä 7 laskutettavaa hakua tuotetunnukselle 2202 (paikannimet).  

  • Jos haku menee useampaan taustapalveluun, muodostuu laskutettavia hakuja jokaiselle tuotetunnukselle. (Esim. paikannimet ja osoitteet) 
  • Jos haku ei tuota yhtään vastausta, ei myöskään muodostu laskutettavaa hakua.  

Käytönseuranta summaa päivän aikana tehdyt laskutettavat haut ja jakaa päiväkohtaisen hakumäärän vielä luvulla 20.  Näin varmistetaan, että asiakassovelluksen toteutustavasta riippumatta laskutettavia hakuja ei muodostu kohtuuttomia määriä.  

Tutustu avoimien paikkatietojen kyselypalvelun hinnastoon ja hinnastossa oleviin esimerkkeihin erilaisilla hakumäärillä.  

Geokoodauspalvelun rajapinnan toteutus hyödyntää seuraavia aineistolähteitä (linkkien käyttö vaatii API-avaimen):

AineistoEsimerkkihakuSource idSource product information
Paikannimetsearchgeographic-namesNimistörekisteri 
Nimistön kyselypalvelu (OGC API Features)
Rakennuksen osoitteetsearchaddressesVäestötietojärjestelmän rakennusten osoitteet
Rakennustietojen kyselypalvelu (WFS)
Laskennalliset tiestön osoitteetsearchinterpolated-road-addressesMaastotietokanta (laskennalliset tiestön osoitteet tuotettu maastotietokannan tiestöaineistosta)
Karttalehdet (TM35)searchmapsheets-tm35JHS 197 kansallinen suositus
Rekisteriyksikötsearchcadastral-unitsKiinteistö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:

OperationPathDescription
Suora geokoodaus/geocoding/v2/pelias/searchPaikan haku etsimällä annettuun hakusanaan parhaiten sopivia paikannimiä, osoitteita tai muita paikkatietokohteita.
Käänteinen geokoodaus/geocoding/v2/pelias/reversePaikannimen, osoitteen tai muun paikkatietokohteen haku annetun paikan (esim. sijaintipisteellä määriteltynä) läheisyydestä.
   
Samankaltaiset hakusanat/geocoding/v2/searchterm/similarSamankaltaisten termien haku vertaamalla hakusanaa paikannimiin ja palauttamalla parhaiten saatuun syötteeseen sopivat. 
Hakusanojen tulkinta/geocoding/v2/searchterm/decodeHakusanan tunnistus vertailemalle hakusanaa luettelopalvelussa saatavilla oleviin koodilistojen koodien selitteisiin. Jos sopiva selite löytyy, palautetaan vastaava koodiarvo.

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

Edelliset esimerkit palauttivat hakusanaan sopivien paikkatietokohteiden sijaintitiedot ETRS-TM35FIN koordinaatteina. Myös WGS84 koordinaatteja voidaan pyytää jättämällä kokonaan crs parametri palvelupyynnöstä pois.

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)

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:

Osoitteiden hakuehdon tulkintaan on tehty parannuksia mm. moniosaisten katunimien käsittelyyn, esim. seuraavat hakuehdot toimivat versiossa v2

Osoitehakuehtoon otettavat osat hakuehdosta

Kiinteistöt

Hakuehdot, jotka palauttavat satoja tai tuhansia kohteita

Hakuehdon ja kohteiden rajaaminen kunnalla

Kohteiden rajaaminen paikkatyyppien ja muiden koodilistojen avulla

Koordinaatistomuunnokset

  • crs ja request-crs parametrilla voi vaihtaa pyyntöjen ja vastausten koordinaattijärjestelmän
  • oletuksena on käytössä CRS84 järjestelmä, joka on WGS84 longitude, latitude koordinaattijärjestyksessä
    • http://www.opengis.net/def/crs/OGC/1.3/CRS84
  • palvelu tukee myös kansallista koodinaattijärjestelmää, jonka saa käyttöön crs parametrilla
    • crs=EPSG:3067
    • tai 
    • crs=http://www.opengis.net/def/crs/EPSG/0/3067

Vastausrakenteen tietoja

  • "distance" elementissa on epäyhtenäiset yksiköt eri koordinaatistoissa
    • oletuskoordinaatiston 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 vastausrakenteen label -kentän kieliasuun
  • lang -parametri vaikuttaa vastausrakenteeseen tulostuviin koodiarvojen selitteisiin, jotka erottuvat 'label:' alkuliitteestä
  • 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", ...

 

Vastausten lukumäärän rajaaminen

  • size -parametrilla voi valita kuinka monta kohdetta palautetaan 

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

Geokoodauspalvelun aineistojen geometriat ovat pistemäisiä, joten boundary.circle.radius parametrin arvoa kannattaa kasvattaa, jotta kohteita löytyy laajemmin tarjolle, esim: &boundary.circle.radius=200

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/v2/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 kiinteistötunnuksen

 

Vastausten lajittelu 

  • vastaukset lajitellaan lähimmästä etäisimpään hakupisteeseen (tai painopisteeseen) nähden

 

Mikäli haluaa selvittää tarkan sijainnin perusteella hallinnolliset yksiköt, voit käyttää parametria sources=administrative-units

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/pelias/reverse?&lang=fi&sources=administrative-units&request-crs=EPSG:3067&crs=EPSG:3067&point.lon=386069.217&point.lat=6678102.476

  • administrative-units hallinnolliset yksiköt on aina valinnainen tietolähde, joka pitää ottaa käyttöön sources -parametrilla
  • administrative-units on tarkoitettu yksittäisten hallinnollisten yksiköiden hakuun pistemäisellä sijainnilla
  • geokoodauspalvelu ei käytä tässä hallinnollisten alueiden hakuun boundary.circle.radius parametria lainkaan eikä siis puskuroi hakurajausta vaan hakurajauksena on aina piste
  • haku palauttaa usean hallinnollisen yksiköiden tietoja: kunta, maakunta, hyvinvointialue, aluehallintovirasto
  • käänteisessä geokoodauksessa sijainti on kaikille vastauksille parametrina annettu sijainti, jonka perusteella hallinnollinen yksikkö on saatu vastaukseksi
    • (käytetyssä inspire aineistossa ei ole tarjolla soveliasta tunnuspistesijaintia geokoodauspalvelun käyttöön)
  • jos samalla haluaa hakea muista tietolähteistä, pitää ne lisätä sources parametriin, esim. sources=administrative-units,addresses,cadastral-units
  • vastauksen skeema sisältää geokoodauspalvelun tietojen ohella inspire-palvelun tietoja mm. nationalCode, nationalLevel,inspireId_localid,inspireId_namespace sekä eri kieliasut tiedoille
  • laajempaan hallinnollisten aineistojen hankintaan ominaisuus- ja sijaintirajauksilla voi käyttää INSPIRE kyselypalveluja, jota myös geokoodauspalvelu käyttää taustapalvelunaan 

Samankaltaiset hakusanat

Hakusana kanssa samankaltaisten paikannimien haku on muotoa:

/geocoding/v2/pelias/searchterm/similar?size=...&text=...

Esimerkiksi alla oleva kysely palauttaa 10 parhaiten samankaltaista paikannimeä syötteelle "mäntyk":

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

Toimintoa voi hyödyntää hakukäyttöliittymän toteutuksessa ja tarjota käyttäjän syötteen kanssa samankaltaisia paikannimiä.
Toiminto tukee myös saamenkielten kirjainlisukkeita (Tarke), jolloin hakuehdon ei tarvitse täysin vastata kirjoitusasua

  • esim: cevetjavri hakuehdolle toiminto tarjoaa vaihtoehdoksi mm. Čevetjävri Čeavetjávri Čevetjävrčuájâ Čevhujävri Čevžijävri  


Teknisistä syistä toiminto on käytettävissä vain paikannimille eli tietolähteelle geographic-names

Hakusanojen tulkinta

Hakusanojen tulkintaa (eli luettelopalvelun koodiselitteiden tunnistus koodiarvoiksi) kutsutaan seuraavasti:

/geocoding/v2/pelias/searchterm/decode?text=...

Vastaukset ovat GeoJSON FeatureCollection rakenteisia laajennuksilla varustettuna.

Toimintoa voi hyödyntää hakukäyttöliittymän toteutuksessa esim. syötteestä löytyneiden avainsanojen visualisointiin.  

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:

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

Palvelu sovittaa hakusanoja ja termejä region, placetype, placetypegroup, placetypecategory ja municipality koodilistojen kanssa. Lisätietoa koodilistojen sisällöstä luettelopalvelusta.

 

 

2025-03-10 - v2 korjaus käänteiseen geokoodaukseen

  • osoitteiden vastausten valintaan korjaus, jos käytetään laajaa hakualuetta (suuri buffer ja limit arvo)  tai sopivien kohteiden määrä hakualueella on suuri

2024-11-13 - v2 uusi tietolähde

  • Hallinnolliset yksiköt (administrative-units) valinnainen tietolähde lisättiin käänteiseen geokoodaukseen (reverse)

2023-10-31 - v2 muutokset 

  • Oletuskoordinaatisto nimetään CRS84
  • CRS84 on OGC API Features- ja GeoJSON-spesifikaatioiden mukaisesti WGS 84 maantieteelliset koordinaatit longitude, latitude -järjestyksessä
  • Palvelun toiminta tai vastaukset eivät muutu. Muutos toteutetaan siten, että sillä ei ole vaikutusta asiakassovelluksiin

2023-02-23 - v2 täydennykset

  • addresses ja interpolated-road-addresses taustapalveluille CRS84 tuki

2022-10-03 - v2 tuotantojulkaisu

 

 

Olet estänyt evästeet. Jos haluat antaa palautetta tästä sivusta, hyväksy kävijämittaus- ja analytiikkaevästeet.