Skip to main content

stac-fastapi-pgstac

GitHub Workflow Status PyPI Documentation License

FastAPI

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,<6.3 >=0.8,<0.10
>=6.3,<7.1 >=0.9,<0.10
>=7.1 >=0.9.2,<0.11

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

With pgstac >=0.10, API hydration uses the base item pgstac returns with each item. pgstac:base_item is reserved for pgstac: it is dropped from items submitted through the transaction extensions and never returned in responses.

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.

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

MIT

Metadata

Release files for stac-fastapi-pgstac 7.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stac-fastapi-pgstac 7.2.2
File Size Uploaded Provenance Actions
stac_fastapi_pgstac-7.2.2.tar.gz 38.7 kB Without provenance Details for stac_fastapi_pgstac-7.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for stac-fastapi-pgstac 7.2.2
File Interpreter ABI Platform Actions
stac_fastapi_pgstac-7.2.2-py3-none-any.whl Python 3 none any Details for stac_fastapi_pgstac-7.2.2-py3-none-any.whl

Total release size: 84.9 kB

Release files / stac_fastapi_pgstac-7.2.2.tar.gz

Download URL stac_fastapi_pgstac-7.2.2.tar.gz
Size 38.7 kB
Tags Source
SHA-256 checksum
How to use checksums
ae4c071730c25ff453d7a29b5f38ad8923b9bb013a6c362fa261445ea1e901e4
BLAKE2b-256 checksum
How to use checksums
c5142c703555647f9ab8b84487e150aca3af2725c83cf207f42d885cb53e35e9
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":"26.04","id":"resolute","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-7.2.2-py3-none-any.whl

Download URL stac_fastapi_pgstac-7.2.2-py3-none-any.whl
Size 46.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cdc12bdfa143b54dbe5552e86b7c4ab96a626b1dba2b52bcef01bbb099ab6d08
BLAKE2b-256 checksum
How to use checksums
dbdeaa7d33d3401655966c52f9cd82e7b0363181279b4c9715d0f3ea762a9fd9
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":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for stac-fastapi-pgstac 7.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

7.2.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page