Python library for working with Spatiotemporal Asset Catalog (STAC).
Project description
STAC API Client
A Python client for working with STAC Catalogs and APIs.
Installation
Install from PyPi. Other than PySTAC itself, the only dependency for pystac-client is the Python requests library.
pip install pystac-client
Usage
pystac-client can be used as either a CLI or a Python library.
CLI
Use the CLI to quickly make searches and output or save the results.
$ stac-client search --url https://earth-search.aws.element84.com/v0 -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41
1999 items matched
The environment variable STAC_URL can be set instead of having to explicitly set the Catalog URL with every call:
$ export STAC_URL=https://earth-search.aws.element84.com/v0
$ stac-client search -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31
48 items matched
The CLI performs a search with limit=0 so does not get any Items, it only gets the count. To fetch the items use one or both of the --stdout or --save switches.
Specifying --stdout will fetch all items, paginating if necessary. If max_items is provided it will stop paging once that many items has been retrieved. It then prints all items to stdout as an ItemCollection. This can be useful to pipe output to another process such as stac-terminal, geojsonio-cli, or jq.
$ stac-client search --stdout -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 | stacterm cal --label platform
The --save switch will save all fetched items (as with --stdout) to a file.
$ stac-client search -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 --save items.json
If the Catalog supports the Query extension, any Item property can also be included in the search. Rather than requiring the JSON syntax the Query extension uses, pystac-client uses a simpler syntax that it will translate to the JSON equivalent.
<property><operator><value>
where operator is one of `>=`, `<=`, `>`, `<`, `=`
Examples:
eo:cloud_cover<10
created=2021-01-06
view:sun_elevation<20
Any number of properties can be included, and each can be included more than once to use additional operators.
$ stac-client search -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 -q "eo:cloud_cover<10"
10 items matched
Python
To use the Python library, first an API instance is created for a specific STAC API (use the root URL)
from pystac_client import Client
catalog = Client.open("https://earth-search.aws.element84.com/v0")
Create a search
mysearch = catalog.search(collections=['sentinel-s2-l2a-cogs'], bbox=[-72.5,40.5,-72,41], max_items=10)
print(f"{mysearch.matched()} items found")
Iterate through items
for item in mysearch.items():
print(item.id)
Save all found items as a single FeatureCollection
items = list(mysearch.items())
items.save('items.json')
Development
Build Docs
$ scripts/build-docs
Run Tests
$ scripts/test
or
$ pytest -v -s --cov pystac_client --cov-report term-missing
Lint
$ scripts/format
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file pystac-client-0.1.0.tar.gz.
File metadata
- Download URL: pystac-client-0.1.0.tar.gz
- Upload date:
- Size: 28.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/3.10.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.9.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 09cbe22917e8b00d300e44989bcbd2774cce496729241d11338598d73afa5af8 |
|
| MD5 | 0aba896aa9b4f385024d65fa07717360 |
|
| BLAKE2b-256 | bd3d2ece7e42e556d1fe17c4ef62f038b0b17ea75ab04344be79ea0862c5bbf3 |
Provenance
File details
Details for the file pystac_client-0.1.0-py3-none-any.whl.
File metadata
- Download URL: pystac_client-0.1.0-py3-none-any.whl
- Upload date:
- Size: 33.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/3.10.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.9.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | b88356c4fedc043469a29a60d648fcb28d8942b1db537237482acf4c58b95916 |
|
| MD5 | b9bf804b456b2232529b68494ef908a8 |
|
| BLAKE2b-256 | c7ce037848506cad7c57092c713069d8253546b50dac3a88eee534b675746645 |
