Metadata-Version: 2.4
Name: stac-fastapi-geoparquet
Version: 0.0.6
Summary: A stac-fastapi implementation with a stac-geoparquet backend
Project-URL: Documentation, https://stac-utils.github.io/stac-fastapi-geoparquet
Project-URL: Github, https://github.com/stac-utils/stac-fastapi-geoparquet
Project-URL: Issues, https://github.com/stac-utils/stac-fastapi-geoparquet/issues
Project-URL: Changelog, https://github.com/stac-utils/stac-fastapi-geoparquet/blob/main/CHANGELOG.md
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Development Status :: 1 - Planning
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: attr>=0.3.2
Requires-Dist: fastapi>=0.115.8
Requires-Dist: geojson-pydantic>=1.2.0
Requires-Dist: obstore>=0.8.0
Requires-Dist: pydantic>=2.10.4
Requires-Dist: pystac>=1.13.0
Requires-Dist: rustac>=0.7.0
Requires-Dist: stac-fastapi-api>=5.0.2
Requires-Dist: stac-fastapi-extensions>=5.0.2
Requires-Dist: stac-fastapi-types>=5.0.2
Provides-Extra: lambda
Requires-Dist: mangum==0.21.0; extra == "lambda"
Provides-Extra: serve
Requires-Dist: uvicorn>=0.34.0; extra == "serve"
Dynamic: license-file

# stac-fastapi-geoparquet

[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/stac-utils/stac-fastapi-geoparquet/ci.yml?style=for-the-badge)](https://github.com/stac-utils/stac-fastapi-geoparquet/actions/workflows/ci.yml)
[![PyPI - Version](https://img.shields.io/pypi/v/stac-fastapi-geoparquet?style=for-the-badge)](https://pypi.org/project/stac-fastapi-geoparquet/)
[![GitHub License](https://img.shields.io/github/license/stac-utils/stac-fastapi-pgstac?style=for-the-badge)](https://github.com/stac-utils/stac-fastapi-geoparquet/blob/main/LICENSE)

A [stac-fastapi](https://github.com/stac-utils/stac-fastapi) with a [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet/blob/main/spec/stac-geoparquet-spec.md) backend.

**stac-fastapi-geoparquet** can serve a full-featured STAC API from one or more **stac-geoparquet** files located (e.g.) in blob storage — no database required.

> [!WARNING]
> 👷 This project is under active development and may change and break at any time.

## Usage

To start a STAC API server pointing to a single **stac-geoparquet** file:

```shell
$ python -m pip install 'stac-fastapi-geoparquet[serve]'
$ STAC_FASTAPI_GEOPARQUET_HREF=data/naip.parquet uvicorn stac_fastapi.geoparquet.main:app
INFO:     Started server process [47920]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```

This will start the server on <http://127.0.0.1:8000>.
The collection will be auto-generated from the items in the **stac-geoparquet** file.

### Using collections

Instead of providing the href to a single file, you can provide the href to a file containing a JSON list of collections.
Any [collection assets](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#assets) with a [application/vnd.apache.parquet](https://github.com/opengeospatial/geoparquet/blob/main/format-specs/geoparquet.md#media-type) `type` field will be added to the server as sources of items.
For an example, see [data/collections.json](./data/collections.json).

To start a server with one or more collections:

```shell
$ STAC_FASTAPI_COLLECTIONS_HREF=data/collections.json uvicorn stac_fastapi.geoparquet.main:app
INFO:     Started server process [47920]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```

To auto-generate the collections file, we provide a [script](./scripts/generate-collections):

```shell
scripts/generate-collections s3://my-bucket/a.parquet s3://my-bucket/b.parquet
```

This will update `./data/collections.json`.

### Limitations

- Currently, only supports one collection per file (tracking issue: <https://github.com/stac-utils/stac-fastapi-geoparquet/issues/27>)

## Development

Get [uv](https://docs.astral.sh/uv/getting-started/installation/), then:

```shell
git clone git@github.com:stac-utils/stac-fastapi-geoparquet.git
cd stac-fastapi-geoparquet
uv sync
```

To run the tests:

```shell
uv run pytest
```
