API description (REST)

This service offers a Geocoding API for geocoding and reverse geocoding using different data sources like geographic names, interpolated road addresses, cadastral units and map sheets provided by the National Land Survey of Finland. Also building addresses from the Finnish Population Information System are used. 

The API description of the service as Open API 3.0 document is available at: 

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/openapi.json

The API is based on the subset of the Pelias API specification with some modifications (for example coordinate system and language parameters). Responses are formatted as GeoJSON data with extensions. 

The service supports ETRS-TM35FIN (EPSG:3067) coordinate system for all data sources the service is using and providing. There is also a partial support for WGS84 geographic coordinates (EPSG:4326) for some data sources.

This service is provided as an open interface with API-key authentication and as a contract based interface with http basic authentication

The Geocoding API uses geospatial feature data accessed from different data sources:

Data source

Example queries

Source id

Source product information
Geographic names search geographic-names Geographic Names Register 
Building addresses search addresses Building information of the Population Information System
Interpolated road addresses search interpolated-road-addresses Topographic Database (interpolated road addresses are part of this database)
Map sheets (TM35) search mapsheets-tm35 JHS 197 national recommendation (in Finnish)
Cadastral units search cadastral-units Cadastral index map

The service uses these data sources as back-end services when processing either forward or reverse geocoding API operations. Data sources return place names, addresses or other geospatial features that may have different set of properties and different data structures. The Geocoding Service uses relevant properties of data source feature types as filter parameters. Response data varies depending on data sources of matched features.

Operations supported by the API:

Operation

Path

Description
Forward geocoding /geocoding/v1/pelias/search Find a location with geographic coordinates by matching place names, addresses or other geospatial features of data sources with a search text or term.
Reverse geocoding /geocoding/v1/pelias/reverse Find a place name, an address or other geospatial feature located on given coordinates or nearby.
Decode text /geocoding/v1/searchterm/decode Match a text string with descriptions of code list values (accessed from a catalogue service), and if matched, then decode such description to a code value.
Similar terms /geocoding/v1/searchterm/similar Match a text string with place names and return a list of similar place names.

Please see Pelias API documentation for background information about:

Features and filter parameters supported by this service are listed on the Open API 3.0 description (link at the beginning of this page).

Forward geocoding

Note! The use of the example links below requires the use of an API-key.

A basic template for finding a location using a search term:

/geocoding/v1/pelias/search?text=...&sources=...&crs=...&lang=...

Responses are formatted as extended GeoJSON FeatureCollection.

Example queries to search by a place name with optional additional search terms:

Previous examples returned matched locations as ETRS-TM35FIN coordinates. WGS 84 geographic coordinates on responses can be requested by omitting crs parameter or by asking for crs=EPSG:4326. 

Following examples matching locations from other data sources than place names however works only using ETRS-TM35FIN coordinates. These examples also require defining which data sources should be queried, so sources parameter is required.

Map sheets (TM35)

Interpolated road addresses (here searching for "Mannerheimintie 3 Helsinki" or "Mannerheimvägen 3 Helsingfors"):

Same queries but now using building addresses:

It's recommended to URL encode text parameter, for example to search for "Pohjoinen Makasiinikatu" in Helsinki from building addresses:

A street number can be added to the request in this way:

Reverse geocoding

Reverse geocoding is used for finding nearest features at a given location. Responses are formatted as extended GeoJSON FeatureCollection.

For example to find nearest building addresses nearby a location a following query can be used:

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/reverse?&lang=fi&sources=addresses&boundary.circle.radius=10&request-crs=EPSG:3067&crs=EPSG:3067&point.lon=385000&point.lat=6675000 

In a specific case where the information of a parcel based on an exact position is the object of interest, the parameter boundary.circle.radius shoul be given a value of 0:

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/pelias/reverse?&lang=fi&sources=cadastral-units&boundary.circle.radius=0&request-crs=EPSG:3067&crs=EPSG:3067&point.lon=386069.217&point.lat=6678102.476(link is external)

Decode text

A template for decoding text (matching code list value descriptions and converting them to code values):

/geocoding/v1/pelias/searchterm/decode?text=...

Responses are formatted as extended GeoJSON FeatureCollection.

For example a search term "helsinki" matches with information from subregion and municipality code lists:

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/searchterm/decode?text=helsinki

Or a Finnish text "museo" is matched with a place type code used to classify museums:

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/searchterm/decode?text=museo

 

There can be many terms separated by encoded space char. The following example searches for "jyrä", "Heinola" and "koski" resulting with multiple matches for different code lists:

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/searchterm/decode?text=jyr%C3%A4%20Heinola%20koski

The service matches search terms with region, placetype, placetypegroup, placetypecategory and municipality code lists. Please see index page of the catalogue service for more information.

Similar terms

A template for similar terms (place names) for text input:

/geocoding/v1/pelias/searchterm/similar?size=...&text=...

For example this query find 10 similar terms for text input "mäntyk":

https://avoin-paikkatieto.maanmittauslaitos.fi/geocoding/v1/searchterm/similar?size=10&text=m%C3%A4ntyk

BETA-release 2019-03.

Productional release 2020-02.