EODAG backend for stac-fastapi, the FastAPI implementation of the STAC API spec
stac-fastapi-eodag combines the capabilities of EODAG and STAC FastAPI to provide a powerful, unified API for accessing Earth observation data from various providers.
Make sure you have the required dependencies installed:
pip install .[server]Once the server is properly set up, you can start it with:
python stac_fastapi/eodag/app.py
# or run directly using uvicorn
# the uvicorn parameters configuration will not be applied
uvicorn stac_fastapi.eodag.app:appBy default, the EODAG HTTP server runs at port 8000.
To run the server as a container:
- Build the container image:
docker build -t eodag-fastapi .- Run the container:
docker run -p 8000:8000 eodag-fastapiYou can also run the server using Docker Compose:
docker compose upNOTE: This will start a stac-fastapi-eodag container and an otel-collector container for the collection of metrics. The STAC API is available on http://localhost:8080, the metrics can be checked using http://localhost:8000/metrics.
You can install stac-fastapi-eodag in your Kubernetes cluster with the Helm chart in this repository.
stac-fastapi-eodag supports multiple environment variables to customize the deployment of your API.
| name | description | default value |
|---|---|---|
APP_HOST |
Bind socket to this host. Use 0.0.0.0 to make the application available from every host. |
0.0.0.0 |
APP_PORT |
Port from which the application is available. | 8000 |
RELOAD |
Enable auto-reload. Useful for debug, should be disabled for production. | True |
UVICORN_ROOT_PATH |
Used to compute the base_url when exposing the API on a subPath. For instance /stac. You should set ROOT_PATH (from stac-fastapi parameters) as well. This parameter does not change the path on which the API is exposed. It only modify the links in the response body. |
"" |
The full list of available Uvicorn parameters is available from Uvicorn settings page.
| name | description | default value |
|---|---|---|
STAC_FASTAPI_TITLE |
Title of the API. It is displayed on the landing page. | "stac-fastapi" |
STAC_FASTAPI_DESCRIPTION |
Description for the API. It is displayed on the landing page. | "stac-fastapi" |
STAC_FASTAPI_VERSION |
It is the version number of your API instance. This is not the STAC version. It is displayed on the landing page. | 0.1 |
STAC_FASTAPI_LANDING_PAGE_ID |
It is a unique identifier for the landing page. It is displayed on the landing page. | "stac-fastapi" |
ENABLE_RESPONSE_MODELS |
Turn on response validation. | False |
OPENAPI_URL |
Path for the OpenAPI definition of the API. | "/api" |
DOCS_URL |
Path for the Swagger UI of the API. | "/api.html" |
ROOT_PATH |
Used to compute the base_url when exposing the API on a subPath. For instance /stac. You should set UVICORN_ROOT_PATH (from Uvicorn parameters) as well. This parameter does not change the path on which the API is exposed. It only modify the links in the response body. |
"" |
Reach to stac-fastapi documentation for exhaustive documentation on stac-fastapi.
| name | description | default value |
|---|---|---|
DEBUG |
When set to True, set the EODAG logging level to 3. Otherwise, set EODAG logging level to 2. |
False |
KEEP_ORIGIN_URL |
Keep origin as alternate URL when data-download extension is enabled. | False |
ORIGIN_URL_BLACKLIST |
Hide from clients items assets' origin URLs starting with URLs from the list. A string of comma separated values is expected. | "" |
FETCH_PROVIDERS |
Fetch additional collections from all EODAG providers. | False |
DOWNLOAD_BASE_URL |
Useful to expose asset download URL in a separate domain name. | "" |
| name | description | default value |
|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT |
Target url to which the exporter sends the metrics. | "" |
OTEL_METRIC_EXPORT_INTERVAL |
Time interval (in milliseconds) between the start of two export attempts. | 60000 |
OTEL_EXPORTER_OTLP_TIMEOUT |
Timeout value for all outgoing data (traces, metrics, and logs) in milliseconds. | 10000 |
To start an otel-collector container and to connect it to an instance of STAC API the following commands can be used:
pip install .[server,telemetry]
docker run -p 4318:4318 -p 8000:8000 \
-v ./config/otelcol_config.yml:/etc/otel-collector-config.yaml \
otel/opentelemetry-collector:latest \
--config=/etc/otel-collector-config.yaml
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/"
export OTEL_METRIC_EXPORT_INTERVAL="5000" # shorter export interval for testing
export APP_PORT=8080 # change app port because otel-collector uses 8000
python stac_fastapi/eodag/app.pyEODAG configuration parameters are available from EODAG documentation.
Have you spotted a typo in our documentation? Have you observed a bug while running stac-fastapi-eodag? Do you have a suggestion for a new feature?
Don't hesitate and open an issue or submit a pull request, contributions are most welcome!
For guidance on setting up a development environment and how to make a contribution to eodag, see the contributing guidelines.
We would like to express our gratitude to the maintainers and contributors of the following projects which have been instrumental in the development of this project:
- stac-fastapi: Thanks to the stac-fastapi team for their implementation of the STAC API spec.
- FastAPI: Thanks to the FastAPI team for providing a modern, fast (high-performance) web framework for building APIs.
stac-fastapi-eodag is licensed under Apache License v2.0. See LICENSE file for details.