pygeoapi: publique su primera OGC API con datos de prueba

Construya una API local OGC API Features con dos estaciones ficticias, una colección descubrible y URLs estables por objeto. Creará datos y configuración completa, generará OpenAPI, verificará respuestas y separará este ejercicio de un despliegue productivo.

La API CSV se comprobó con pygeoapi 0.24.0 y Python 3.13: descubrimiento, endpoint OpenAPI, conformidad, consulta acotada y un identificador inexistente. Eso no demuestra capacidad productiva, autenticación externa ni comportamiento PostGIS. El laboratorio de referencia descargable utiliza una colección distinta, assets; no mezcle sus nombres con stations.

Qué hace pygeoapi

pygeoapi conecta un recurso de API con un proveedor de datos. El proveedor lee la fuente; la API expone colección, enlaces a objetos y consultas soportadas. No necesita convertir cada conjunto en una capa alojada propietaria para que otro programa lo consuma. Sí necesita calidad, permisos, mantenimiento y un contrato estable.

Aquí la fuente es CSV, la geometría se construye con longitud/latitud y la salida es GeoJSON. Empezar con CSV elimina problemas de red y privilegios de base. Una vez comprobado el contrato, continúe con el proveedor PostGIS.

1. Prepare datos y directorio

En un directorio vacío guarde stations.csv:

id,name,longitude,latitude
s1,Station A,-75.58,6.24
s2,Station B,-75.57,6.25

Son estaciones inventadas, no infraestructura u observaciones reales. La licencia siguiente aplica solo a estos registros. Cambiar un campo de configuración no relicencia datos ajenos: una publicación real necesita propietario, licencia, fecha y condiciones de acceso.

Los identificadores deben permanecer estables al ordenar o actualizar el archivo. No use la posición de una fila como ID público. Mantenga longitud antes de latitud; JSON válido con ejes invertidos puede ubicar una estación en otro continente.

2. Guarde la configuración completa

Cree config.yml junto al CSV. server.url es la dirección anunciada al consumidor y debe coincidir con la ruta local. admin: false mantiene el ejercicio limitado a publicación. max_items controla una página, no la cantidad total que un cliente puede descargar mediante muchas solicitudes.

server:
  bind: {host: 127.0.0.1, port: 5000}
  url: http://localhost:5000
  mimetype: application/json; charset=UTF-8
  encoding: utf-8
  languages: [en-US]
  pretty_print: true
  admin: false
  limits: {default_items: 10, max_items: 100}
logging: {level: ERROR}
metadata:
  identification:
    title: Synthetic stations lab
    description: Two fictional stations for local learning
    keywords: [synthetic, stations]
    keywords_type: theme
    terms_of_service: https://creativecommons.org/publicdomain/zero/1.0/
    url: https://example.org
  license: {name: CC0, url: https://creativecommons.org/publicdomain/zero/1.0/}
  provider: {name: Local lab, url: https://example.org}
  contact: {name: Lab operator, email: lab@example.org}
resources:
  stations:
    type: collection
    title: Synthetic stations
    description: Fictional points, not operational observations
    keywords: [synthetic]
    links: []
    extents:
      spatial:
        bbox: [-75.7, 6.1, -75.5, 6.3]
        crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84
    providers:
      - type: feature
        name: CSV
        data: stations.csv
        id_field: id
        geometry: {x_field: longitude, y_field: latitude}

Los metadatos identifican servicio y fuente. La extensión de la colección describe su área; no funciona como filtro de autorización por fila. El proveedor define archivo, clave y columnas de coordenadas. Un encabezado mal escrito puede impedir construir geometría aunque YAML sea válido.

Consulte la configuración de la versión 0.24.0. Mantenga documentación y entorno alineados: latest puede describir una versión en desarrollo.

3. Instale y genere OpenAPI

Ejecute desde el directorio de ambos archivos:

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

El proceso queda en primer plano y se detiene con Ctrl+C. Es un servidor local de desarrollo. Las variables de entorno apuntan a rutas absolutas; el CSV del ejemplo depende del directorio de trabajo. Si inicia desde otro lugar, configure una ruta de datos absoluta o un directorio controlado para el servicio.

Regenerar OpenAPI forma parte de cambiar la publicación. Si el servidor entrega una colección nueva pero el documento describe la anterior, los clientes automatizados reciben información contradictoria. La guía de ejecución documenta generación y puntos de entrada.

4. Descubra la API como un consumidor

Abra la dirección local y revise estos recursos JSON. Los valores y enlaces importan más que el diseño visual de la página.

Declarar conformidad no demuestra que todos los proveedores implementen cada consulta opcional. Consulte la matriz de proveedores de la versión y pruebe los comportamientos requeridos sobre su fuente.

5. Automatice la comprobación

Guarde check_api.py y ejecute python check_api.py en otra terminal mientras corre el servidor:

import json
from urllib.error import HTTPError
from urllib.request import urlopen

base = 'http://localhost:5000'
def get_json(path):
    with urlopen(base + path, timeout=10) as response:
        assert response.status == 200
        return json.load(response)

collections = get_json('/collections?f=json')
assert 'stations' in [item['id'] for item in collections['collections']]
page = get_json('/collections/stations/items?f=json&limit=1')
assert page['type'] == 'FeatureCollection'
assert len(page['features']) == 1
assert page['features'][0]['id'] == 's1'
assert page['features'][0]['geometry']['coordinates'] == [-75.58, 6.24]
item = get_json('/collections/stations/items/s1?f=json')
assert item['id'] == 's1'
try:
    get_json('/collections/stations/items/missing?f=json')
except HTTPError as error:
    assert error.code == 404
else:
    raise AssertionError('Missing identifier must not return another station')
print('Collection, item, coordinates and missing identifier checks passed')

La prueba verifica IDs y coordenadas, no únicamente HTTP 200. Añada una solicitud con limit excesivo y examine el resultado. Con dos registros, devolver dos no prueba un máximo de 100: use el conjunto mayor del laboratorio para verificar un límite real. Esa distinción evita convertir una prueba débil en una afirmación exagerada.

6. Trate paginación y cambios como parte del contrato

Siga los enlaces de paginación cuando la respuesta los proporcione. Registre identificadores recibidos y detecte duplicados inesperados al construir una exportación. Si la fuente cambia entre páginas, decida si necesita instantánea estable, fecha de actualización o descarga separada.

El tamaño de página limita respuesta, pero no necesariamente costo de filtros, tiempo SQL o descarga total. Una API pública puede requerir límites de frecuencia, conexiones y alternativa de descarga masiva. Autenticación y autorización son independientes de los metadatos y la licencia.

7. Diagnóstico

8. Prepare una publicación mantenible

Antes de exponerla, reemplace metadatos ficticios, asigne responsable de actualización, defina campos públicos y URL HTTPS, y ejecute pruebas por el proxy real. Compruebe reinicio y sustitución del archivo con la cuenta de servicio. Documente regreso a la publicación anterior si una actualización queda mal formada.

Continúe con PostGIS, filtros y paginación y producción pygeoapi. Si necesita cartografía renderizada o WMS/WFS, revise GeoServer, pygeoapi y QGIS Server antes de elegir por la facilidad del primer endpoint.