WFS/WMS-Datensatz anlegen per API¶

Dieser Guide beschreibt, wie ein Datensatz mit WFS- und WMS-Distributionen über die ODI-API angelegt wird. Der Datensatz wird im DCAT-AP.de-Standard angelegt, der als Metadatenprofil für offene Verwaltungsdaten in Deutschland gilt.

Der Ablauf gliedert sich in drei Schritte: Token abrufen → Datensatz anlegen → Distributionen (WFS/WMS) hinzufügen.

Was ist eine Distribution? Laut dem DCAT-AP ist eine Distribution „eine physische Verkörperung bzw. Repräsentation des Datensatzes in einem bestimmten Format" – sie beschreibt also, wie und wo die Daten abgerufen werden können. Eine Distribution kann z. B. eine herunterladbare Datei (CSV, JSON, …) oder ein Verweis/Link auf einen externen Dienst (wie in diesem Beispiel) sein. Ein Datensatz kann mehrere Distributionen enthalten.

Umgebungen

Alle Requests in diesem Guide sind für beide Umgebungen verfügbar. Wähle die passende Umgebung über die Tabs bei den Beispiel-Requests aus. Die Zugangsdaten (Client-ID, Client-Secret) sind umgebungsspezifisch und werden vom ODI-Team bereitgestellt.

ProduktionTest

API-Dokumentation

Swagger-UI: https://ckan-service.odi.schleswig-holstein.de/docs

API-Dokumentation

Swagger-UI: https://ckan-service.staging.frostcluster.da23.dsecurecloud.de/docs

Voraussetzungen¶

Client-ID und Client-Secret eines Keycloak Service Accounts liegen vor
WFS- und/oder WMS-URL ist bekannt und erreichbar
Metadaten sind bekannt (siehe Metadaten-IDs abrufen):
- Katalog-Name (catalogue), z. B. opendata-sh
- Lizenz-ID (licenseId), z. B. http://dcat-ap.de/def/licenses/cc-zero
- Publisher-ID (publisherId), z. B. lfu
- Kategorie-IDs (categoryIds), z. B. ["ener", "envi"]
- Raumbezug-ID (spatialReferenceId), z. B. http://dcat-ap.de/def/politicalGeocoding/stateKey/01

Vorgehen¶

1. Token abrufen¶

Eine Anleitung zum Abrufen eines gültigen JWT-Tokens findet sich unter Token abrufen.

2. Metadaten-IDs abrufen¶

Mehrere Pflichtfelder des Requests referenzieren Objekte, die im Metadaten-Service verwaltet werden. Eine Übersicht aller verfügbaren IDs und Endpunkte ist unter Metadaten-IDs abrufen zu finden.

Häufig verwendete Werte:

Feld	Wert	Kommentar
`catalogue`	`opendata-sh`
`licenseId`	`http://dcat-ap.de/def/licenses/cc-zero`	Creative Commons CC Zero
`spatialReferenceId`	`http://dcat-ap.de/def/politicalGeocoding/stateKey/01`	Bundesland Schleswig-Holstein
`categoryIds`	`["envi", "tran", "ener", "gove"]`	Umwelt, Verkehr, Energie, Regierung und öffentlicher Sektor

3. Datensatz anlegen¶

Ein neuer Datensatz wird ohne Dateiinhalt angelegt. Er enthält ausschließlich Metadaten und erhält die WFS- und WMS-URLs im nächsten Schritt als Distributionen.

Endpunkt¶

ProduktionTest

POST https://ckan-service.odi.schleswig-holstein.de/dataset/{catalogue}

POST https://ckan-service.staging.frostcluster.da23.dsecurecloud.de/dataset/{catalogue}

Felder¶

Feld	Pflicht	Typ	Beschreibung	Quelle
`datasetId`	Pflicht	string	Frei wählbare ID des Datensatzes	frei wählbar
`title`	Pflicht	JSON-Objekt	Titel des Datensatzes (mehrsprachig)	frei wählbar
`description`	Pflicht	JSON-Objekt	Beschreibung des Datensatzes (mehrsprachig)	frei wählbar
`publisherId`	Pflicht	string	ID des Herausgebers	Metadaten-Service `/publisher`
`categoryIds`	Pflicht	string[]	Array der Kategorie-IDs	Metadaten-Service `/categories`
`licenseId`	Pflicht	string	ID der Lizenz	Metadaten-Service `/licenses`
`spatialReferenceId`	Pflicht	string	ID des Raumbezugs	Metadaten-Service `/places`
`startDate`	Pflicht	string	Startdatum des Datensatz-Zeitraums im ISO-8601-Format (z. B. `2025-01-01T00:00:00`)	bekannt
`endDate`	Optional	string	Enddatum des Datensatz-Zeitraums im ISO-8601-Format (z. B. `2026-01-01T00:00:00`)	–
`issuedBy`	Optional	string	Dienst oder Nutzer, der den Datensatz angelegt hat	frei wählbar
`publish`	Optional	string	`"true"` = sofort veröffentlichen; fehlt = Draft	–

Info

title und description sind mehrsprachige JSON-Objekte, z. B.: {"de": "Windkraftanlagen", "en": "Wind turbines"} Mindestens ein Sprachwert (de oder en) ist erforderlich.

Beispiel-Request¶

Der access_token wird im Abschnitt Token abrufen ermittelt.

ProduktionTest

curl --request POST \
  --url https://ckan-service.odi.schleswig-holstein.de/dataset/opendata-sh \
  --header 'authorization: Bearer <access_token>' \
  --header 'content-type: application/json' \
  --data '{
    "datasetId": "windkraftanlagen-2026-05-01",
    "title": {
      "de": "Windkraftanlagen"
    },
    "description": {
      "de": "Dieser Datensatz enthält Daten und Standorte von genehmigungspflichtigen Windkraftanlagen in Schleswig-Holstein. Im Landesportal sind weitere Informationen zum Thema Windenergie zu finden."
    },
    "publisherId": "lfu",
    "categoryIds": ["ener", "envi"],
    "licenseId": "http://dcat-ap.de/def/licenses/cc-zero",
    "spatialReferenceId": "http://dcat-ap.de/def/politicalGeocoding/stateKey/01",
    "startDate": "2025-01-01T00:00:00",
    "endDate": "2026-01-01T00:00:00",
    "issuedBy": "ODI-Api-Examples",
    "publish": "true"
  }'

curl --request POST \
  --url https://ckan-service.staging.frostcluster.da23.dsecurecloud.de/dataset/opendata-sh \
  --header 'authorization: Bearer <access_token>' \
  --header 'content-type: application/json' \
  --data '{
    "datasetId": "windkraftanlagen-2026-05-01",
    "title": {
      "de": "Windkraftanlagen"
    },
    "description": {
      "de": "Dieser Datensatz enthält Daten und Standorte von genehmigungspflichtigen Windkraftanlagen in Schleswig-Holstein. Im Landesportal sind weitere Informationen zum Thema Windenergie zu finden."
    },
    "publisherId": "lfu",
    "categoryIds": ["ener", "envi"],
    "licenseId": "http://dcat-ap.de/def/licenses/cc-zero",
    "spatialReferenceId": "http://dcat-ap.de/def/politicalGeocoding/stateKey/01",
    "startDate": "2025-01-01T00:00:00",
    "endDate": "2026-01-01T00:00:00",
    "issuedBy": "ODI-Api-Examples",
    "publish": "true"
  }'

Beispiel-Response (Erfolg)¶

{
  "datasetId": "windkraftanlagen-2026-05-01",
  "catalogue": "opendata-sh",
  "distributionIds": [],
  "modifiedDate": "2026-05-27T08:11:31.378281",
  "issuedDate": "2026-05-27T08:11:30.146000+00:00",
  "datasetUrl": "https://opendata.schleswig-holstein.de/dataset/windkraftanlagen-2026-05-01"
}

Fehlercodes¶

HTTP-Status	Bedeutung	Mögliche Ursache / Lösung
400	Ungültige Anfrage	Pflichtfeld fehlt oder falsches Format
401	Nicht authentifiziert	Token fehlt oder abgelaufen → neuen Token abrufen
403	Keine Berechtigung	Service Account hat nicht die erforderliche Rolle
500	Interner Serverfehler	Kontakt zum ODI-Support aufnehmen

4. WFS-Distribution hinzufügen¶

Nach dem Anlegen des Datensatzes wird die WFS-URL als Distribution angehängt.

Endpunkt¶

ProduktionTest

POST https://ckan-service.odi.schleswig-holstein.de/distribution/{catalogue}/{datasetId}/link-to

POST https://ckan-service.staging.frostcluster.da23.dsecurecloud.de/distribution/{catalogue}/{datasetId}/link-to

Felder¶

Feld	Pflicht	Typ	Beschreibung
`format`	Pflicht	string	Format-Kenner der Distribution; für WFS: `WFS_SRVC`
`licenseId`	Pflicht	string	ID der Lizenz
`title`	Pflicht	JSON-Objekt	Titel der Distribution (mehrsprachig)
`description`	Pflicht	JSON-Objekt	Beschreibung der Distribution (mehrsprachig)
`url`	Pflicht	string	URL zum WFS GetCapabilities-Request

Beispiel-Request¶

ProduktionTest

curl --request POST \
  --url https://ckan-service.odi.schleswig-holstein.de/distribution/opendata-sh/windkraftanlagen-2026-05-01/link-to \
  --header 'authorization: Bearer <access_token>' \
  --header 'content-type: application/json' \
  --data '{
    "format": "WFS_SRVC",
    "licenseId": "http://dcat-ap.de/def/licenses/cc-zero",
    "title": {
      "de": "WFS"
    },
    "description": {
      "de": "Web Feature Service zum Abrufen von Geodaten."
    },
    "url": "https://geoserver.odi.schleswig-holstein.de/geoserver/windkraftanlagen_2026_02_12/ows?service=WFS&version=2.0.0&request=GetCapabilities"
  }'

curl --request POST \
  --url https://ckan-service.staging.frostcluster.da23.dsecurecloud.de/distribution/opendata-sh/windkraftanlagen-2026-05-01/link-to \
  --header 'authorization: Bearer <access_token>' \
  --header 'content-type: application/json' \
  --data '{
    "format": "WFS_SRVC",
    "licenseId": "http://dcat-ap.de/def/licenses/cc-zero",
    "title": {
      "de": "WFS"
    },
    "description": {
      "de": "Web Feature Service zum Abrufen von Geodaten."
    },
    "url": "https://geoserver.odi.schleswig-holstein.de/geoserver/windkraftanlagen_2026_02_12/ows?service=WFS&version=2.0.0&request=GetCapabilities"
  }'

Fehlercodes¶

HTTP-Status	Bedeutung	Mögliche Ursache / Lösung
400	Ungültige Anfrage	Pflichtfeld fehlt oder ungültige URL
401	Nicht authentifiziert	Token fehlt oder abgelaufen → neuen Token abrufen
403	Keine Berechtigung	Service Account hat nicht die erforderliche Rolle
404	Datensatz nicht gefunden	`datasetId` oder `catalogue` prüfen
500	Interner Serverfehler	Kontakt zum ODI-Support aufnehmen

5. WMS-Distribution hinzufügen¶

Analog zur WFS-Distribution wird die WMS-URL als weitere Distribution angehängt.

Endpunkt¶

ProduktionTest

POST https://ckan-service.odi.schleswig-holstein.de/distribution/{catalogue}/{datasetId}/link-to

POST https://ckan-service.staging.frostcluster.da23.dsecurecloud.de/distribution/{catalogue}/{datasetId}/link-to

Felder¶

Feld	Pflicht	Typ	Beschreibung
`format`	Pflicht	string	Format-Kenner der Distribution; für WMS: `WMS_SRVC`
`licenseId`	Pflicht	string	ID der Lizenz
`title`	Pflicht	JSON-Objekt	Titel der Distribution (mehrsprachig)
`description`	Pflicht	JSON-Objekt	Beschreibung der Distribution (mehrsprachig)
`url`	Pflicht	string	URL zum WMS GetCapabilities-Request

Beispiel-Request¶

ProduktionTest

curl --request POST \
  --url https://ckan-service.odi.schleswig-holstein.de/distribution/opendata-sh/windkraftanlagen-2026-05-01/link-to \
  --header 'authorization: Bearer <access_token>' \
  --header 'content-type: application/json' \
  --data '{
    "format": "WMS_SRVC",
    "licenseId": "http://dcat-ap.de/def/licenses/cc-zero",
    "title": {
      "de": "WMS"
    },
    "description": {
      "de": "Web Map Service zum Abrufen von Geodaten."
    },
    "url": "https://geoserver.odi.schleswig-holstein.de/geoserver/windkraftanlagen_2026_02_12/ows?service=WMS&version=2.0.0&request=GetCapabilities"
  }'

curl --request POST \
  --url https://ckan-service.staging.frostcluster.da23.dsecurecloud.de/distribution/opendata-sh/windkraftanlagen-2026-05-01/link-to \
  --header 'authorization: Bearer <access_token>' \
  --header 'content-type: application/json' \
  --data '{
    "format": "WMS_SRVC",
    "licenseId": "http://dcat-ap.de/def/licenses/cc-zero",
    "title": {
      "de": "WMS"
    },
    "description": {
      "de": "Web Map Service zum Abrufen von Geodaten."
    },
    "url": "https://geoserver.odi.schleswig-holstein.de/geoserver/windkraftanlagen_2026_02_12/ows?service=WMS&version=2.0.0&request=GetCapabilities"
  }'

Fehlercodes¶

HTTP-Status	Bedeutung	Mögliche Ursache / Lösung
400	Ungültige Anfrage	Pflichtfeld fehlt oder ungültige URL
401	Nicht authentifiziert	Token fehlt oder abgelaufen → neuen Token abrufen
403	Keine Berechtigung	Service Account hat nicht die erforderliche Rolle
404	Datensatz nicht gefunden	`datasetId` oder `catalogue` prüfen
500	Interner Serverfehler	Kontakt zum ODI-Support aufnehmen

6. Datensatz löschen (optional)¶

Ein Datensatz kann per API gelöscht werden. Ohne den Parameter purge wird der Datensatz nur als gelöscht markiert (Soft Delete) und kann wiederhergestellt werden. Mit purge=true wird der Datensatz dauerhaft gelöscht und die datasetId wird für eine Wiederverwendung freigegeben.

Endpunkt¶

ProduktionTest

DELETE https://ckan-service.odi.schleswig-holstein.de/dataset/{datasetId}

DELETE https://ckan-service.staging.frostcluster.da23.dsecurecloud.de/dataset/{datasetId}

Query-Parameter¶

Parameter	Pflicht	Typ	Beschreibung
`purge`	Optional	boolean	`true` = dauerhaft löschen (Hard Delete); fehlt oder `false` = Soft Delete

Beispiel-Request¶

ProduktionTest

curl --request DELETE \
  --url 'https://ckan-service.odi.schleswig-holstein.de/dataset/windkraftanlagen-2026-05-01?purge=true' \
  --header 'authorization: Bearer <access_token>'

curl --request DELETE \
  --url 'https://ckan-service.staging.frostcluster.da23.dsecurecloud.de/dataset/windkraftanlagen-2026-05-01?purge=true' \
  --header 'authorization: Bearer <access_token>'

Fehlercodes¶

HTTP-Status	Bedeutung	Mögliche Ursache / Lösung
204	Erfolgreich gelöscht	–
401	Nicht authentifiziert	Token fehlt oder abgelaufen → neuen Token abrufen
403	Keine Berechtigung	Service Account hat nicht die erforderliche Rolle
404	Datensatz nicht gefunden	`datasetId` prüfen

Nächste Schritte¶

Für weiterführende Operationen – z. B. das Aktualisieren von Datensatz-Metadaten oder das Ersetzen einer Distribution – steht die vollständige API-Referenz des CKAN-Service zur Verfügung:

CKAN-Adapter API → API Referenz