Denne side er en guide til hvordan du som anvender kan bruge Datafordelerens entitetsbaserede WFS-tjenester.

Indledning

Datafordeleren tilbyder Web Feature Service (WFS)-tjenester til distribution af geografiske vektordata fra danske registre. WFS er en international OGC-standard, der muliggør struktureret udveksling af geodata mellem systemer og GIS-applikationer.

Datafordeleren udstiller entitetsbaserede WFS-tjenester, som er automatisk genererede baseret direkte på registrenes datamodeller. Tjenesterne følger OGC WFS 2.0.0 standarden. Denne guide fokuserer på hvordan disse tjenester anvendes i praksis.

Yderligere information om WFS og GeoServer kan findes på:

• WFS: Web Feature Service (WFS) Standard | OGC Publications
• GeoServer: GeoServer

Begreber

På denne side bruges begreberne nedenfor. Bemærk at begreberne også er yderligere forklaret i løbet af dokumentet med eksempler.

Om entitetsbaserede WFS-tjenester

Entitetsbaserede WFS-tjenester repræsenterer en automatiseret tilgang til at eksponere geodata, hvor hver tabel i et registers datamodel bliver direkte tilgængelig som et WFS-lag gennem en standardiseret proces. Dette koncept bygger på OGCs WFS 2.0.0 standard, men implementerer en én-til-én mapping mellem databasetabeller og WFS FeatureTypes.

Grundprincippet er at data eksponeres præcis som det ligger i registrenes databaser - uden forudgående filtrering, aggregering eller transformation. Hver entitet i datamodellen bliver automatisk et tilgængeligt lag i WFS-tjenesten. Dette betyder at hvis et register har en tabel kaldet "bygning", vil denne automatisk blive eksponeret som et lag kaldet "bygning_current" for aktuelle data og "bygning_hist" for historiske data.

Tilgangen inkluderer både entiteter med og uden geospatiale data. Dette betyder at selv administrative tabeller som Matriklens Jordstykke-entitet, der ikke indeholder geospatiale data, bliver tilgængelige gennem den samme standardiserede WFS-grænseflade med geometry-feltet sat til null.

Forskelle fra traditionelle/sammenstillede WFS-tjenester

Datafordeleren tilbyder to forskellige tilgange til WFS-tjenester:

1. Sammenstillede WFS-tjenester: De eksisterende WFS-tjenester, som er migreret fra Snowflake GoPublisher til GeoServer-platformen. Disse tjenester er manuelt konfigurerede med specifikke lag, visninger og attributmappings optimeret til bestemte anvendelsesformål. Eksempler inkluderer DAGI Multigeometri, DHM Højdekurver, Fikspunkter og GeoDanmark Vektor tjenesterne. Disse tjenester leverer data gennem foruddefinerede lag med udvalgte felter og strukturer.
2. Entitetsbaserede WFS-tjenester: Automatisk genererede tjenester hvor hver tabel i registrenes datamodel bliver direkte tilgængelig som et WFS-lag. Alle felter i databasetabellen bliver til attributter i WFS-laget med identiske navne og datatyper. For entiteter med bitemporal datamodel tilbydes både aktuelle data (_current) og komplet historisk sporbarhed (_hist). Denne tilgang kræver ingen manuel konfiguration og opdateres automatisk når datamodellerne ændres.

Begge typer kører på GeoServer og følger OGC WFS 2.0.0 standarden. Denne guide fokuserer på entitetsbaserede WFS-tjenester.

Udstilling af WFS-tjenester

WFS-tjenesterne udstilles gennem URL'er, der følger formen:

<register> er forkortelsen for det register anvenderen forsøger at hente data fra, <register>_WFS er servicenavnet der følger et fast mønster, <version> er versionen af tjenesten for det pågældende register (aktuelt 1.0.0 for alle initiale services) og <query-parametre> er de forskellige parametre hver tjeneste kan tage. Parametrene er yderligere beskrevet i afsnit 2.3, 2.4, 2.5 og 2.6 og versionering beskrives i afsnit 2.7.2.2.

De registre, der udstiller én eller flere entiteter gennem de entitetsbaserede WFS-tjenester, er vist i Tabel 3 nedenfor. Bemærk at et register kan vælge, hvilke entiteter de ønsker udstillet gennem tjenesterne, og at det derfor ikke nødvendigvis er alle entiteter i et register der kan tilgås gennem disse tjenester.

Nogle registre har data opdelt i flere logiske enheder kaldet replikeringskanaler. For eksempel har DHM separate kanaler for Højdekurver og Oprindelse. Disse eksponeres som separate WFS-services med hver deres URL som vist i tabellen ovenfor.

Standardparametre

Alle WFS-forespørgsler består af en base-URL og påkrævede query-parametre. Base-URL'en følger strukturen:

Query-parametrene inkluderer tre standard OGC-parametre (service-type, protokolversion og ønsket funktion) samt autentifikation. Disse parametre skal altid inkluderes som query-parametre for at få et gyldigt svar fra tjenesten.

Følgende query-parametre skal altid angives ved WFS forespørgsler:

Det er vigtigt at skelne mellem to forskellige versionsnumre i WFS-forespørgsler. Service-versionen i URL'en (f.eks. /1.0.0/) angiver version af servicen, mens WFS-protokol-versionen i parametrene (version=2.0.0) angiver versionen af WFS-standarden. WFS-protokol-versionen skal altid være 2.0.0, uanset hvilken serviceversion der tilgås.

I eksemplet nedenfor bruges:

• Register: BBR
• Service version: 1.0.0
• OGC parametre
  • Service: WFS
  • WFS-protokol-version: 2.0.0
  • Metode: GetFeature
• Entitet_bitemporalitet: Bygning_current

Som vist i eksemplet ovenfor, indeholder URL'en både service-versionen (1.0.0) og WFS-protokol-versionen (2.0.0) på forskellige steder.

WFS-Metoder

WFS-tjenesterne understøtter standard OGC-metoder der giver mulighed for at opdage tilgængelige data, forstå datastrukturen og hente de faktiske geografiske features. Hver metode har et specifikt formål i arbejdet med geografiske data.

For yderligere information om WFS-metoder, GeoServer WFS Reference: GeoServer's officielle dokumentation.

GetCapabilities

GetCapabilities-metoder bruges til at hente oplysning om de tilgængelige lag der er i en WFS-tjeneste samt hvilke metoder og formater der understøttes for disse lag. Dette er typisk det første kald man laver til en ny WFS-tjeneste for at forstå hvad der er tilgængeligt. GetCapabilities kan kaldes med ingen yderligere parametre end de standardparametre beskrevet i Tabel 4.

Eksempel:

Kald til GetCapabilities returnerer et længere XML-dokument der beskriver de pågældende tjenester. Kaldet returner blandt andet metadata om:

• Understøttede outputformater (GML, GeoJSON)
• Geografisk udstrækning for hvert lag
• Maksimalt antal features der kan returneres (10.000)
• Understøttede koordinatsystemer (EPSG:25832 som standard)

Læs mere om GeoServer GetCapabilities i GeoServer dokumentationen.

DescribeFeatureType

DescribeFeatureType-metode returnerer den detaljerede struktur i form af et skema for et lag. Dette bruges til at forstå, hvilke attributter der er tilgængelige, deres datatyper og eventuelle begrænsninger. GIS-software bruger ofte denne metode automatisk for at konfigurere attributtabeller korrekt. DescribeFeatureType bruger de samme standardparametre som beskrevet i  Tabel 4 (service, version, request, apikey) plus følgende yderligere parameter beskrevet i Tabel 6 for at specificere hvilken entitet du vil se strukturen for.

For entitetsbaserede tjenester følger lagnavnene mønsteret {entitet}_{bitemporalitet} hvor entitet er bygning, tekniskanlaeg, adresse osv., og bitemporalitet er enten current (aktuelle data) eller hist (historiske data). Eksempler: bygning_current, tekniskanlaeg_hist, adresse_current.

Brug af typeName-parameteren:

• Uden typeName: Henter skemaer for alle tilgængelige lag samtidig - nyttigt for at få komplet overblik over servicens datamodel
• Med typeName: Henter kun skema for det specifikke lag - hurtigere og mere fokuseret når du ved præcis hvilket lag du skal arbejde med

For at kunne finde en korrekte typeName-værdier

1. Kald GetCapabilities for at se alle tilgængelige lag, for eksempel:

2. Find lagnavne i FeatureTypeList i GetCapabilities-responset:

3. Brug lagnavnet direkte som vist i FeatureTypeList <Title>, eks. bygning_current eller bygning_hist og du vil modtage den detaljerede struktur, du anmodede om

DescribeFeatureType eksempel med bygning_current:

Læs mere om DescribeFeatureType i GeoServer dokumentationen.

GetFeature

GetFeature-metode bruges til at hente de faktiske geografiske data. Dette er den primære metode når man skal arbejde med data i GIS-software eller lave analyser. GetFeature understøtter forskellige filtrerings- og udvælgelsesmuligheder gennem query-parametre. Alle inputparametre for GetFeature findes i følgende tabel:

GetFeature understøtter flere avancerede query-muligheder, såsom:

• Paging: Via startIndex- og count-parameteren
• Sortering: Via sortBy-parameteren
• Attribut-selektion: Via propertyName-parameteren
• Geometrisk filtrering: Via bbox-parameteren eller CQL geometriske operatorer
• Attribut-filtrering: Via cql_filter-parameteren

Eksempel:

Læs mere om GetFeature og alle query-muligheder i GeoServer dokumentationen.

For en mere detaljeret beskrivelse af brugen af bbox- og cql_filter-parameteren, se afsnit 2.7.

Outputformater

WFS-tjenesterne understøtter to standard-outputformater der dækker forskellige anvendelsesbehov. Valg af format afhænger af hvilken type applikation eller GIS-software der skal forbruge data.

Outputformat specificeres via outputFormat-parameteren i GetFeature- og DescribeFeatureType-forespørgsler. Hvis ingen outputFormat-parameter angives, returneres data i henholdsvis GML format som standard for GetFeature, og som XSD-skema som standard for DescribeFeatureType.

For GetFeature returneres geografiske data i det valgte format (GML eller GeoJSON). For DescribeFeatureType returneres strukturbeskrivelsen enten som XSD-skema (standard) eller som JSON-skema når outputFormat=application/json specificeres.

GetCapabilities-metoden understøtter ikke outputFormat-parameteren og returnerer altid XML uanset hvilken værdi der angives.

Valg af format

GML bør vælges når:

• Data skal bruges i desktop GIS-software som eksempelvis QGIS eller ArcGIS
• Fuld OGC-compliance er påkrævet
• Data skal arkiveres eller udveksles mellem offentlige systemer
• Maksimal præcision og metadata er vigtig

GeoJSON bør vælges når:

• Data skal bruges i webapplikationer eller JavaScript
• Integration med moderne REST APIs
• Filstørrelse er en begrænsning (GeoJSON er typisk 20-30% mindre)
• Hurtig parsing og simpel datastruktur er prioriteret

For yderligere information om output formater i GeoServer se: WFS output formats

Bitemporalitet

Entitetsbaserede WFS-tjenester håndterer bitemporal data gennem separate lag for aktuelle og historiske data. Alle entiteter med bitemporal datamodel eksponeres i to varianter, identificeret gennem endelsen på lagnavnet:

• _current: Viser kun aktuelt gyldige data
• _hist: Viser komplet bitemporal historik med alle versioner over tid

Det aktuelle lag, for eksempel bygning_current, returnerer kun features der er gyldige på nuværende tidspunkt. Dvs. de underliggende data filtreres automatisk på både virkningstid og registreringstid for at vise det aktuelle billede af data.

Det historiske lag, for eksempel bygning_hist, returnerer alle versioner af hver feature gennem tiden, inklusive både aktuelle og historiske versioner. Dette giver mulighed for at analysere hvordan data har ændret sig over tid. Det historiske lag giver mulighed for at filtrere på de bitemporale felter for at finde gyldige data i specifikke tidsperioder. De relevante felter er:

• registreringFra / registreringTil: Hvornår data blev registreret i systemet
• virkningFra / virkningTil: Hvornår data er/ var gyldigt i virkeligheden

Man kan filtrere på disse felter ved brug af cql_filter-parameteren, som er beskrevet i afsnit 2.7.2.1.

For yderligere information om se Bitemporalitet på Datafordeleren.

Filtrering

De entitetsbaserede WFS-tjenester understøtter både attribut- og geometrisk filtrering når data hentes ved brug af GetFeature-metoden beskrevet i afsnit 2.4.3. Man kan filtrere på baggrund af udvalgte attributter ved brug af cql_filter-parameteren mens filtrering på baggrund af geospatial data kan gøres på en af to måder: ved brug af enten bbox- eller cql_filter-parameteren. Parametrene kan ikke benyttes samtidig. Brug af bbox-parameteren er beskrevet i afsnit 2.7.1, mens brug af cql_filter-parameteren er beskrevet i afsnit 2.7.2 nedenfor.

Filtrering med bbox

bbox-parameteren gør det muligt at søge efter features, der er indeholdt (eller delvist indeholdt) inden for en såkaldt bounding box. En bounding box er en rektangulær, geografisk afgrænsning, som angiver det område indenfor hvilket, der returneres features til anvenderen. Bounding box’en er defineret ved angivelse af to sæt af koordinater, som alle skal være inden for EPSG-25832 grænserne. Nedenfor er vist et eksempel på en bounding box for koordinaterne bbox=721148,617549,722618,6176355

Med hensyn til hvilke hjørner af afgrænsningsboksen der skal angives, er det eneste krav, at et af de nederste hjørner (venstre eller højre) angives først. For eksempel nederste venstre og øverste højre, eller nederste højre og øverste venstre. I Figur 6 svarer koordinaterne (minX, minY) til nederst venstre og (maxX, maxY) til øverste højre. Man ville således få samme bounding box ved at angive koordinaterne maxX, minY og minX, maxY, hvilket svarer til nederste højre og øverste venstre hjørne.

Hvis man for eksempel vil finde tekniske anlæg inden for bounding box’en ovenfor, kan man benytte bbox-parameteren til at lave en filtrering på tekniskanlaeg_current-laget. Dette kan gøres ved følgende kald:

Kaldet returnerer en lang XML-fil med følgende data:

Filtrering med cql_filter

cql_filter-parameteren tilbyder en avanceret og fleksibel metode til at filtrere de features, der returneres fra en WFS-tjeneste. I modsætning til den simple bbox-filtrering, giver cql_filter mulighed for at formulere komplekse forespørgsler baseret på både attribut- og geospatiale data. Filtret skrives ved hjælp af OGC's Common Query Language (CQL).

Du kan læse mere om CQL og hvordan det kan bruges i GeoServers CQL Tutorial og dokumentation for ECQL.

Attributfiltrering

Attributfiltrering giver mulighed for at udvælge features baseret på deres attributværdier, såsom tekststrenge, tal eller datoer. Filtret opbygges typisk som attribut-operator-værdi. Følgende operatorer understøttes:

Hvis man for eksempel vil finde tekniske anlæg der var gyldige pr. 1. januar 2023, kan man benytte cql_filter til at lave bitemporal filtrering på tekniskanlaeg_hist-laget. Dette kan gøres ved følgende kald:

I dette kald skal cql_filter-filtrene læses således:

• Returnerer kun data der var gyldigt den 1. januar 2023 eller før (virkningFra <= '2023-01-01').
• Returnerer kun data der stadig er gyldigt (virkningTil IS NULL) eller (OR) som var gyldigt indtil efter 1. januar 2023 (virkningTil > '2023-01-01')
• Returnerer kun data der har en registrering der stadig er gyldig (registreringTil IS NULL)

Som vist i kaldet ovenfor, kombineres de forskellige filtre ved hjælp af AND/OR-operatorer.

Bemærk at outputFormat-parameteren er sat til json, hvorfor kaldet returnerer en lang json-fil med følgende data:

Geometrisk filtrering

Udover attributfiltrering kan cql_filter også bruges til at filtrere features på baggrund af geospatiale data. Dette gøres i form af WKT-strenge (Well Known Text) som gives som input gennem cql_filter-parameteren. Disse WKT'er repræsenterer geospatiale data, enten i form af en koordinattype, en geometri-type eller lignende datatyper.

De mest almindelige typer af geometriske former er punkter, linjer og polygoner. Et punkt repræsenteres af et koordinatsæt med to eller tre værdier, afhængigt af om det er et punkt i to eller tre dimensioner. En linje repræsenteres af en liste af de punkter, der udgør linjen. En polygon repræsenteres af en liste de punkter, der udgør hjørnerne af polygonen, hvor første og sidste punkt i listen er identisk. Et eksempel på WKT-formatet for hver af de tre geometrityper i 2D, er vist nedenfor:

De entitetsbaserede WFS-tjenester understøtter en række forskellige geometriske operatorer. Alle operatorerne fremgår af Tabel  10: . Kombinationer af geometriske operatorer understøttes ved hjælp af tilhørende AND/OR-operatorer.

Nedenfor er vist et eksempel på en WKT-geometri: POLYGON ((563436.97 6257781.63, 563505.88 6257908.45, 563623.98 6257788.20, 563472.62 6257744.47, 563436.97 6257781.63))

I dette eksempel bruges tek109Koordinat, som er geometrifeltet for tekniske anlæg (som vist i JSON-responset i afsnit 2.7.2.1). Hvis man for eksempel vil finde alle tekniske anlæg, hvor geometrien tek109Koordinat er indeholdt i polygonen oven for, kan man benytte WITHIN-operatorer til at lave en filtrering på tekniskanlaeg_current-laget. Dette kan gøres ved følgende kald:

Kaldet returnerer en lang XML-fil med følgende data:

Versionering

I de entitetsbaserede WFS-tjenester versioneres hvert register separat, og alle entiteter, der tilhører det samme register, versioneres under det samme versionsnummer som registret. Det vil sige, at DAR og BBR kan eksistere separat som DAR_WFS/1.0.0 og BBR_WFS/2.0.0. Men hvis BBR har en ændring til Bygning-entiteten i deres datamodel, vil alle entiteter i BBR blive opgraderet til BBR_WFS/3.0.0, og BBR_WFS/2.0.0 vil derefter efter en overgangsperiode blive udfaset.