Skip to main content

Python library for working with Spatiotemporal Asset Catalog (STAC).

Project description

STAC API Client

CI Release PyPI version Documentation codecov

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 --matched switch performs a search with limit=0 so does not get any Items, but gets the total number of matches which will be output to the screen.

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 --matched
48 items matched

Without the --matched switch, all items will be fetched, 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 -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 | stacterm cal --label platform

If the --save switch is provided instead, the results will not be output to stdout, but instead will be saved to the specified 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" --matched
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 = mysearch.items_as_collection()
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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pystac-client-0.1.1.tar.gz (29.2 kB view details)

Uploaded Source

Built Distribution

pystac_client-0.1.1-py3-none-any.whl (34.4 kB view details)

Uploaded Python 3

File details

Details for the file pystac-client-0.1.1.tar.gz.

File metadata

  • Download URL: pystac-client-0.1.1.tar.gz
  • Upload date:
  • Size: 29.2 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

Hashes for pystac-client-0.1.1.tar.gz
Algorithm Hash digest
SHA256 b39b7d318e7e1372d47336737fa19a5c6ce2c4ab2dd97153ad18c73a48e07111
MD5 9889d5961eebbfb85643a090122449ca
BLAKE2b-256 867652029df5cae6dc37fcd1590850daeedde222aae4198f6f6811725d224e66

See more details on using hashes here.

Provenance

File details

Details for the file pystac_client-0.1.1-py3-none-any.whl.

File metadata

  • Download URL: pystac_client-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 34.4 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

Hashes for pystac_client-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 6f02f0dc470decabad70cb65fd6b52cc524d8f2048c1858c463214cc93c1b9c8
MD5 459442917120cb38e4121d38b5a1b1c2
BLAKE2b-256 12f231896e7fefed83f372a30d49deafc2120034934af14c625892e68e853ee5

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page