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:
- Rekisteröidy OmaTili-palveluun.
- 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.
API-avaimen käyttö
Tähän on tarjolla kaksi vaihtoehtoa:
Käyttäjän tunnistautuminen (HTTP Basic Authentication)
- Rajapinnan käyttö paikkatieto-ohjelmistolla tai selaimella
- Jos käytät rajapintapalvelua esim. QGIS-ohjelmistolla tai selaimella, asiakasohjelmisto pyytää käyttäjätunnusta ja salasanaa
- Syötä API-avain käyttäjätunnuksen paikalle ja jätä salasanakenttä tyhjäksi
- Löydät ohjeen sivulta 1 vinkkikuvan: Vihjeitä Maanmittauslaitoksen Maastotietokannan OGC API Features -palvelun käyttäjille.
- API-avaimen liittämisessä voi olla ohjelmakohtaisia eroja. Jos esimerkiksi salasanakenttää ei voi jättää tyhjäksi, kokeile laittaa API-avain sekä käyttäjätunnus- että salasanakenttiin.
- Rajapinnan käyttö itse ohjelmoitavalla asiakassovelluksella
- Liitä jokaiseen rajapintapalveluun tehtävään HTTPS-pyyntöön Authorization-header, jonka muoto on Basic HTTP Authentication (https://tools.ietf.org/html/rfc7617) -mukainen
- Aseta Authorization-headerissa user-id kentän arvoksi API-avaimen merkkijono täsmällisenä ja jätä password-kenttä tyhjäksi
- Etuna tässä vaihtoehdossa on, että rajapintapalvelun resurssien väliset URL-linkit toimivat sellaisenaan, kunhan jokaisessa HTTPS-pyynnössä mukana em. kuvattu Authorization-header.
- Rajapintapyynnön URL välitetään palveluun sellaisena kuin URL on määritelty palvelun dokumentaatiossa
Ohjelmallinen käyttö (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, 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>