pygeoapi: geodata publiceren als OGC API

pygeoapi is een serverimplementatie van de OGC API-standaarden, geschreven in Python. De documentatie omschrijft het doel zo:

pygeoapi is a Python server implementation of the OGC API suite of standards.

Bron: pygeoapi-documentatie, Introduction. Het project levert in één pakket meerdere API's. De ondersteuningstabel in de documentatie noemt OGC API - Features, Tiles en Environmental Data Retrieval als referentie-implementatie, Processes als compliant en Coverages, Maps en Records als implementing. Dat is de indeling van het project zelf; de documentatie verwijst voor de tests naar de CITE-instantie op demo.pygeoapi.io/cite. Sinds 15 januari 2024 is pygeoapi uit de OSGeo-incubatie afgestudeerd, volgens het projectoverzicht op osgeo.org. De standaarden waar het om gaat, staan uitgelegd bij WFS en OGC API Features.

pygeoapi past bij organisaties die al in Python werken en data die in een database, GeoPackage of bestand staat willen aanbieden volgens de nieuwe API-standaarden. Het vervangt geen viewer: een kaart voor eindgebruikers bouwt u er bovenop, bijvoorbeeld met MapLibre.

U installeert pygeoapi in een virtuele omgeving, schrijft een configuratiebestand, genereert het OpenAPI-document en start de server. Het voorbeeld hieronder is op 11 oktober 2026 gedraaid met pygeoapi 0.24.0 onder Python 3.13 en gebruikt de panden die de pagina over GDAL uit de PDOK BAG OGC API haalt, met -select identificatie,bouwjaar,status als GeoJSON in WGS84 (32 panden rond het Stationsplein in Amersfoort).

python3 -m venv pgv
./pgv/bin/pip install pygeoapi
export PYGEOAPI_CONFIG=$PWD/pygeoapi-config.yml
export PYGEOAPI_OPENAPI=$PWD/openapi.yml
./pgv/bin/pygeoapi openapi generate $PYGEOAPI_CONFIG --output-file $PYGEOAPI_OPENAPI
./pgv/bin/pygeoapi serve

Het configuratiebestand heeft vier delen: server, logging, metadata en resources. Hieronder staat de versie die in de test draaide; organisatie- en contactnaam zijn fictief. Laat license, provider en contact niet weg: zonder provider stopte pygeoapi openapi generate in de test met de foutmelding KeyError: 'provider'.

server:
  bind:
    host: 127.0.0.1
    port: 5000
  url: http://127.0.0.1:5000
  mimetype: application/json; charset=UTF-8
  encoding: utf-8
  languages:
    - nl-NL
    - en-US
  limits:
    default_items: 10
    max_items: 100
logging:
  level: ERROR
metadata:
  identification:
    title:
      nl: Panden Stationsplein Amersfoort (voorbeeld)
      en: Buildings Stationsplein Amersfoort (example)
    description:
      nl: Voorbeeldservice met BAG-panden uit PDOK
      en: Example service with BAG buildings from PDOK
    keywords:
      nl: [BAG, panden]
      en: [BAG, buildings]
    terms_of_service: https://creativecommons.org/publicdomain/zero/1.0/
    url: https://example.org
  license:
    name: CC0 1.0
    url: https://creativecommons.org/publicdomain/zero/1.0/
  provider:
    name: Voorbeeldorganisatie (fictief)
    url: https://example.org
  contact:
    name: Team geodata (fictief)
    email: geodata@example.org
resources:
  panden:
    type: collection
    title:
      nl: Panden
      en: Buildings
    description:
      nl: BAG-panden rond het Stationsplein in Amersfoort
      en: BAG buildings around Stationsplein Amersfoort
    keywords:
      nl: [BAG]
      en: [BAG]
    extents:
      spatial:
        bbox: [5.37, 52.15, 5.38, 52.16]
        crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84
    providers:
      - type: feature
        name: GeoJSON
        data: /pad/naar/panden.geojson
        id_field: identificatie

De server luistert in het voorbeeld alleen op 127.0.0.1. Dat is bewust: dit is de ontwikkelserver van Flask. Zet voor productie een applicatieserver en een omgekeerde proxy ervoor; de configuratie van url moet dan de publieke URL worden. De server die pygeoapi serve start is niet bedoeld voor publiek verkeer.

Na het opstarten beantwoordt de server de standaardpaden van OGC API Features. De volgende aanroepen zijn in de test uitgevoerd met curl en gaven statuscode 200:

Een attribuutfilter werkt dus door de veldnaam als queryparameter mee te geven, en bbox in de volgorde minlon,minlat,maxlon,maxlat. Het antwoord op een item-verzoek bevat numberMatched en numberReturned, die u kunt gebruiken om te pagineren. De parameter limit wordt begrensd door max_items in de configuratie.

Wie WFS gewend is, ziet dat deze URL's gewone paden zijn zonder REQUEST=GetFeature. Dat maakt de API eenvoudig te gebruiken vanuit JavaScript. Of een bestaande GIS-client OGC API Features kan lezen, hangt af van de client; QGIS en GDAL kunnen dit (zie QGIS).

pygeoapi regelt zelf geen toegang: u beveiligt de server met een laag erboven. De documentatie zegt het ronduit:

By design, pygeoapi does not have built-in support for access control.

Bron: pygeoapi-documentatie, Security. Dat is geen gebrek maar een ontwerpkeuze: open data heeft geen toegangscontrole nodig, en wie die wel nodig heeft, plaatst de server achter een gateway. De documentatie noemt de projecten fastgeoapi, pygeoapi-auth-deployment en pygeoapi-auth als beveiligingsframeworks voor pygeoapi.

Wat u in elk geval regelt, ook bij open data:

• Alleen-lezen databron. Geef de database-account van de provider alleen leesrechten. Een publieke API hoort geen schrijfrechten te hebben.
• Beperkte limieten. Stel max_items in zodat één verzoek niet de hele tabel levert.
• Omgekeerde proxy met TLS. De ontwikkelserver spreekt geen HTTPS; laat Nginx of een gelijkwaardige proxy dat doen, met rate limiting.
• Geen persoonsgegevens. Controleer welke attributen u publiceert. Adresgegevens uit de BAG zijn open, maar gegevens over bewoners zijn dat niet; zie geodata en de AVG.

Voor het inrichten van zo'n publicatieketen bij een gemeente, met metadata en vindbaarheid, zie open data publiceren als gemeente en open data-platform.

De valkuilen zitten in de configuratie en in de verwachtingen. De volgende punten komen uit de test of uit de documentatie.

• OpenAPI-document opnieuw genereren. Na elke wijziging in resources genereert u het OpenAPI-document opnieuw met pygeoapi openapi generate. Anders loopt de documentatie achter op wat de server aanbiedt.
• Coördinatenstelsel. Het GeoJSON-voorbeeld staat in WGS84. Wie data in RD (EPSG:28992) aanbiedt, moet de CRS in de configuratie en in de metadata kloppend vermelden en nagaan of de provider RD ondersteunt. Zet bij twijfel de data vooraf om met GDAL.
• Het GeoJSON-bestand is geen database. Het voorbeeld leest een bestand van 32 features. Voor grote tabellen kiest u een databaseprovider, zoals de PostgreSQL/PostGIS-provider uit de lijst van de documentatie; zie PostGIS.
• id_field moet uniek zijn. Zonder eenduidig id werkt het ophalen van één feature niet betrouwbaar. In het voorbeeld is dat identificatie uit de BAG.
• Versie 0.x. Het versienummer begint met nul. Lees de releasenotes voordat u updatet en pin de versie in uw omgeving.
• Poort 5000 op macOS. Op de testmachine luisterde de macOS-systeemdienst ControlCenter (AirPlay-ontvanger) al op *:5000. Een verzoek dat binnenkwam voordat pygeoapi draaide, kreeg daardoor een 403 van een andere server. Kies bij twijfel een andere poort in bind én url.

De kolommen van GeoServer en QGIS Server tonen alleen wat op de eigen pagina's van deze site is vastgelegd. De afweging per product staat daar.

Kies iets anders als uw afnemers WMS-lagen of een bestaand GIS-systeem met WMS en WMTS nodig hebben: daarvoor is een server als GeoServer of QGIS Server beter geschikt, omdat die kaartbeelden renderen. pygeoapi levert vooral features en data. Kies ook iets anders als u gebruikersbeheer binnen de server nodig hebt, of als u geen Python-kennis in huis hebt voor beheer.

Gaat het om een volledig dataplatform met catalogus en metadata, dan is een catalogus als CKAN de partij die datasets vindbaar maakt; pygeoapi levert dan de API's onder die datasets. Het samenspel staat beschreven bij dataplatforms. De standaard waaraan de overheid in Nederland zich houdt voor API's is NL API Design Rules; toets uw publicatie daaraan voordat u hem als officiële dienst aanbiedt.