stac-fastapi-pgstac

June 11, 2026 · View on GitHub

PgSTAC backend for stac-fastapi, the FastAPI implementation of the STAC API spec

Overview

stac-fastapi-pgstac is an HTTP interface built in FastAPI. It validates requests and data sent to a PgSTAC backend, and adds links to the returned data. All other processing and search is provided directly using PgSTAC procedural sql / plpgsql functions on the database. PgSTAC stores all collection and item records as jsonb fields exactly as they come in allowing for any custom fields to be stored and retrieved transparently.

`PgSTAC` version

stac-fastapi-pgstac depends on pgstac database schema and pypgstac python package.

stac-fastapi-pgstac Version	pgstac
2.5	>=0.7,<0.8
3.0	>=0.8,<0.9
>=4.0	>=0.8,<0.10

Usage

PgSTAC is an external project and may be used by multiple front ends. For STAC FastAPI development, a Docker image (which is pulled as part of the docker-compose) is available via the Github container registry. The PgSTAC version required by stac-fastapi-pgstac is found in the setup file.

Sorting

While the STAC Sort Extension is fully supported, PgSTAC is particularly enhanced to be able to sort by datetime (either ascending or descending). Sorting by anything other than datetime (the default if no sort is specified) on very large STAC repositories without very specific query limits (ie selecting a single day date range) will not have the same performance. For more than millions of records it is recommended to either set a low connection timeout on PostgreSQL or to disable use of the Sort Extension.

Hydration

To configure stac-fastapi-pgstac to hydrate search result items at the API level, set the USE_API_HYDRATE environment variable to true. If false (default) the hydration will be done in the database.

use_api_hydrate (API)	nohydrate (PgSTAC)	Hydration
False	False	PgSTAC
True	True	API

Multi-Tenant Catalogs Extension

stac-fastapi-pgstac supports the optional Multi-Tenant Catalogs Extension for managing hierarchical catalog structures with support for Directed Acyclic Graphs (DAG). This enables flexible catalog hierarchies where collections and catalogs can have multiple parents.

To enable this extension, install the stac-fastapi-catalogs-extension package and set the ENABLE_CATALOGS_EXTENSION=TRUE environment variable.

For write operations (creating, updating, and deleting catalogs, and linking/unlinking collections and catalogs), also set ENABLE_TRANSACTIONS_EXTENSIONS=TRUE.

Poly-Hierarchy Links

When a catalog or collection has multiple parents, the API exposes the catalog hierarchy through STAC link relations:

rel="parent": Points to the contextual parent (the catalog through which the resource was accessed)
rel="related": Links to alternative parents in the poly-hierarchy (for catalogs and scoped collections)
rel="duplicate": Links to alternative scoped paths where a collection can be accessed (e.g., /catalogs/{parentId}/collections/{collectionId})
rel="canonical": Points to the global collection endpoint for scoped collections

To prevent information leakage about other tenants in multi-tenant deployments, set HIDE_ALTERNATE_PARENTS=TRUE to suppress rel="related" and rel="duplicate" links. When enabled, only the contextual rel="parent" link is advertised.

Note: The link relation names for poly-hierarchy navigation are subject to change as the OGC and STAC communities continue to standardize on terminology. These names may be updated in future releases to align with emerging standards.

Migrations

There is a Python utility as part of PgSTAC (pypgstac) that includes a migration utility. To use:

pypgstac migrate

Development

Quick Start

Install the packages in editable mode:

We recommend using uv as project manager for development.

See https://docs.astral.sh/uv/getting-started/installation/ for installation

uv sync --dev

Running the API Locally

Start the API with Docker Compose:

make docker-run

The API will be available at http://localhost:8082

Running with Nginx Proxy

To run the API behind an Nginx proxy:

make docker-run-nginx-proxy

The API will be available at:

Direct: http://localhost:8082
Via Nginx: http://localhost:8080/api/v1/pgstac/

Loading Demo Data

To load the Joplin demo dataset:

make load-joplin

Running Tests

To run tests locally (requires postgres/postgis system packages):

uv run pytest

NOTE: If running tests directly on your machine doesn't work, you can use Docker Compose instead. You need Docker and Docker Compose installed.

To run tests in a container:

make test

Stopping Services

To stop running services:

make docker-down          # Stop the default app
make docker-down-nginx    # Stop the nginx variant
make docker-down-all      # Stop all services