Avoimet rajapintapalvelut

Avoimet rajapintapalvelut tarjotaan maksuttomina ja Maanmittauslaitoksen avoimen rajapintapalvelun käyttöehtojen mukaisesti. Palveluiden käyttö edellyttää API-avaimen liittämistä rajapinnan palvelupyyntöihin. Ohjeet API-avaimen luontiin ja käyttöön on kuvattu tämän sivun kohdassa Avoin rajapintakäyttö.

Seuraavat palvelut ovat käytettävissä avoimina rajapintapalveluina:

Avoimen rajapintakäytön lisäksi näistä palveluista voi olla tarjolla myös sopimuskäyttöön tarkoitettu rajapintayhteys. Kunkin palvelun dokumentaatiossa on kuvattu palvelulle mahdolliset käyttömuodot (sopimuskäyttö, avoin rajapintakäyttö, BETA-rajapintakäyttö).

Avoin rajapintakäyttö

Tilin hallinta ja API-avaimen luonti

Avoimien rajapintojen käyttöön tarvitaan API-avain. Käyttäjä voi luoda itselleen API-avaimen Maanmittauslaitoksen tarjoamassa OmaTili-palvelussa. 

Käyttäjän on rekisteröidyttävä ennen API-avaimen luontia. Rekisteröityminen tehdään osoitteessa https://omatili.maanmittauslaitos.fi/user/new/avoimet-rajapintapalvelut.

API-avaimen luomiseen siirry uudestaan osoitteeseen https://omatili.maanmittauslaitos.fi/user/new/avoimet-rajapintapalvelu. Kirjaudu palveluun sähköpostiosoitteella ja salasanalla, jonka loit rekisteröitymisvaiheessa. Kirjautumisen jälkeen voit luoda API-avaimen, poistaa olemassa oleva API-avain, muokata tietojasi tai poistaa käyttäjätunnuksesi.

Yhteenvetona linkit OmaTili-palveluun

Rajapintayhteys API-avaimella

API-avain (eli API-key) on merkkijono, joka tulee liittää jokaiseen avoimen rajapintakäytön mukaiseen palvelupyyntöön. Tähän on tarjolla kaksi vaihtoehtoista tapaa.

HTTP Basic Authentication 

  • tässä vaihtoehdossa rajapintapyynnön URL välitetään palveluun sellaisena kuin URL on määritelty palvelun dokumentaatiossa
  • käytettäessä rajapintapalvelua selaimesta (selaimen osoitelaatikon kautta) tai esim. QGIS-ohjelmistosta, asiakasohjelmisto pyytää käyttäjältä käyttäjätunnusta ja salasanaa - tällöin API-avain syötetään käyttäjätunnuksen paikalle ja salasana voidaan jättää tyhjäksi   
  • käytettäessä rajapintapalvelua itse ohjelmoitavasta asiakassovelluksesta
    • jokaiseen rajapintapalveluun tehtävään HTTPS-pyyntöön on liitettävä Authorization-header, jonka muoto Basic HTTP Authentication (https://tools.ietf.org/html/rfc7617) mukainen
    • Authorization-headerissa user-id kentän arvoksi tulee asettaa API-avaimen merkkijono täsmällisenä ja password kenttä jätetään tyhjäksi
  • etuna tätä vaihtoehtoa käytettäessä on se että rajapintapalvelun resurssien väliset URL-linkit toimivat sellaisenaan, kunhan jokaisessa HTTPS-pyynnössä mukana em. kuvattu Authorization-header 

URL-parametri

  • vaihtoehtoisesti API-avain voidaan välittää rajapintapalveluun myös URL-parametrina
  • huomioitava kuitenkin että jos rajapintapalvelun tietty resurssi palauttaa URL-linkin toiseen resurssiin, niin tämä linkki ei sisällä API-avainta, vaan käyttäjän on itse lisättävä API-avain URL-parametrina myös viitatun resurssin URL-linkkiin
  • URL-parametrin muoto:
    • api-key=<oma-api-avain>