Technical description – Topographic Database (OGC API Features)
The service offers a feature service based on the OGC API Features standard for topographic data in the Topographic Database.
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/maastotiedot/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/maastotiedot/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 service supports the GeoJSON file format.
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 search parameters and certain property data items related to geographic features have been modelled as code values, whose descriptions have been published through a separate catalogue service. The service’s data products are based on the current Topographic Database’s datasets.
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
- Part 3 - Filtering (standard draft): query parameters based on the common query language (CQL2)
The technical description of the API has been published in accordance with the Open API 3.0 specification. A link to the description is available in the ‘Questions and examples’ section.
Geographic features can be queried using following parameters: ID, bounding box (bbox), date and time (datetime), and attributes (filter).
(In Finnish) Tips for users of the OGC API Features service in the NLS Topographic Database (PDF).
Sources and products
Data sources and conceptual models
The feature service’s data sources include the NLS Topographic Database’s datasets that are within the scope of an open data licence. The service’s data is kept constantly updated.
The link above also gives access to descriptions of the Topographic Database’s feature model, whose classification describes the feature groups and classes of geographic features.
GeoJSON schemas
For the feature service, the GeoJSON schemas of the Topographic Database’s features are produced programmatically using the data model built for map services, which is very close, but not quite identical, to the Topographic Database’s object model.
The GeoJSON schemas of topographic features produced by the service are simple features. This means that the data structures do not have any nested subfeature structures, and property data (attributes) are directly available under the ‘Feature’ element. Shared properties for all topographic features produced by the service:
- the id attribute is a service-specific identifier (integer)
- geometry: applicable geometry depending on the topographic feature’s feature class and type (e.g. ‘Point’, ‘LineString’, ‘Polygon’)
- shared properties directly under the ‘Feature’ element
- mtk_id (an identifier specific to the Topographic Database)
- sijaintitarkkuus (horizontal accuracy)
- korkeustarkkuus (elevation accuracy)
- aineistolahde (data source)
- alkupvm (start date)
- kohderyhma (feature group)
- kohdeluokka (feature class)
In addition, features may have other property data directly under the ‘Feature’ element, depending on the topographic feature.
A more detailed description of the data content of feature properties is available in the Topographic Database’s object model.
Feature collections
The feature collections provided by the service categorized by topographic features:
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections
A more detailed description of the topographic features ‘road line’ or ‘building’ (other features with similar requests):
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/tieviiva
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/rakennus
The feature classes supported for different topographic features have been published in the service’s Open API description (https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/api). For example, this data is available for the topographic feature ‘road line’ in the ‘/collections/tieviiva/items’ section under the description of service requests (/paths), in which the supported feature classes have been defined:
{ "name" : "kohdeluokka", "in" : "query", "description" : "Filter the collection by kohdeluokka", "required" : false, "style" : "form", "explode" : false, "schema" : { "type" : "integer", "format" : "int32", "enum" : [ 12131, 12132, 12141, 12111, 12112, 12151, 12312, 12152, 12313, 12121, 12122, 12314, 12316 ] }
The supported feature classes have been listed in the enumeration, and properties for each topographic feature is based on the Topographic Database’s object model.
The schema structure can be identified by searching for example features using a feature class belonging to a specific topographic feature (here, example data has been searched for using the additional BBOX filter).
For example, feature class 12111 (Road Ia) in the topographic feature ‘tieviiva‘ (road line):
For example, feature class 42211 (Residential building, 1–2 storeys) in the topographic feature ‘rakennus’ (building):
Queries and examples
Conformance and collections
The official standard should first be read before developing OGC API Features client applications.
The Topographic Database’s OGC API Features service is in line with the standard’s Core part. In addition, it supports the following, not yet officially approved, standard expansions:
• expanded coordinate system support in bbox rectangular boundaries (crs-bbox parameter) and response geometries (crs parameter)
• cql search parameters
Supported conformance classes:
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/conformance
Collections provided by the service and supported coordinate systems:
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections
Open API descriptions
The Open API 3.0 description provides more detailed information about how metadata and geographic features in line with the Topographic Database can be searched for in the service using service requests in accordance with the OGC API Features standard:
https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/api
Searching for topographic features
Brief instructions on different search methods in OGC API Features services (e.g. searching for topographic features using an identifier, response pages, coordinates and rectangular boundaries, filtering using property data) are available in the Geographic names OGC API Features service’s documentation under ‘Queries and examples’. The search methods described in the instructions can also be applied in the Topographic Data OGC API Features service, while feature classes and their schemas, as well as search parameters, are collection-specific.
A few example searches in the Topographic Data OGC API Features service are given below.
Searching for a single (undefined) topographic feature in a certain collection (see which collections identifiers are permitted after the collections identifier using the request https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections):
Searching for topographic features (the ‘road line’ feature here) using BBOX boundaries (ETRS-TM35FIN) so that geometries are also returned in ETRS-TM35FIN coordinates in the response:
A corresponding BBOX search with an added property data filter (the feature class must be 12122 or 12314):
Searching for a topographic feature using the mtk_id identifier (in the ‘park’ feature here):
The properties that can be used as search parameters have been listed in more detail in the Open API description of the API service.
Version management
Production update 2023-12-18
Production publication 2020-06
BETA publication 2019-05