Ohje API-avaimen käyttöön

Avoimet rajapintapalvelut tarjotaan maksuttomina Maanmittauslaitoksen avoimen rajapintapalvelun käyttöehtojen mukaisesti. Palveluiden käyttö edellyttää API-avaimen liittämistä rajapinnan palvelupyyntöihin. API-avain (eli API-key) on uniikki merkkijono, jonka rajapinnan käyttäjä luo OmaTili-palvelussa.

API-avaimen avulla Maanmittauslaitos pystyy seuraamaan avoimien rajapintapalveluiden käyttöastetta ja tarvittaessa ottamaan palvelujen käyttäjiin yhteyttä.

Seuraavien rajapintojen käyttöön tarvitaan API-avain:

• Geokoodauspalvelu
• Karttakuvapalvelu (Vektoritiilet)
• Karttakuvapalvelu (WMTS), avoin rajapintayhteys
• Kiinteistötietojen kyselypalvelu (OGC API Features), vain avoimet tuotteet
• Maastotietokannan kyselypalvelu (OGC API Features)
• Nimistö (OGC API Features)
• Ortokuvien ja korkeusmallien kyselypalvelu (WCS)
• Paikkatiedon tiedostopalvelu (OGC API Processes)

API-avaimien luominen ja hallinta

Voit luoda API-avaimen Maanmittauslaitoksen OmaTili-palvelussa seuraavasti:

1. Rekisteröidy OmaTili-palveluun.
2. Kirjaudu palveluun rekisteröimälläsi sähköpostilla.
   Kirjautumisen jälkeen voit
   - luoda uuden API-avaimen,
   - poistaa olemassa olevan API-avaimen.
   - muokata tietojasi tai poistaa käyttäjätunnuksesi.

Jos poistat API-avaimen käytöstä, et saa enää käyttöösi rajapintoja, jotka hyödyntävät API-avaintasi toimiakseen. API-avaimen poistamista ei voi peruuttaa, mutta voit milloin vain luoda uuden API-avaimen OmaTili-palvelussa. Uusi API-avain on otettava käyttöön niissä rajapinnoissa, joissa vanha API-avain on ollut käytössä.

Katso ohjevideo API-avaimen luomisesta OmaTili-palvelussa

Unohtuiko OmaTili-palvelun salasana? Tilaa uusi salasana.

Ongelmia OmaTili-palvelun kanssa? Ota yhteyttä tekniseen tukeen.

• Tietosuojaseloste: Maanmittauslaitoksen tietojärjestelmien käyttäjien henkilötiedot 

API-avaimen käyttö

Tähän on tarjolla kaksi vaihtoehtoa:

HTTP Basic Authentication 

• mahdollisia käyttökohteita: rajapinnan käyttö paikkatieto-ohjelmistosta, itse ohjelmoitavasta asiakassovelluksesta tai selaimesta (osoitelaatikon kautta)
• 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 (Vinkkikuva löytyy Vihjeitä Maanmittauslaitoksen Maastotietokannan OGC API Features -palvelun käyttäjille .pdf:stä sivulla 1.). API-avaimen liittämisessä voi olla ohjelmakohtaisia eroja. Jos esimerkiksi salasana-kenttää ei voi jättää tyhjäksi, kannattaa kokeilla laittaa API-avain sekä käyttäjätunnus- että salasanakenttiin.
• 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

• mahdollisia käyttökohteita: rajapinnan käyttö itse ohjelmoitavasta asiakassovelluksesta
• API-avain voidaan välittää rajapintapalveluun myös URL-parametrina
• 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>