Download STAC Assets using a variety of authentication schemes.
python -m pip install stac-asset
To use the command-line interface (CLI):
python -m pip install 'stac-asset[cli]'
We have a Python API and a command-line interface (CLI).
Here's how to download a STAC Item and all of its assets to the current working directory. The correct client will be guessed from the assets' href. Each asset's href will be updated to point to the local file.
import pystac
import stac_asset
import asyncio
async def main():
href = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json"
item = pystac.read_file(href)
item = await stac_asset.download_item(item, ".")
return item
asyncio.run(main())
If you're working in a fully synchronous application, you can use our blocking interface:
import stac_asset.blocking
href = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json"
item = pystac.read_file(href)
item = stac_asset.blocking.download_item(item, ".")
Note that the above will not work in some environments like Jupyter notebooks which already have their own asyncio
loop running.
To get around this, you can use nest_asyncio
.
Simply run the following before using any functions from stac_asset.blocking
.
import nest_asyncio
nest_asyncio.apply()
To download an item using the command line:
stac-asset download \
https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json
To download all assets from the results of a pystac-client search, and save the item collection to a file named item-collection.json
:
stac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \
-c landsat-c2-l2 \
--max-items 1 | \
stac-asset download > item-collection.json
If you'd like to only download certain assets, e.g. a preview image, you can use the include -i
flag:
stac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \
-c landsat-c2-l2 \
--max-items 1 | \
stac-asset download -i rendered_preview -q
By default, all assets are stored in a folder named after the item ID. To change this, you can use the -p
flag and specify a path template using PySTAC layout template variables:
stac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \
-c landsat-c2-l2 \
--max-items 1 | \
stac-asset download -i rendered_preview -p '${collection}'
See the documentation for more examples and complete API and CLI documentation.
This library comes with several clients, each tailored for a specific data provider model and authentication scheme. Some clients require some setup before use; they are called out in this table, and the details are provided below.
Name | Description | Notes |
---|---|---|
HttpClient |
Simple HTTP client without any authentication | |
S3Client |
Simple S3 client | Use requester_pays=True in the client initializer to enable access to requester pays buckets, e.g. USGS landsat's public AWS archive |
FilesystemClient |
Moves files from place to place on a local filesystem | Mostly used for testing |
PlanetaryComputerClient |
Signs urls with the Planetary Computer Authentication API | No additional setup required, works out of the box |
EarthdataClient |
Uses a token-based authentication to download data, from some Earthdata providers, e.g. DAACs | Requires creation of a personal access token, see docs |
For information about configuring each client, see the API documentation for that client.
This project does its best to adhere to semantic versioning.
Any module, class, constant, or function that does not begin with a _
is considered part of our public API for versioning purposes.
Our command-line interface (CLI) is NOT considered part of our public API, and may change in breaking ways at any time.
If you need stability promises, use our API.
Use Github issues to report bugs and request new features. Use Github pull requests to fix bugs and propose new features.
Install uv. Then clone, sync, and install pre-commit:
git clone git@github.com:stac-utils/stac-asset.git
cd stac-asset
uv sync
pre-commit install
Some network-touching tests are disabled by default. To enable these tests:
uv run pytest --network-access
Some tests are client-specific and need your environment to be configured correctly. See each client's documentation for instructions on setting up your environment for each client.
To build:
make -C docs html && open docs/_build/html/index.html
It can be handy to use sphinx-autobuild if you're doing a lot of doc work:
uv pip install sphinx-autobuild
sphinx-autobuild --watch src docs docs/_build/html