Skip to content

How-to Guides

This section contains practical guides for configuring and using fastgeoapi features.

Serve a cloud-native format as a collection

The three providers fastgeoapi adds read their data where it already is, with no conversion step in between:

  • GeoParquet — a file, a glob or a hive-partitioned root as an OGC API - Features collection, with CQL2 pushed down into DuckDB.
  • PMTiles — one archive of any size as an OGC API - Tiles collection, read by byte range and awaited.
  • MapLibre — a PMTiles archive drawn as PNG maps by MapLibre Native, as an OGC API - Maps collection; Linux only.

All three take their bucket settings per dataset, and the configuration itself can live in the same place. For a format with no provider yet, the contributor guide walks a Cloud Optimized GeoTIFF from nothing to a working one.

The demo's own configuration, and where to read it

The public demo is not configured by a document you have to take on trust. The same one lives in three places, deliberately:

Where What it is for
pygeoapi-config.demo.yml in the repository history, review, and a way back
the object the deployment reads what is actually serving, right now
DEV_PYGEOAPI_CONFIG in .flyio.env the name of that object

The object carries the same name as the file, so there is nothing to translate between the two.

The first two are kept equal. Fetch the second and diff it against the first: if they differ, the repository is behind, and that is worth knowing rather than guessing.

curl -s https://fastgeoapi-demo.fly.storage.tigris.dev/pygeoapi-config.demo.yml \
  | diff - pygeoapi-config.demo.yml && echo "in step"

You can run it. Every dataset it names is readable without credentials — Overture Maps' own public releases, and the two extracts of ours on the same bucket, opened for reading so the demo can be reproduced rather than believed:

pip install 'fastgeoapi[geoparquet,pmtiles]'
PYGEOAPI_CONFIG=pygeoapi-config.demo.yml fastgeoapi run

The default pygeoapi-config.yml is left alone on purpose: it is what a plain pip install fastgeoapi starts with and what the published image carries, so it may only name providers an installation without extras can build.

A demo is not a deployment

That bucket is readable by anyone because the point here is to be checked. In production, keep the configuration private. It names the buckets it reads, and those may hold data you mean to offer only through the API — as OGC API - Features and Tiles, with your authentication in front — rather than as files anyone can fetch. The document holds no credentials either way: every provider takes its keys from the environment.

Writing it stays authenticated in both cases. The bucket grants read to everyone and write to nobody, so the way to change the demo's configuration is the same as yours: the editor, pointed at the object.

Two things to expect the first time, both measured rather than guessed:

  • The GeoParquet collections are what make the boot slow. The provider reads the dataset's schema when it is constructed — at boot, on every configuration reload and on every dry run. Measured from Europe with a warm DuckDB extension cache the whole server was answering in 40 s; constructing the Overture one alone, cold, took 87 s. In the same region it is a fraction of either. The server looks hung and is not; staging a regional extract is the cure, and the lazio-roads pair is that cure measured.
  • The tile collections cost nothing to start. Overture's archive holds zoom 14 only, which is their choice rather than ours, so its extents.bbox is pinned to a city and the built-in map opens where there are tiles; the PMTiles guide explains why a global box would open on an empty map.

Serve fastgeoapi's own HTML pages

pygeoapi's pages are the default. The native HTML pages replace them on the same URLs. They draw their maps with MapLibre, come in English and Italian, and take your own templates one file at a time.

Configure Identity and Access Management

TBD

Run Keycloak and Open Policy Agent

TBD

Health and Readiness Probes

fastgeoapi exposes two probe endpoints at the application root — outside the FASTGEOAPI_CONTEXT path and outside every authentication chain, so orchestrators (Fly.io checks, Kubernetes probes, control planes) can call them without credentials in any auth mode:

  • GET /healthz — liveness: returns 200 {"status": "ok"} as soon as the process is serving
  • GET /readyz — readiness: returns 200 {"status": "ready"} once the pygeoapi OpenAPI document is available, 503 otherwise

Related knob: FASTGEOAPI_CACHE_DIR relocates the external-refs schema cache and the range cache (default <cwd>/.cache) for containerized layouts with read-only or non-stable working directories.

Configure the MCP Server

fastgeoapi includes an optional integrated MCP server that exposes OGC API endpoints as tools for AI assistants and LLM-based applications.

The MCP server provides:

  • Automatic Tool Generation from the OGC API OpenAPI specification
  • OAuth Authentication with any OIDC-compliant provider
  • Dynamic Client Registration for seamless integration with MCP clients
  • Streamable HTTP Transport, stateless, with the protocol version negotiated per connection

For complete configuration instructions, the supported specifications matrix, and usage examples, see the dedicated MCP section.