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

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

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.

 

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 
Nimistön kyselypalvelu (OGC API Features)

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:

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

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

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", ...

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.

    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

    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:

    https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v2/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/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