Python API for stac-rs v0.1

  • 20th Sep 2024
  •  • 
  • 2 min read
  •  • 
  • Tags: 
  • python
  • stac

stac-rs has a simple, no-dependency Python API installable from PyPI:

pip install stacrs

The API documentation is available here. This Python API is intended to complement, not replace, existing Python packages such as pystac and pystac-client by providing functionality that those packages don't have.

stac-geoparquet

stac-geoparquet is a relatively new specification that describes how to store STAC items in GeoParquet. The specification repo also contains a reference implementation, mostly written in Python. stac-geoparquet was added to stac-rs in v0.9.0, and v0.1 of the Python package includes this capability:

import stacrs

item_collection = stacrs.read("items.parquet")
# do some work
stacrs.write("items.parquet", item_collection)

Note that these items are read as JSON dictionaries, which might not be the most efficient way to work with the data depending on your use case.

Object store

stacrs supports reading and writing from blob storage via object_store:

options = [("aws_access_key_id", "...")]
item = stacrs.read("s3://bucket/item.json", options=options)

Currently, credentials are provided via options, which can be a little awkward — we'd like to make that experience better in the future (e.g. via environment variables).

Searching into files

A common workflow for data analysis is to search a STAC API for a large number of items, save those items to a file (e.g. stac-geoparquet) then iteratively work with those items for more focused queries. stacrs supports that workflow with search_to:

stacrs.search_to("items.parquet",
    "https://landsatlook.usgs.gov/stac-server",
    collections=["landsat-c2l2-sr"],
    intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
    sortby="-properties.datetime",
    max_items=1000,
)
items = stacrs.read("items.parquet")
# Do some work

pystac compatability

If pystac exists on the system, stacrs.pystac provides functions that take and return pystac objects:

from pystac import ItemCollection

item_collection = stacrs.pystac.read("items.json")
assert isinstance(item_collection, ItemCollection)

Get in touch

If you're using the stacs Python package, or you'd like to use it, get in touch! I'm on Bluesky, or ask anything in the Github Discussions.