An implementation of STAC API based on the FastAPI framework and using the pgstac backend.
Project description
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.
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 in the API, set the USE_API_HYDRATE environment variable to true or explicitly set the option in the PGStac Settings object.
Migrations
There is a Python utility as part of PgSTAC (pypgstac) that includes a migration utility. To use:
pypgstac migrate
Contributing
See CONTRIBUTING for detailed contribution instructions.
To install:
git clone https://github.com/stac-utils/stac-fastapi-pgstac
cd stac-fastapi-pgstac
pip install -e ".[dev,server,docs]"
To test:
make test
Use Github Pull Requests to provide new features or to request review of draft code, and use Issues to report bugs or request new features.
Documentation
To build the docs:
make docs
Then, serve the docs via a local HTTP server:
mkdocs serve
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file stac_fastapi_pgstac-2.5.0.tar.gz.
File metadata
- Download URL: stac_fastapi_pgstac-2.5.0.tar.gz
- Upload date:
- Size: 34.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.0.0 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 10a4c7efcab5b950375219a4572d00b205494e759d1b5cd9f800f61a34c43a2a |
|
| MD5 | 7227e014674d18460f36ceac3fb5b8cf |
|
| BLAKE2b-256 | 9a7f35a5ab9faaf12ff1d5ba8a87612fae478992a7c21f61356d8a8b2863760b |
Provenance
File details
Details for the file stac_fastapi.pgstac-2.5.0-py3-none-any.whl.
File metadata
- Download URL: stac_fastapi.pgstac-2.5.0-py3-none-any.whl
- Upload date:
- Size: 38.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.0.0 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1be9fb4d81ed583f2e78956653b9745c0d6996c820a0128e3494d337bedcf833 |
|
| MD5 | 21f315d89b6fc0d1dbf3efff25459a7a |
|
| BLAKE2b-256 | 6b125eb498ad733ffcb1972157063df31d14e8de0eebec630f83695a17a9a632 |
