stac-fastapi-pgstac
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
Contributing
See CONTRIBUTING for detailed contribution instructions.
Releasing
See RELEASING.md.
History
stac-fastapi-pgstac was initially added to stac-fastapi by developmentseed. In April of 2023, it was removed from the core stac-fastapi repository and moved to its current location (http://github.com/stac-utils/stac-fastapi-pgstac).
License
1 maintainer
Metadata
1 maintainer
Release files for stac-fastapi-pgstac 6.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| stac_fastapi_pgstac-6.4.0.tar.gz | 36.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stac_fastapi_pgstac-6.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 81.3 kB
Release files / stac_fastapi_pgstac-6.4.0.tar.gz
| Download URL | stac_fastapi_pgstac-6.4.0.tar.gz |
|---|---|
| Size | 36.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2f02bb2b6d5ef3b5edd5d5d049371793ed99741e911bcdcc8ab7881e4296aaa0
|
|
BLAKE2b-256 checksum How to use checksums |
717872dd5b8010cd29560faae4fc9c5913a30f3f957b490481b1b9c0bb787ca1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.30 {"installer":{"name":"uv","version":"0.9.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / stac_fastapi_pgstac-6.4.0-py3-none-any.whl
| Download URL | stac_fastapi_pgstac-6.4.0-py3-none-any.whl |
|---|---|
| Size | 44.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b33997cf598c292d514846837846754f8dac0966b5e7e0c2a3b585a85a77f125
|
|
BLAKE2b-256 checksum How to use checksums |
d2de8c186dcc84f9f9e44aee656bf7410887058c58fab0d644fa87e589f189a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.30 {"installer":{"name":"uv","version":"0.9.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
