Skip to main content

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. 

The API of the service is available at: https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/

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)

Primary coordinate system supported by the service according to OGC API Features and GeoJSON specifications is WGS 84 geographic coordinates. The service also supports ETRS-TM35FIN, ETRS-TM34..36, ETRS-GK19..31FIN projected map coordinates and ETRS89 geographic coordinates.

Some query parameters and properties of response features are modeled as code values whose descriptions are published via a separate catalogue service.

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 GeoJSONGML places Place
Place names GeoJSONGML placenames PlaceName
Place names (simple) GeoJSONGML placenames_simple PlaceNameSimple
Map names GeoJSONGML mapnames MapName

Place names can be queried using PlacesPlace 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 finsweeng
Seutukunta SubRegion finsweeng
Maakunta Region finsweeng
Mittakaavarelevanssi ScaleRelevance finsweeng
Kieli Language finsweeng
KielenVirallisuus LanguageOfficiality finsweeng
KielenValtaasema LanguageDominance finsweeng
PaikannimenLahde PlaceNameSource finsweeng
PaikannimenStatus PlaceNameStatus finsweeng
Karttatuote MapProduct finsweeng
Mittakaavaluokka ScaleClass finsweeng
TekstinAakkoslaji TextCase finsweeng
TekstinKirjasintyyppi TextFont finsweeng
TekstinVari TextColour finsweeng
TekstinHarvennus TextSpacing finsweeng
TekstinEnsisijaisuus TextPreference finsweeng
TuoteTapahtumaLaji ProductEventType fin, swe, eng

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))

OGC API Features service implementation described here is conformant with the draft with following exceptions or extensions:

  • extension (unofficial): coordinate support for bbox queries (crs-bbox parameter) and response geometries (using crs parameter)

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

See also same information as a generated HTML document.

 

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: 

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items/PN_40889621 

Same as GML 3.2.1:

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items/PN_40889621.gml 

 

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:

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?limit=100 

This returns a response with those 100 features and also a link to a next set of 100 features, ie.:

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?limit=100&minId=40000102

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 (CRS80), for example :

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?bbox=22.15,63.45,22.2,63.5

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:

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?bbox=490000,6904000,492000,6906000&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067

Previous example returns response geometries still as WGS84 coordinates. To project response to another coordinate system a crs parameter can be used:

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?bbox=490000,6904000,492000,6906000&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3067&crs=http://www.opengis.net/def/crs/EPSG/0/3067

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:

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?municipality=837&limit=100

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):

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?municipality=418,837,980&limit=100

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"):

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?municipality=837&spelling_case_insensitive=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"):

https://avoin-paikkatieto.maanmittauslaitos.fi/geographic-names/features/v1/collections/placenames/items?municipality=837&spelling_case_insensitive=tammer*&placeType=2020115

BETA-release 2019-03.