Instructions for using the API key

Open interface services are provided free of charge in accordance with the terms of use of the open interface service of the National Land Survey of Finland . The use of the services requires the API key to be linked with interface service requests. The API key is a unique string that is created in the My Account service.

With the API key, the National Land Survey of Finland can monitor the utilisation rate of open interface services and contact the service users where necessary.

The API key is needed to use the following interfaces (in Finnish):

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

Creation and management of API keys

You can create a personal API key in the My Account service of the National Land Survey of Finland as follows:

1. Register in the My Account service.
2. Log in to the service with the email address you have registered.
   After logging in, you can
   - create a new API key
   - delete an existing API key
   - edit your information or delete your user ID

If you disable the API key, you will no longer have access to interfaces that use your API key to work. You cannot cancel the deletion of the API key, but you can create a new API key in the My Account service at any time. You must enable the new API key in the interfaces where you used the old API key.

Did you forget your My Account service password? Order a new password.

Problems with My Account service? Contact technical support.

• Privacy policy: Personal data of users of the National Land Survey of Finland’s information systems 

Using the API key

Two alternatives are available:

HTTP Basic Authentication 

• possible uses: use of the interface from geospatial information software, the self-programmed customer application or the browser (through the address box)
• the URL of the interface query is transmitted to the service in the way the URL has been defined in the service documentation
• For example, when using the interface service through the browser (through the browser address box) or with for example QGIS software, the customer software asks the user for a password and user ID – the user ID is then replaced with the API key, and the password can be left blank (See  Vihjeitä Maanmittauslaitoksen Maastotietokannan OGC API Features -palvelun käyttäjille.pdf on page 1.). However there might occur differences between softwares.
•  when using the interface service from a self-programmed customer application
  • an Authorisation header of the form Basic HTTP Authentication (https://tools.ietf.org/html/rfc7617) must be attached to each HTTPS request made to the interface service
  • the API key’s string must be set as the value of the user-id field in the Authorisation header, and the password field must be left empty
•  the advantage when using this alternative is that the URL links between the interface service resources work as such as long as each HTTPS request includes the Authorisation header described above.

URL parameter

• possible uses: use of the interface through a self-programmed customer application
• The API key can also be transmitted to the interface service as a URL parameter
•   If a specific resource in the interface service returns a URL link to another resource, the link does not contain an API key, but the user must also add the API key as a URL parameter to the URL link of the resource referred to
• Form of the URL parameter:
  • api-key=<oma-api-avain