STAC FastAPI

https://github.com/stac-utils/stac-fastapi
Admin
Python library for building a STAC-compliant FastAPI application that enables SpatioTemporal Asset...
Tokens:15,965
Snippets:100
Trust Score:9.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install STAC FastAPI components and launch the API with Uvicorn

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/index.md

Installs the core STAC FastAPI packages and the PgSTAC backend, then starts the API server. After running these commands, the API is accessible at http://localhost:8080.

```bash
# Install core software from PyPI
python -m pip install stac-fastapi.types stac-fastapi.api stac-fastapi.extensions uvicorn

# Install a backend of your choice, here's PgSTAC
python -m pip install stac-fastapi.pgstac

# Launch the API
uvicorn stac_fastapi.pgstac.app:app --host 0.0.0.0 --port 8080
```

--------------------------------

### Install core dependencies

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/get-started.md

Creates a virtual environment and installs the core STAC FastAPI packages and uvicorn.

```bash
# Create a virtual environment
python -m venv env
source ./env/bin/activate

# Install core dependencies
python -m pip install stac-fastapi.types stac-fastapi.api stac-fastapi.extensions uvicorn
```

--------------------------------

### Install PgSTAC backend

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/get-started.md

Installs the PgSTAC backend package for STAC FastAPI.

```bash
python -m pip install stac-fastapi.pgstac
```

--------------------------------

### Install stac-fastapi-api[metrics]

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/tips-and-tricks.md

Install the optional dependency to enable Prometheus metrics support.

```bash
pip install "stac-fastapi-api[metrics]"
```

--------------------------------

### Install pre-commit Git hook

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/contributing.md

Installs the pre-commit Git hook using uv. Run this in the repository root before committing.

```bash
uv run pre-commit install
```

--------------------------------

### Build and serve documentation with MkDocs

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/contributing.md

Builds the documentation site to `./site` or starts a live-reload dev server using the `docs` group and the `docs/mkdocs.yml` config. Use these commands for local documentation work.

```bash
# Static build (output → ./site)
uv run --group docs mkdocs build -f docs/mkdocs.yml

# Live‑reload dev server
uv run --group docs mkdocs serve -f docs/mkdocs.yml --livereload
```

--------------------------------

### Set up Docker database for PgSTAC

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/get-started.md

Clones the stac-fastapi-pgstac repository and starts the Docker database using make run-database.

```bash
# Get PgSTAC FastAPI code
git clone https://github.com/stac-utils/stac-fastapi-pgstac.git
cd stac-fastapi-pgstac

# Start Docker database
make run-database
```

--------------------------------

### Set up local PostgreSQL database with PgSTAC

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/get-started.md

Clones PgSTAC, installs migration dependencies, and applies PgSTAC structures to a local database. Requires superuser permissions for the migration and grants pgstac_admin to the user.

```bash
# Download PgSTAC
git clone https://github.com/stac-utils/pgstac.git
cd pgstac/src/pgstac-migrate/

# Install dependencies
python -m venv env
source ./env/bin/activate
pip install -e .

# Add PgSTAC structures to database
# Note that your PostgreSQL user needs superuser permissions to do the install
pgstac-migrate migrate -d postgres://myuser@localhost:5432/database

# Give PgSTAC admin rights as well
psql -d postgres://myuser@localhost:5432/database -c "GRANT pgstac_admin TO myuser"
```

--------------------------------

### Custom GET request with Query alias

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v3.0.0.md

Example of defining a custom GET request model with an aliased query parameter using Annotated and Query().

```python
@attr.s
class SomeRequest(APIRequest):
    user_number: Annotated[Optional[int], Query(alias="user-number")] = attr.ib(default=None)
```

--------------------------------

### Clone repository and install dependencies with uv

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/contributing.md

Clones the stac-fastapi repository, installs dev and runtime dependencies via `uv sync --dev`, and runs the test suite with `uv run pytest`. Use this to set up a local development environment.

```bash
# Clone the repository
git clone https://github.com/stac-utils/stac-fastapi.git
cd stac-fastapi

# Install dependencies (dev + runtime)
uv sync --dev

# Run tests to confirm everything works
uv run pytest
```

--------------------------------

### Start the API with uvicorn

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/get-started.md

Runs the STAC FastAPI application on localhost:8080 using the PgSTAC backend.

```bash
uvicorn stac_fastapi.pgstac.app:app --host 0.0.0.0 --port 8080
```

--------------------------------

### Implement AsyncBaseSortablesClient with get_sortables methods

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/tips-and-tricks.md

Create a class inheriting from AsyncBaseSortablesClient and implement the abstract methods for the endpoints you wish to support. The example returns JSON schemas for /search, /collections/{collection_id}/items, and /collections endpoints.

```python
from typing import Any
from starlette.requests import Request
from stac_fastapi.extensions.sort import AsyncBaseSortablesClient


class MySortablesClient(AsyncBaseSortablesClient):
    
    async def get_sortables(self, request: Request | None = None, **kwargs: Any) -> dict[str, Any]:
        """Return sortables for the /search endpoint."""
        return {
            "$id": "https://example.com/sortables",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "Item Search Sortables",
            "type": "object",
            "properties": {
                "id": {"type": "string"},
                "properties.datetime": {"type": "string", "format": "date-time"},
                "properties.cloud_cover": {"type": "number", "minimum": 0, "maximum": 100}
            }
        }

    async def get_collection_sortables(self, collection_id: str, request: Request | None = None, **kwargs: Any) -> dict[str, Any]:
        """Return sortables for the /collections/{collection_id}/items endpoint."""
        # You can dynamically return schemas based on the collection_id
        return {
            "$id": f"https://example.com/collections/{collection_id}/sortables",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
                "id": {"type": "string"},
                "properties.datetime": {"type": "string", "format": "date-time"}
            }
        }

    async def get_collections_sortables(self, request: Request | None = None, **kwargs: Any) -> dict[str, Any]:
        """Return sortables for the /collections endpoint."""
        return {
            "$id": "https://example.com/collections-sortables",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
                "id": {"type": "string"},
                "title": {"type": "string"}
            }
        }
```

--------------------------------

### Migrate filter extension to filter_expr with TestClient

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v4.0.0.md

Shows the before and after usage of the filter extension in a STAC API test. The example sets up a dummy core client and API with the filter extension, then demonstrates that POST and GET requests using `filter` now return `filter_expr` in the response. The `filter` parameter in requests remains unchanged, but the response attribute is renamed.

```python
from starlette.testclient import TestClient
from stac_fastapi.api.app import StacApi
from stac_fastapi.api.models import create_get_request_model, create_post_request_model
from stac_fastapi.extensions.core import FilterExtension
from stac_fastapi.types.config import ApiSettings
from stac_fastapi.types.core import BaseCoreClient

class DummyCoreClient(BaseCoreClient):
    def all_collections(self, *args, **kwargs):
        raise NotImplementedError

    def get_collection(self, *args, **kwargs):
        raise NotImplementedError

    def get_item(self, *args, **kwargs):
        raise NotImplementedError

    def get_search(self, *args, **kwargs):
        return kwargs

    def post_search(self, *args, **kwargs):
        return args[0].model_dump()

    def item_collection(self, *args, **kwargs):
        raise NotImplementedError

extensions = [FilterExtension()]
api = StacApi(
    settings=ApiSettings(enable_response_models=False),
    client=DummyCoreClient(),
    extensions=extensions,
    search_get_request_model=create_get_request_model(extensions),
    search_post_request_model=create_post_request_model(extensions),
)


# before
with TestClient(api.app) as client:
    response = client.post(
        "/search",
        json={
            "filter": {"op": "=", "args": [{"property": "test_property"}, "test-value"]},
        },
    )
    assert response.json()["filter"]

    response = client.get(
        "/search",
        params={
            "filter": "id='item_id' AND collection='collection_id'",
        },
    )
    assert response.json()["filter"]

# now
with TestClient(api.app) as client:
    response = client.post(
        "/search",
        json={
            "filter": {"op": "=", "args": [{"property": "test_property"}, "test-value"]},
        },
    )
    assert response.json()["filter_expr"]

    response = client.get(
        "/search",
        params={
            "filter": "id='item_id' AND collection='collection_id'",
        },
    )
    assert response.json()["filter_expr"]

```

--------------------------------

### BaseSearchGetRequest GET request model

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v3.0.0.md

Default GET request model for the /search endpoint. Uses python attrs with Annotated type hints and FastAPI Query() for query parameters.

```python
@attr.s
class BaseSearchGetRequest(APIRequest):
    """Base arguments for GET Request."""

    collections: Optional[List[str]] = attr.ib(default=None, converter=_collection_converter)
    ids: Optional[List[str]] = attr.ib(default=None, converter=_ids_converter)
    bbox: Optional[BBox] = attr.ib(default=None, converter=_bbox_converter)
    intersects: Annotated[Optional[str], Query()] = attr.ib(default=None)
    datetime: Optional[DateTimeType] = attr.ib(
        default=None, converter=_datetime_converter
    )
    limit: Annotated[Optional[int], Query()] = attr.ib(default=10)
```

--------------------------------

### Verify datetime is string in GET search with DummyCoreClient

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v4.0.0.md

Shows a DummyCoreClient whose get_search returns True if the datetime parameter is a string, and a TestClient request to /search that asserts the response is True after the 4.0 change. Before 4.0, the datetime was a datetime.datetime and the assertion would be False.

```python
from starlette.testclient import TestClient
from stac_fastapi.api.app import StacApi
from stac_fastapi.types.config import ApiSettings
from stac_fastapi.types.core import BaseCoreClient

class DummyCoreClient(BaseCoreClient):
    def all_collections(self, *args, **kwargs):
        raise NotImplementedError

    def get_collection(self, *args, **kwargs):
        raise NotImplementedError

    def get_item(self, *args, **kwargs):
        raise NotImplementedError

    def get_search(self, *args, datetime = None, **kwargs):
        # Return True if datetime is a string
        return isinstance(datetime, str)

    def post_search(self, *args, **kwargs):
        raise NotImplementedError

    def item_collection(self, *args, **kwargs):
        raise NotImplementedError

api = StacApi(
    settings=ApiSettings(enable_response_models=False),
    client=DummyCoreClient(),
    extensions=[],
)


# before
with TestClient(api.app) as client:
    response = client.get(
        "/search",
        params={
            "datetime": "2020-01-01T00:00:00.00001Z",
        },
    )
    assert response.json() == False

# now
with TestClient(api.app) as client:
    response = client.get(
        "/search",
        params={
            "datetime": "2020-01-01T00:00:00.00001Z",
        },
    )
    assert response.json() == True
```

--------------------------------

### Use granular sort extensions for specific endpoints

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/tips-and-tricks.md

Use granular extensions instead of the global SortExtension to only mount routes and advertise conformance classes for specific endpoints. The example shows SearchSortExtension for /search and ItemCollectionSortExtension for /collections/{id}/items.

```python
from stac_fastapi.extensions.sort import (
    SearchSortExtension,
    ItemCollectionSortExtension
)

api = StacApi(
    # ... other configurations ...
    extensions=[
        # Only support sorting on /search and /collections/{id}/items
        SearchSortExtension(client=sortables_client),
        ItemCollectionSortExtension(client=sortables_client),
    ]
)
```

--------------------------------

### Converter with Annotated type hint

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v3.0.0.md

Shows how to define a converter with Annotated type hints for a GET request attribute. The converter function is used to transform the query parameter value.

```python
def _ids_converter(
    val: Annotated[
        Optional[str],
        Query(
            description="Array of Item ids to return.",
        ),
    ] = None,
) -> Optional[List[str]]:
    return str2list(val)

@attr.s
class BaseSearchGetRequest(APIRequest):
    """Base arguments for GET Request."""

    ids: Optional[List[str]] = attr.ib(default=None, converter=_ids_converter)
```

--------------------------------

### Override default middlewares in StacApi

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/tips-and-tricks.md

Use this to customize the default middlewares (Brotli, CORS, ProxyHeader) in your backend's app.py. The example replaces the default middlewares with a custom CORS middleware allowing origins from 'https://myendpoints.io'.

```python
from starlette.middleware import Middleware

from stac_fastapi.api.app import StacApi
from starlette.middleware.cors import CORSMiddleware


api = StacApi(
    ...
    middlewares=[
        Middleware(CORSMiddleware, allow_origins=["https://myendpoints.io"])
    ],
    ...
)
```

--------------------------------

### Custom Fields extension POST request with default includes

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/tips-and-tricks.md

Define a custom FieldsExtensionPostRequest to set default included fields for POST requests. The example sets a default 'include' set of common STAC keys and overrides the extension's POST model.

```python
from typing import Optional, Set

import attr
from stac_fastapi.extensions import FieldsExtension as FieldsExtensionBase
from stac_fastapi.extensions.fields import request
from pydantic import BaseModel, Field


class PostFieldsExtension(requests.PostFieldsExtension):
    include: Optional[Set[str]] = Field(
        default_factory=lambda: {
            "id",
            "type",
            "stac_version",
            "geometry",
            "bbox",
            "links",
            "assets",
            "properties.datetime",
            "collection",
        }
    )
    exclude: Optional[Set[str]] = set()


class FieldsExtensionPostRequest(BaseModel):
    """Additional fields and schema for the POST request."""

    fields: Optional[PostFieldsExtension] = Field(PostFieldsExtension())


class FieldsExtension(FieldsExtensionBase):
    """Override the POST model"""

    POST = FieldsExtensionPostRequest


from stac_fastapi.api.app import StacApi

stac = StacApi(
    extensions=[
        FieldsExtension()
    ]
)
```

--------------------------------

### Middleware configuration before and after

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v3.0.0.md

Shows the old way of passing middleware classes directly and the new way using starlette.middleware.Middleware to pass options dynamically.

```python
# before
class myMiddleware(mainMiddleware):
    option1 = option1
    option2 = option2

stac = StacApi(
    middlewares=[
        myMiddleware,
    ]
)

# now
stac = StacApi(
    middlewares=[
        Middleware(myMiddleware, option1, option2),
    ]
)
```

--------------------------------

### Load demo collection and item via SQL

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/get-started.md

Inserts a demo collection and item directly into PgSTAC tables using SQL. The collection defines temporal and spatial extents; the item uses ST_Point for geometry and includes an asset.

```sql
-- Single collection
INSERT INTO pgstac.collections (content)
SELECT jsonb_build_object(
	'type', 'Collection',
	'id', '1',
	'extent', jsonb_build_object(
		'temporal', jsonb_build_object(
			'interval', json_build_array(
				json_build_array(
					'2026-01-01',
					'2026-12-31'
				)
			)
		),
		'spatial', jsonb_build_object(
			'bbox', json_build_array(
				json_build_array(-180.0, -90.0, 180.0, 90.0)
			)
		)
	)
);

-- Single item
INSERT INTO pgstac.items_staging_upsert(content)
SELECT jsonb_build_object(
	'type', 'Feature',
	'id', '1',
	'geometry', ST_Point(-1.7, 48.7, 4326),
	'collection', '1',
	'properties', json_build_object(),
	'assets', json_build_object(
		'hd', json_build_object(
			'href', 'https://path.to/some/image',
			'roles', json_build_array('data'),
			'type', 'image/jpeg'
		)
	)
);
```

--------------------------------

### Manually deploy docs with mkdocs gh-deploy

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/contributing.md

Manually deploys documentation to GitHub Pages using `mkdocs gh-deploy`. Note that this is normally unnecessary because GitHub Actions deploys automatically for new commits.

```bash
uv run --group docs mkdocs gh-deploy -f docs/mkdocs.yml
```

--------------------------------

### Pagination extension: before and after migration

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v3.0.0.md

Shows the old way of using pagination_extension and the new way using items_get_request_model with a custom request model created via create_request_model.

```python
# before
stac=StacApi(
    pagination_extension=TokenPaginationExtension,
    extension=[TokenPaginationExtension]
)

# now
items_get_request_model = create_request_model(
    "ItemCollectionURI",
    base_model=ItemCollectionUri,
    mixins=[TokenPaginationExtension().GET],
)

stac=StacApi(
    extension=[TokenPaginationExtension],
    items_get_request_model=items_get_request_model,
)

```

--------------------------------

### Request model customization before and after

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v3.0.0.md

Shows the previous way of customizing only search request models and the new way with additional attributes for collections and items endpoints.

```python
# before
getSearchModel = create_request_model(
    model_name="SearchGetRequest",
    base_model=BaseSearchGetRequest
    extensions=[...],
    request_type="GET"
)
stac = StacApi(
    search_get_request_model=getSearchModel,
    search_post_request_model=...,
)

# now
@attr.s
class CollectionsRequest(APIRequest):
    user: Annotated[str, Query(...)] = attr.ib()

stac = StacApi(
    search_get_request_model=getSearchModel,
    search_post_request_model=postSearchModel,
        collections_get_request_model=CollectionsRequest,
        collection_get_request_model=...,
        items_get_request_model=...,
        item_get_request_model=...,
)
```

--------------------------------

### Create .env configuration file

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/get-started.md

Defines the PostgreSQL connection settings used by the API. The Docker database requires different values (PGUSER=username, PGPASSWORD=password, PGDATABASE=postgis, PGHOST=localhost, PGPORT=5439).

```env
PGUSER=myuser
PGPASSWORD=mypassword
PGHOST=localhost
PGPORT=5432
PGDATABASE=database
```

```env
PGUSER=username
PGPASSWORD=password
PGDATABASE=postgis
PGHOST=localhost
PGPORT=5439
```

--------------------------------

### Run all pre-commit checks manually

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/contributing.md

Optionally runs all pre-commit checks (ruff, pydocstring, mypy) on all files without committing.

```bash
uv run pre-commit run --all-files
```

--------------------------------

### Render benchmark charts with Chart.js

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/benchmarks.html

JavaScript code that fetches benchmark data from a remote URL, parses it, and renders interactive line charts using Chart.js. It includes tooltip callbacks to show commit details and a click handler to open the commit URL in a new tab. The code also provides a download button to export the raw data as a JSON file.

```javascript
'use strict'; (function() { // Colors from https://github.com/github/linguist/blob/master/lib/linguist/languages.yml const toolColors = { cargo: '#dea584', go: '#00add8', benchmarkjs: '#f1e05a', benchmarkluau: '#000080', pytest: '#3572a5', googlecpp: '#f34b7d', catch2: '#f34b7d', julia: '#a270ba', jmh: '#b07219', benchmarkdotnet: '#178600', customBiggerIsBetter: '#38ff38', customSmallerIsBetter: '#ff3838', _: '#333333' }; function init(data) { function collectBenchesPerTestCase(entries) { const map = new Map(); for (const entry of entries) { const {commit, date, tool, benches} = entry; for (const bench of benches) { const result = { commit, date, tool, bench }; const arr = map.get(bench.name); if (arr === undefined) { map.set(bench.name, [result]); } else { arr.push(result); } } } return map; } // Render header document.getElementById('last-update').textContent = new Date(data.lastUpdate).toString(); const repoLink = document.getElementById('repository-link'); repoLink.href = data.repoUrl; repoLink.textContent = data.repoUrl; // Render footer document.getElementById('dl-button').onclick = () => { const dataUrl = 'data:,' + JSON.stringify(data, null, 2); const a = document.createElement('a'); a.href = dataUrl; a.download = 'benchmark_data.json'; a.click(); }; // Prepare data points for charts return Object.keys(data.entries).map(name => ({ name, dataSet: collectBenchesPerTestCase(data.entries[name]), })); } function renderAllChars(dataSets) { function renderGraph(parent, name, dataset) { const canvas = document.createElement('canvas'); canvas.className = 'benchmark-chart'; parent.appendChild(canvas); const color = toolColors[dataset.length > 0 ? dataset[0].tool : '_']; const data = { labels: dataset.map(d => d.commit.id.slice(0, 7)), datasets: [ { label: name, data: dataset.map(d => d.bench.value), borderColor: color, backgroundColor: color + '60', // Add alpha for #rrggbbaa } ], }; const options = { scales: { xAxes: [ { scaleLabel: { display: true, labelString: 'commit', }, } ], yAxes: [ { scaleLabel: { display: true, labelString: dataset.length > 0 ? dataset[0].bench.unit : '', }, ticks: { beginAtZero: true, } } ], }, tooltips: { callbacks: { afterTitle: items => { const {index} = items[0]; const data = dataset[index]; return '\n' + data.commit.message + '\n\n' + data.commit.timestamp + ' committed by @' + data.commit.committer.username + '\n'; }, label: item => { let label = item.value; const { range, unit } = dataset[item.index].bench; label += ' ' + unit; if (range) { label += ' (' + range + ')'; } return label; }, afterLabel: item => { const { extra } = dataset[item.index].bench; return extra ? '\n' + extra : ''; } } }, onClick: (_mouseEvent, activeElems) => { if (activeElems.length === 0) { return; } // XXX: Undocumented. How can we know the index? const index = activeElems[0]._index; const url = dataset[index].commit.url; window.open(url, '_blank'); }, }; new Chart(canvas, { type: 'line', data, options, }); } function renderBenchSet(name, benchSet, main) { const setElem = document.createElement('div'); setElem.className = 'benchmark-set'; main.appendChild(setElem); const nameElem = document.createElement('h1'); nameElem.className = 'benchmark-title'; nameElem.textContent = name; setElem.appendChild(nameElem); const graphsElem = document.createElement('div'); graphsElem.className = 'benchmark-graphs'; setElem.appendChild(graphsElem); for (const [benchName, benches] of benchSet.entries()) { renderGraph(graphsElem, benchName, benches) } } const main = document.getElementById('main'); for (const {name, dataSet} of dataSets) { renderBenchSet(name, dataSet, main); } } fetch('https://raw.githubusercontent.com/stac-utils/stac-fastapi/gh-benchmarks/dev/bench/data.js') .then(res => { if (res.ok) return res.text() throw new Error('Network response was not ok.') }) .then(data => { const data_json = JSON.parse(data.replace('window.BENCHMARK_DATA = ', '')); renderAllChars(init(data_json)) return }) .catch(err => { console.log(err) }); })();
```

--------------------------------

### Enable metrics on StacApi

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/tips-and-tricks.md

Set add_metrics=True on StacApi to expose {router_prefix}/_mgmt/metrics with low-cardinality STAC operation labels. The /_mgmt/* routes are excluded from instrumentation.

```python
from stac_fastapi.api.app import StacApi

api = StacApi(
    settings=settings,
    client=client,
    add_metrics=True,
)
```

--------------------------------

### Define a custom ApiExtension class

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/contributing.md

Defines a custom extension by subclassing `stac_fastapi.types.extension.ApiExtension` and binding a FastAPI route inside the `register()` method. Use this to add deployment-specific routes without forking the core repository.

```python
from fastapi import APIRouter
from stac_fastapi.types.extension import ApiExtension

class MyCustomExtension(ApiExtension):
    """Example of a custom out-of-tree extension."""

    def register(self, app):
        router = APIRouter()

        @router.get("/api/custom-route")
        async def my_route():
            return {"message": "Hello from my custom extension!"}

        app.include_router(router)
```

--------------------------------

### Filter extension: before and after migration

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v3.0.0.md

Shows the old way of using FieldsExtension without default_includes and the new way by overriding the POST model to include default fields. The new approach defines a custom PostFieldsExtension with default include set, a request model, and a FieldsExtension override.

```python
# before
stac = StacApi(
    extensions=[
        FieldsExtension()
    ]
)

# now
class PostFieldsExtension(requests.PostFieldsExtension):
    include: Optional[Set[str]] = Field(
        default_factory=lambda: {
            "id",
            "type",
            "stac_version",
            "geometry",
            "bbox",
            "links",
            "assets",
            "properties.datetime",
            "collection",
        }
    )
    exclude: Optional[Set[str]] = set()


class FieldsExtensionPostRequest(BaseModel):
    """Additional fields and schema for the POST request."""

    fields: Optional[PostFieldsExtension] = Field(PostFieldsExtension())


class FieldsExtension(FieldsExtensionBase):
    """Override the POST model"""

    POST = FieldsExtensionPostRequest


from stac_fastapi.api.app import StacApi

stac = StacApi(
    extensions=[
        FieldsExtension()
    ]
)

```

--------------------------------

### Before: BadCoreClient returning invalid STAC Item

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v3.0.0.md

Shows the previous implementation where post_search and get_search return a plain dictionary that is not a proper STAC Item. This caused validation to be bypassed for all requests when the Fields extension was enabled.

```python
# before
class BadCoreClient(BaseCoreClient):
    def post_search(
        self, search_request: BaseSearchPostRequest, **kwargs
    ) -> stac.ItemCollection:
        return {"not": "a proper stac item"}

    def get_search(
        self,
        collections: Optional[List[str]] = None,
        ids: Optional[List[str]] = None,
        bbox: Optional[List[NumType]] = None,
        intersects: Optional[str] = None,
        datetime: Optional[Union[str, datetime]] = None,
        limit: Optional[int] = 10,
        **kwargs,
    ) -> stac.ItemCollection:
        return {"not": "a proper stac item"}
```

--------------------------------

### Bump version with bump-my-version CLI

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/contributing.md

Use the bump-my-version CLI to update the version number across the repository. The command sets the new version to 3.1.0.

```bash
uv run --with bump-my-version bump-my-version bump --new-version 3.1.0
```

--------------------------------

### Parse datetime interval and single date with BaseSearchGetRequest

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v4.0.0.md

Shows how to use parse_datetime(), start_date, and end_date on BaseSearchGetRequest for both an interval (slash-separated) and a single date. For a single date, end_date returns None.

```python
from stac_fastapi.types.search import BaseSearchGetRequest

# Interval
search = BaseSearchGetRequest(datetime="2020-01-01T00:00:00.00001Z/2020-01-02T00:00:00.00001Z")

search.parse_datetime()
>>> (datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc), datetime.datetime(2020, 1, 2, 0, 0, 0, 10, tzinfo=datetime.timezone.utc))

search.start_date
>>> datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc)

search.end_date
>>> datetime.datetime(2020, 1, 2, 0, 0, 0, 10, tzinfo=datetime.timezone.utc)

# Single date
search = BaseSearchGetRequest(datetime="2020-01-01T00:00:00.00001Z")

search.parse_datetime()
>>> datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc)

search.start_date
>>> datetime.datetime(2020, 1, 1, 0, 0, 0, 10, tzinfo=datetime.timezone.utc)

search.end_date
>>> None
```

--------------------------------

### Register SortExtension with StacApi

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/tips-and-tricks.md

Register the standard SortExtension to apply sorting and sortables to all endpoints (Item Search, OGC API Features, and Collection Search). If you omit the client argument, the extension degrades to the older specification, providing ?sortby support without /sortables endpoints.

```python
from stac_fastapi.api.app import StacApi
from stac_fastapi.extensions.sort import SortExtension

sortables_client = MySortablesClient()

api = StacApi(
    # ... other configurations ...
    extensions=[
        SortExtension(client=sortables_client)
    ]
)
```

--------------------------------

### Now: BadCoreClient returning JSONResponse when fields extension is enabled

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/migrations/v3.0.0.md

Shows the required v3.0 implementation. When the fields extension is enabled, post_search and get_search return a JSONResponse to avoid Item validation. For post_search, check search_request.fields; for get_search, check if 'fields' is in kwargs.

```python
# now
class BadCoreClient(BaseCoreClient):
    def post_search(
        self, search_request: BaseSearchPostRequest, **kwargs
    ) -> stac.ItemCollection:
        resp = {"not": "a proper stac item"}

        # if `fields` extension is enabled, then we return a JSONResponse
        # to avoid Item validation
        if getattr(search_request, "fields", None):
            return JSONResponse(content=resp)

        return resp

    def get_search(
        self,
        collections: Optional[List[str]] = None,
        ids: Optional[List[str]] = None,
        bbox: Optional[List[NumType]] = None,
        intersects: Optional[str] = None,
        datetime: Optional[Union[str, datetime]] = None,
        limit: Optional[int] = 10,
        **kwargs,
    ) -> stac.ItemCollection:
        resp = {"not": "a proper stac item"}

        # if `fields` extension is enabled, then we return a JSONResponse
        # to avoid Item validation
        if "fields" in kwargs:
            return JSONResponse(content=resp)

        return resp
```

--------------------------------

### Register custom operation labels with register_operations

Source: https://github.com/stac-utils/stac-fastapi/blob/main/docs/src/tips-and-tricks.md

Register explicit labels for extra routes (e.g., multi-tenant catalogs) before or at app construction. Unmatched /catalogs* paths fall back to operation="catalog".

```python
from stac_fastapi.api.metrics import register_operations

register_operations({
    ("GET", "/viewer"): "viewer",
    ("GET", "/catalogs/{catalog_id}/collections"): "list_collections",
})
```
Tokens:
Raw