nkleinbaer / stac-fastapi

STAC API implementation with FastAPI.

FastAPI implemention of the STAC API spec.

---

Documentation: https://stac-utils.github.io/stac-fastapi/

Source Code: https://github.com/stac-utils/stac-fastapi

---

Python library for building a STAC compliant FastAPI application. The project is split up into several namespace packages:

• stac_fastapi.api: An API layer which enforces the stac-api-spec.
• stac_fastapi.extensions: Abstract base classes for STAC API extensions and third-party extensions.
• stac_fastapi.types: Shared types and abstract base classes used by the library.

Backends

• stac_fastapi.sqlalchemy: Postgres backend implementation with sqlalchemy.
• stac_fastapi.pgstac: Postgres backend implementation with PGStac.

stac-fastapi was initially developed by arturo-ai.

Installation

# Install from pypi.org
pip install stac-fastapi.api stac-fastapi.types stac-fastapi.extensions

# Install a backend of your choice
pip install stac-fastapi.sqlalchemy
# or
pip install stac-fastapi.pgstac

#/////////////////////
# Install from sources

git clone https://github.com/stac-utils/stac-fastapi.git && cd stac-fastapi
pip install \
  -e stac_fastapi/api \
  -e stac_fastapi/types \
  -e stac_fastapi/extensions

# Install a backend of your choice
pip install -e stac_fastapi/sqlalchemy
# or
pip install -e stac_fastapi/pgstac

Local Development

Use docker-compose via make to start the application, migrate the database, and ingest some example data:

make image
make docker-run-all

• The SQLAlchemy backend app will be available on http://localhost:8081.
• The PGStac backend app will be available on http://localhost:8082.

You can also launch only one of the applications with either of these commands:

make docker-run-pgstac
make docker-run-sqlalchemy

The application will be started on http://localhost:8080.

By default, the apps are run with uvicorn hot-reloading enabled. This can be turned off by changing the value of the RELOAD env var in docker-compose.yml to false.

Note to Docker for Windows users

You'll need to enable experimental features on Docker for Windows in order to run the docker-compose, due to the "--platform" flag that is required to allow the project to run on some Apple architectures. To do this, open Docker Desktop, go to settings, select "Docker Engine", and modify the configuration JSON to have "experimental": true.

Testing

Before running the tests, ensure the database and apps run with docker-compose are down:

docker-compose down

The database container provided by the docker-compose stack must be running. This can be started with:

make run-database

To run tests for both the pgstac and sqlalchemy backends, execute:

make test

To only run pgstac backend tests:

make test-pgstac

To only run sqlalchemy backend tests:

make test-sqlalchemy

Run individual tests by running pytest within a docker container:

make docker-shell-pgstac # or docker-shell-sqlalchemy
$ pip install -e stac_fastapi/pgstac[dev]
$ pytest -v stac_fastapi/pgstac/tests/api/test_api.py