From c6ff56512b4d244c3fd5fe74d2441336d4f25a21 Mon Sep 17 00:00:00 2001
From: jampukka <janne.z.heikkila@gmail.com>
Date: Fri, 19 Dec 2025 16:57:07 +0200
Subject: [PATCH] Add finnish_admin_units example

---
 examples/finnish_admin_units/README.md        | 121 ++++++++++++
 .../administrative_areas.properties           | 174 ++++++++++++++++++
 2 files changed, 295 insertions(+)
 create mode 100644 examples/finnish_admin_units/README.md
 create mode 100644 examples/finnish_admin_units/administrative_areas.properties

diff --git a/examples/finnish_admin_units/README.md b/examples/finnish_admin_units/README.md
new file mode 100644
index 00000000..e4cb6485
--- /dev/null
+++ b/examples/finnish_admin_units/README.md
@@ -0,0 +1,121 @@
+# Division into Administrative Areas (vector)
+
+This example project demonstrates how to create an OGC API Features service with hakunapi to provide Finland's administrative boundaries available from the National Land Survey of Finland (Maanmittauslaitos).
+
+The dataset depicts the municipalities, regions, Regional State Administrative Agencies, Wellbeing Services Counties, and the national border of Finland.
+
+## About the Dataset
+
+The Division into Administrative Areas dataset is produced and maintained by the National Land Survey of Finland. It includes comprehensive administrative boundary data for Finland at multiple hierarchical levels and map scales.
+
+The 2025 dataset contains five administrative hierarchy levels: Municipalities (Kunta), Regions (Maakunta), Regional State Administrative Agencies (Aluehallintovirasto), Wellbeing Services Counties (Hyvinvointialue), and Nations (Valtakunta). Each level is available at five map scales: 1:10,000, 1:100,000, 1:250,000, 1:1,000,000, and 1:4,500,000, resulting in 25 total feature collections.
+
+The dataset is updated annually in January to reflect municipal boundary changes. For complete technical specifications, see the [official product description](https://www.maanmittauslaitos.fi/en/maps-and-spatial-data/datasets-and-interfaces/product-descriptions/division-administrative-areas-vector).
+
+## Getting the Data
+
+### Download from Maanmittauslaitos
+
+The GeoPackage files can be downloaded from the National Land Survey of Finland's open data portal:
+
+1. Visit [Maanmittauslaitos Open Data](https://www.maanmittauslaitos.fi/en/maps-and-spatial-data/datasets-and-interfaces)
+2. Navigate to the Division into Administrative Areas (vector) dataset
+3. Download the zip files for your desired scales
+4. Extract each zip file to obtain the GeoPackage files
+
+The extracted GeoPackage files should follow this naming convention:
+- `SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_10k.gpkg`
+- `SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_100k.gpkg`
+- `SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_250k.gpkg`
+- `SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_1000k.gpkg`
+- `SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_4500k.gpkg`
+
+Each GeoPackage file contains all five administrative levels as separate tables (Kunta, Maakunta, Aluehallintovirasto, Hyvinvointialue, Valtakunta).
+
+### License
+
+The dataset is available under the **National Land Survey open data Attribution CC 4.0 licence**.
+
+When using this data, include the attribution:
+```
+Contains data from Division into administrative areas (vector), National Land Survey of Finland
+```
+
+See the [official license](https://www.maanmittauslaitos.fi/en/opendata-licence-cc40) for details.
+
+## Setting Up the Data
+
+This example uses GeoPackage files directly, so no database setup is required.
+
+1. Place the downloaded GeoPackage files in the `examples/finnish_admin_units/` directory (or update the paths in `administrative_areas.properties`)
+
+2. Each GeoPackage file contains tables for all five administrative levels:
+   - Kunta (Municipalities)
+   - Maakunta (Regions)
+   - Aluehallintovirasto (Regional State Administrative Agencies)
+   - Hyvinvointialue (Wellbeing Services Counties)
+   - Valtakunta (Nations)
+
+## Configuring and running hakunapi with tomcat
+
+hakunapi by default builds into a war package called `features.war`. For the following we'll assume you have a tomcat instance running on localhost on port 8080.
+
+First build the project with `mvn clean package` and give the built war to your tomcat instance to load.
+
+Now we need to tell hakunapi where to look for the configuration file. First, create a directory to contain the configuration files. We will create ours in `/app/features_admin_areas/`.
+```
+mkdir -p /app/features_admin_areas
+```
+
+and copy the example config file there
+```
+cp examples/finnish_admin_units/administrative_areas.properties /app/features_admin_areas/
+```
+
+If you placed your GeoPackage files somewhere other than the example directory, update the `collections.*.db` paths in `administrative_areas.properties` to point to the correct locations.
+
+On startup hakunapi will look for system property `{context_path}.hakuna.config.path` (e.g. `features.hakuna.config.path`) followed by `hakuna.config.path` if the first one didn't work. This property is used to control where hakunapi searches for the main configuration file of the hakunapi instance. In our case we'll need to add `-Dfeatures.hakuna.config.path=/app/features_admin_areas/administrative_areas.properties` to the tomcat launch options.
+
+Now hakunapi can find the configuration file and the GeoPackage data files.
+
+Restart your tomcat instance and navigate to http://localhost:8080/features
+
+The service provides 25 feature collections (5 administrative levels × 5 scales each). Browse the collections at http://localhost:8080/features/collections
+
+## Preparing for Production
+
+### Configure Contact Information
+
+Edit `administrative_areas.properties` and update the contact information:
+
+```properties
+api.contact.name=Your Name or Organization
+api.contact.email=contact@example.com
+api.contact.url=https://your-organization.com
+```
+
+### Configure Server Endpoints
+
+Update the server URL configuration to match your production environment:
+
+```properties
+servers=production
+servers.production.url=https://your-domain.com/features
+servers.production.description=Production server
+```
+
+### Output Formats
+
+The service provides three output formats by default:
+- **GeoJSON** (`f=json`) - Default format for spatial data
+- **HTML** (`f=html`) - Human-readable web interface
+- **CSV** (`f=csv`) - Tabular data export with geometries as WKT (Well-Known Text)
+
+### API Limits
+
+Configure request limits in `administrative_areas.properties`:
+
+```properties
+getfeatures.limit.default=1000
+getfeatures.limit.max=10000
+```
diff --git a/examples/finnish_admin_units/administrative_areas.properties b/examples/finnish_admin_units/administrative_areas.properties
new file mode 100644
index 00000000..04c55891
--- /dev/null
+++ b/examples/finnish_admin_units/administrative_areas.properties
@@ -0,0 +1,174 @@
+# General information about the api
+api.title=Division into administrative areas (vector)
+api.version=0.1
+api.description=Division into administrative areas (vector) is a dataset depicting the municipalities, regions, Regional State Administrative Agencies, and the national border of Finland.
+api.contact.name=Name of Contact
+api.contact.email=hakunapi@io.github.nlsfi
+api.contact.url=https://github.com/nlsfi/hakunapi
+api.license.name=National Land Survey open data Attribution CC 4.0 licence, contains data from Division into administrative areas (vector)
+api.license.url=https://www.maanmittauslaitos.fi/en/opendata-licence-cc40
+
+# List of servers 
+## Required, comma-separated list of server the API is
+servers=dev
+## The url of the server has to be correct as it is used for all links generated by the server
+#servers.dev.url=http://${X-Forwarded-Host}/${X-Forwarded-Path}
+servers.dev.url=http://localhost:8080/features
+servers.dev.description=Development server
+
+# API level configuration
+formats=json,html,csv
+formats.json.type=json
+formats.html.type=html
+formats.csv.type=csv
+#formats.geojson.forceLonLat=true
+getfeatures.limit.default=1000
+getfeatures.limit.max=10000
+
+srid=3067
+
+db.classes=fi.nls.hakunapi.source.gpkg.GpkgSimpleSource
+
+default.collections.type=gpkg
+default.collections.srid=3067
+
+# Collections and their configurations	
+## Required, comma-separated list of all collections
+collections=municipalities,municipalities_100k,municipalities_250k,municipalities_1000k,municipalities_4500k,regions,regions_100k,regions_4500k,regions_250k,regions_1000k,regional_state_administrative_agencies,regional_state_administrative_agencies_100k,regional_state_administrative_agencies_250k,regional_state_administrative_agencies_1000k,regional_state_administrative_agencies_4500k,wellbeing_services_counties,wellbeing_services_counties_100k,wellbeing_services_counties_250k,wellbeing_services_counties_1000k,wellbeing_services_counties_4500k,nations,nations_100k,nations_250k,nations_1000k,nations_4500k
+
+# 1:10k
+
+collections.municipalities.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_10k.gpkg
+collections.municipalities.table=Kunta
+collections.municipalities.title=Municipalities 2025
+collections.municipalities.parameters=gml_id,natcode,namefin,nameswe,landarea,freshwarea,seawarea,totalarea
+
+collections.regions.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_10k.gpkg
+collections.regions.table=Maakunta
+collections.regions.title=Regions 2025
+collections.regions.parameters=gml_id,natcode,namefin,nameswe
+
+collections.regional_state_administrative_agencies.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_10k.gpkg
+collections.regional_state_administrative_agencies.table=Aluehallintovirasto
+collections.regional_state_administrative_agencies.title=Regional state administrative agencies 2025
+collections.regional_state_administrative_agencies.parameters=gml_id,natcode,namefin,nameswe
+
+collections.wellbeing_services_counties.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_10k.gpkg
+collections.wellbeing_services_counties.table=Hyvinvointialue
+collections.wellbeing_services_counties.title=Wellbeing Services Counties 2025
+collections.wellbeing_services_counties.parameters=gml_id,natcode,namefin,nameswe
+
+collections.nations.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_10k.gpkg
+collections.nations.table=Valtakunta
+collections.nations.title=Nations 2025
+collections.nations.parameters=gml_id,natcode,namefin,nameswe
+
+# 1:100k
+
+collections.municipalities_100k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_100k.gpkg
+collections.municipalities_100k.table=Kunta
+collections.municipalities_100k.title=Municipalities 2025, 1:100000
+collections.municipalities_100k.parameters=gml_id,natcode,namefin,nameswe,landarea,freshwarea,seawarea,totalarea
+
+collections.regions_100k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_100k.gpkg
+collections.regions_100k.table=Maakunta
+collections.regions_100k.title=Regions 2025, 1:100000
+collections.regions_100k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.regional_state_administrative_agencies_100k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_100k.gpkg
+collections.regional_state_administrative_agencies_100k.table=Aluehallintovirasto
+collections.regional_state_administrative_agencies_100k.title=Regional state administrative agencies 2025, 1:100000
+collections.regional_state_administrative_agencies_100k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.wellbeing_services_counties_100k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_100k.gpkg
+collections.wellbeing_services_counties_100k.table=Hyvinvointialue
+collections.wellbeing_services_counties_100k.title=Wellbeing Services Counties 2025, 1:100000
+collections.wellbeing_services_counties_100k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.nations_100k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_100k.gpkg
+collections.nations_100k.table=Valtakunta
+collections.nations_100k.title=Nations 2025, 1:100000
+collections.nations_100k.parameters=gml_id,natcode,namefin,nameswe
+
+# 1:250k
+
+collections.municipalities_250k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_250k.gpkg
+collections.municipalities_250k.table=Kunta
+collections.municipalities_250k.title=Municipalities 2025, 1:250000
+collections.municipalities_250k.parameters=gml_id,natcode,namefin,nameswe,landarea,freshwarea,seawarea,totalarea
+
+collections.regions_250k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_250k.gpkg
+collections.regions_250k.table=Maakunta
+collections.regions_250k.title=Regions 2025, 1:250000
+collections.regions_250k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.regional_state_administrative_agencies_250k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_250k.gpkg
+collections.regional_state_administrative_agencies_250k.table=Aluehallintovirasto
+collections.regional_state_administrative_agencies_250k.title=Regional state administrative agencies 2025, 1:250000
+collections.regional_state_administrative_agencies_250k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.wellbeing_services_counties_250k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_250k.gpkg
+collections.wellbeing_services_counties_250k.table=Hyvinvointialue
+collections.wellbeing_services_counties_250k.title=Wellbeing Services Counties 2025, 1:250000
+collections.wellbeing_services_counties_250k.parameters=gml_id,namefin,nameswe
+# Issue with natcode in this file existing in column "natcode       " and .parameters can't find it
+
+collections.nations_250k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_250k.gpkg
+collections.nations_250k.table=Valtakunta
+collections.nations_250k.title=Nations 2025, 1:250000
+collections.nations_250k.parameters=gml_id,natcode,namefin,nameswe
+
+# 1:1000k
+
+collections.municipalities_1000k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_1000k.gpkg
+collections.municipalities_1000k.table=Kunta
+collections.municipalities_1000k.title=Municipalities 2025, 1:1000000
+collections.municipalities_1000k.parameters=gml_id,natcode,namefin,nameswe,landarea,freshwarea,seawarea,totalarea
+
+collections.regions_1000k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_1000k.gpkg
+collections.regions_1000k.table=Maakunta
+collections.regions_1000k.title=Regions 2025, 1:1000000
+collections.regions_1000k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.regional_state_administrative_agencies_1000k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_1000k.gpkg
+collections.regional_state_administrative_agencies_1000k.table=Aluehallintovirasto
+collections.regional_state_administrative_agencies_1000k.title=Regional state administrative agencies 2025, 1:1000000
+collections.regional_state_administrative_agencies_1000k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.wellbeing_services_counties_1000k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_1000k.gpkg
+collections.wellbeing_services_counties_1000k.table=Hyvinvointialue
+collections.wellbeing_services_counties_1000k.title=Wellbeing Services Counties 2025, 1:1000000
+collections.wellbeing_services_counties_1000k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.nations_1000k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_1000k.gpkg
+collections.nations_1000k.table=Valtakunta
+collections.nations_1000k.title=Nations 2025, 1:1000000
+collections.nations_1000k.parameters=gml_id,natcode,namefin,nameswe
+
+# 1:4500k
+
+collections.municipalities_4500k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_4500k.gpkg
+collections.municipalities_4500k.table=Kunta
+collections.municipalities_4500k.title=Municipalities 2025, 1:4500000
+collections.municipalities_4500k.parameters=gml_id,natcode,namefin,nameswe,landarea,freshwarea,seawarea,totalarea
+
+collections.regions_4500k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_4500k.gpkg
+collections.regions_4500k.table=Maakunta
+collections.regions_4500k.title=Regions 2025, 1:4500000
+collections.regions_4500k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.regional_state_administrative_agencies_4500k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_4500k.gpkg
+collections.regional_state_administrative_agencies_4500k.table=Aluehallintovirasto
+collections.regional_state_administrative_agencies_4500k.title=Regional state administrative agencies 2025, 1:4500000
+collections.regional_state_administrative_agencies_4500k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.wellbeing_services_counties_4500k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_4500k.gpkg
+collections.wellbeing_services_counties_4500k.table=Hyvinvointialue
+collections.wellbeing_services_counties_4500k.title=Wellbeing Services Counties 2025, 1:4500000
+collections.wellbeing_services_counties_4500k.parameters=gml_id,natcode,namefin,nameswe
+
+collections.nations_4500k.db=SuomenHallinnollisetKuntajakopohjaisetAluejaot_2025_4500k.gpkg
+collections.nations_4500k.table=Valtakunta
+collections.nations_4500k.title=Nations 2025, 1:4500000
+collections.nations_4500k.parameters=gml_id,natcode,namefin,nameswe
+