Geographic names (OGC API Features)
This service is a OGC API Features interface for places, place names and map names of the Geographic Names Register provided by the National Land Survey of Finland.
There are two OGC API Features services available:
- The open and free service is using API keys for authentication. User can acquire an API key as self-service.
https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/ - The agreement-based service has a higher service level. This service is subject to a charge and a signed User Account Agreement is required.
https://sopimus-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/- Please contact the interface service customer support at verkkopalvelut@maanmittauslaitos.fi for further information if you are interested in the agreement based service.
The API is based on the OGC API Features standard and API description is published as Open API 3.0.1 specification. Features can be queried using identifiers, properties and bounding box filters. Following output response content types are supported:
- GeoJSON (primary content type for a OGC API Features service, excellent for simple features, supports also complex features)
- GML (also available for backward compatibility reasons, this service supports GML 3.2.1)
As specified by OGC API Features and GeoJSON specifications the default coordinate reference system supported by this service is WGS 84 geographic coordinates (lon-lat) identified by the CRS84 identifier. The service also supports ETRS-TM35FIN, ETRS-TM34..36 and ETRS-GK19..31FIN projected map coordinates, WGS84-coordinates identified by the EPSG:4326 identifier, ETRS89 (2D) geographic coordinates and Web Mercator-coordinate reference system.
Some query parameters and properties of response features are modeled as code values whose descriptions are published via a separate catalogue service.
Sources and products
The Geographic Names Register contains approximately 800,000 named places and their names in different languages. There are also map names with cartographical information on the register. Please see more information about place, place name and map name products and their data sources on the product description or meta data published on Paikkatietohakemisto - the meta data service for Finnish geospatial information.
Products offered for API users using this OGC API Features service:
| Product | Example features | FeatureCollection id (OGC API Features) | FeatureType |
|---|---|---|---|
| Places | GeoJSON, GML | places | Place |
| Place names | GeoJSON, GML | placenames | PlaceName |
| Place names (simple) | GeoJSON, GML | placenames_simple | PlaceNameSimple |
| Map names | GeoJSON, GML | mapnames | MapName |
Place names can be queried using Places, Place names and Place names (simple) products. Place names and Places products contain same information but data structures differ. The feature type for the Places product is a named place that has a place type and position with names and their attributes (like spelling and language). The feature type for the Place names product is a place name having spelling and language, optional parallel names and also properties for a named place (like place type and position). There is also a simplified (by data structure) product for place names.
For accessing map name data there is only one product that is Map names. It has a map name as the feature type. Map names has properties for map name text, layout and typography with most important properties also from a named place and a place name relating to a map name. Queries are filtered using a map product.
Code lists published on a catalogue service and used on query parameters and responses (partially description text only in Finnish):
| Name in Finnish | Name in English | Code lists |
|---|---|---|
| Paikanlaji | PlaceType | fin, swe, eng |
| Paikanlajikuvaus | PlaceTypeDescription | fin, swe, eng |
| Paikanlajiteema | PlaceTypeCategory | fin, swe, eng |
| Paikanlajiryhma | PlaceTypeGroup | fin, swe, eng |
| Paikanlajialaryhma | PlaceTypeSubgroup | fin, swe, eng |
| Kunta | Municipality | fin, swe, eng |
| Seutukunta | SubRegion | fin, swe, eng |
| Maakunta | Region | fin, swe, eng |
| Mittakaavarelevanssi | ScaleRelevance | fin, swe, eng |
| Kieli | Language | fin, swe, eng |
| KielenVirallisuus | LanguageOfficiality | fin, swe, eng |
| KielenValtaasema | LanguageDominance | fin, swe, eng |
| PaikannimenLahde | PlaceNameSource | fin, swe, eng |
| PaikannimenStatus | PlaceNameStatus | fin, swe, eng |
| Karttatuote | MapProduct | fin, swe, eng |
| Mittakaavaluokka | ScaleClass | fin, swe, eng |
| TekstinAakkoslaji | TextCase | fin, swe, eng |
| TekstinKirjasintyyppi | TextFont | fin, swe, eng |
| TekstinVari | TextColour | fin, swe, eng |
| TekstinHarvennus | TextSpacing | fin, swe, eng |
| TekstinEnsisijaisuus | TextPreference | fin, swe, eng |
| TuoteTapahtumaLaji | ProductEventType | fin, swe, eng |
Queries and examples
Conformance and products
When developing OGC API Features client applications it's recommended to firs read the OGC API - Features - Part 1: Core -standard (http://docs.opengeospatial.org/is/17-069r3/17-069r3.html(link is external))
This OGC API Features -service conforms to the Core part of the standard. It also supports following standard extensions:
- Part 2 - Coordinate Reference Systems by Reference: support for bbox queries (bbox-crs parameter) and response geometries (using crs parameter) in alternative coordinate reference systems
Supported conformance classes are published as:
https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/conformance
You can find products offered (collections) and coordinate systems supported:
https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections
Open API descriptions
Please see Open API 3.0.1 description for more information how to access meta data and geographic names features from this OGC API Features conformant service:
https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/api
Codelist API of a catalogue service has an index page for all code lists available. It also publishes an Open API 3.0.1 description:
https://beta-paikkatieto.maanmittauslaitos.fi/catalogue/openapi.json
https://beta-paikkatieto.maanmittauslaitos.fi/catalogue/openapi.yaml
Using OGC API Features service
This is a short guide how to use an OGC API Features service, here with examples for the Place names product. Similar queries are naturally possible also for other products too. Please see Open API description for more information about filter parameters on different products.
Feature by ID
By default as GeoJSON output:
Same as GML 3.2.1:
Content paging
OGC API Features has a good support for content paging of response features. For example a partial set for a collection, first 100 features:
This returns a response with those 100 features and also a link to a next set of 100 features, ie.:
This one returns a response with link to a subsequent set and so on.
Coordinates and bounding box filters
By default BBOX-filter parameter and response geometries contain WGS84 geographic coordinates (CRS84), for example :
To filter using ETRS-TM35FIN coordinates (EPSG:3067) a bbox-crs filter parameter (that is not part of OGC API Features core standard draft) can be used:
Previous example returns response geometries still as WGS84 coordinates. To project response to another coordinate system a crs parameter can be used:
Supported coordinate system identifiers are published on collection metadata:
https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections
Filtering by properties
This example requests all place names for one municipality (837 = Tampere) in sub sets of 100 features for each call, the first set:
To requests place names from multiple municipalities at once different municipality code values are listed on a parameter field (this works like OR operator that is "418 or 837 or 980" for our example):
Different parameters are handled just like AND operator would work. For example this example filters both with municipality code and place name spelling (as a wildcard query this example returns all place names in Tampere that has their case insensitive spelling starting with a word "tammer"):
Previous query returns 5 features including "Tammerkoski" ja "Tammerfors". If a place type filter parameter (in the example code value 2020115 that means "Rapids") is added to a request then response would have exactly one feature ("Tammerkoski"):
Version management
Production update 2023-12-18
Production publication 2020-06
BETA-release 2019-03