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)

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.

Instruction video (in Finnish)

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:

User authentication (HTTP Basic Authentication) 

• Using the API with geospatial software or a web browser
  • If you use the API service with a geospatial information software such as QGIS or a browser, the client application will prompt you for a username and password
  • Enter the API key in the username field and leave the password field empty.
  • You can find a helpful screenshot on page 1 of the guide: Vihjeitä Maanmittauslaitoksen Maastotietokannan OGC API Features -palvelun käyttäjille.
  • There may be software-specific differences in how the API key is entered. For example, if the application does not allow the password field to be empty, try entering the API key in both the username and password fields.
• Using the API with a self-programmed client application
  • Include an Authorization header in every HTTPS request to the API service, formatted according to Basic HTTP Authentication (https://tools.ietf.org/html/rfc7617).
  • In the Authorization header, set the user-id field to the exact API key string and leave the password field empty.
  • The advantage of this method is that the URL links between resources in the API service will work as-is, as long as each HTTPS request includes the Authorization header as described above.
• The API request URL should be used exactly as defined in the service documentation

Programmatic use via URL parameter

• Possible use cases: Using the Api from a custom-built client application
• The API key can also be passed to the API service as a URL parameter
• If a specific resource in the API service returns a URL link to another resource, that link will not include the API key. The user must manually add the API key as a URL parameter to the linked resource´s URL.
• Form of the URL parameter:
  • api-key=<oma-api-avain