Skip to content

t.stac.item

Downloads and imports data from a STAC API server.

t.stac.item [-miadp] url=string collection_id=string [request_method=string] [settings=name] [max_items=integer] [limit=integer] [ids=string] [bbox=float [,float,...]] [intersects=name] [datetime=string] [query=string] [filter=string] [asset_keys=string [,string,...]] [item_roles=string [,string,...]] [filter_lang=string] [sortby=string] [format=string] [strds_output=name] [items_vector=string] [method=string] [resolution=string] [resolution_value=float] [extent=string] [nprocs=integer] [memory=memory in MB] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

t.stac.item url=string collection_id=string

grass.script.parse_command("t.stac.item", url, collection_id, request_method="POST", settings=None, max_items=1000, limit=100, ids=None, bbox=None, intersects=None, datetime=None, query=None, filter=None, asset_keys=None, item_roles=None, filter_lang=None, sortby=None, format="json", strds_output=None, items_vector=None, method="nearest", resolution="estimated", resolution_value=None, extent="input", nprocs=1, memory=300, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.parse_command("t.stac.item", url="string", collection_id="string")

Parameters

url=string [required]
    STAC API Client URL
collection_id=string [required]
    Collection Id.
request_method=string
    The HTTP method to use when making a request to the service.
    Allowed values: GET, POST
    Default: POST
settings=name
    Full path to settings file (user, password)
    '-' for standard input
max_items=integer
    The maximum number of items to return from the search, even if there are more matching results.
    Default: 1000
limit=integer
    A recommendation to the service as to the number of items to return per page of results. Defaults to 100.
    Default: 100
ids=string
    List of one or more Item ids to filter on.
bbox=float [,float,...]
    The bounding box of the request in WGS84 (example [-72.5,40.5,-72,41]). (default is current region)
intersects=name
    Name of input vector map
    Results filtered to only those intersecting the geometry.
datetime=string
    Datetime Filter
    Either a single datetime or datetime range used to filter results.
query=string
    List or JSON of query parameters as per the STAC API query extension.
filter=string
    JSON of query parameters as per the STAC API filter extension
asset_keys=string [,string,...]
    Asset Keys
    List of one or more asset keys to filter item downloads.
item_roles=string [,string,...]
    Item roles
    List of one or more item roles to filter by.
filter_lang=string
    Language variant used in the filter body. If filter is a dictionary or not provided, defaults to cql2-json. If filter is a string, defaults to cql2-text.
    Allowed values: cql2-json, cql2-text
sortby=string
    A single field or list of fields to sort the response by
format=string
    Output format
    Allowed values: json, plain
    Default: json
strds_output=name
    STRDS Output
    Spatial Temporal Raster Dataset Registration File
items_vector=string
    Name of vector containing STAC item boundaries and metadata.
method=string
    Resampling method to use for reprojection (required if location projection not longlat)
    Allowed values: nearest, bilinear, bicubic, lanczos, bilinear_f, bicubic_f, lanczos_f
    Default: nearest
    nearest: nearest neighbor
    bilinear: bilinear interpolation
    bicubic: bicubic interpolation
    lanczos: lanczos filter
    bilinear_f: bilinear interpolation with fallback
    bicubic_f: bicubic interpolation with fallback
    lanczos_f: lanczos filter with fallback
resolution=string
    Resolution of output raster map (default: estimated)
    Allowed values: estimated, value, region
    Default: estimated
    estimated: estimated resolution
    value: user-specified resolution
    region: current region resolution
resolution_value=float
    Resolution of output raster map (use with option resolution=value)
extent=string
    Output raster map extent
    Allowed values: input, region
    Default: input
    input: extent of input map
    region: extent of current region
nprocs=integer
    Number of threads for parallel computing
    Default: 1
memory=memory in MB
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Default: 300
-m
    Collection Search Item Summary
-i
    Item metadata
-a
    Asset metadata
-d
    Dowload and import assets
-p
    Pretty print the JSON output
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

url : str, required
    STAC API Client URL
collection_id : str, required
    Collection Id.
request_method : str, optional
    The HTTP method to use when making a request to the service.
    Allowed values: GET, POST
    Default: POST
settings : str, optional
    Full path to settings file (user, password)
    '-' for standard input
    Used as: input, file, name
max_items : int, optional
    The maximum number of items to return from the search, even if there are more matching results.
    Default: 1000
limit : int, optional
    A recommendation to the service as to the number of items to return per page of results. Defaults to 100.
    Default: 100
ids : str, optional
    List of one or more Item ids to filter on.
bbox : float | list[float] | str, optional
    The bounding box of the request in WGS84 (example [-72.5,40.5,-72,41]). (default is current region)
intersects : str, optional
    Name of input vector map
    Results filtered to only those intersecting the geometry.
    Used as: input, vector, name
datetime : str, optional
    Datetime Filter
    Either a single datetime or datetime range used to filter results.
query : str, optional
    List or JSON of query parameters as per the STAC API query extension.
filter : str, optional
    JSON of query parameters as per the STAC API filter extension
asset_keys : str | list[str], optional
    Asset Keys
    List of one or more asset keys to filter item downloads.
item_roles : str | list[str], optional
    Item roles
    List of one or more item roles to filter by.
filter_lang : str, optional
    Language variant used in the filter body. If filter is a dictionary or not provided, defaults to cql2-json. If filter is a string, defaults to cql2-text.
    Allowed values: cql2-json, cql2-text
sortby : str, optional
    A single field or list of fields to sort the response by
format : str, optional
    Output format
    Allowed values: json, plain
    Default: json
strds_output : str, optional
    STRDS Output
    Spatial Temporal Raster Dataset Registration File
    Used as: output, file, name
items_vector : str, optional
    Name of vector containing STAC item boundaries and metadata.
method : str, optional
    Resampling method to use for reprojection (required if location projection not longlat)
    Allowed values: nearest, bilinear, bicubic, lanczos, bilinear_f, bicubic_f, lanczos_f
    nearest: nearest neighbor
    bilinear: bilinear interpolation
    bicubic: bicubic interpolation
    lanczos: lanczos filter
    bilinear_f: bilinear interpolation with fallback
    bicubic_f: bicubic interpolation with fallback
    lanczos_f: lanczos filter with fallback
    Default: nearest
resolution : str, optional
    Resolution of output raster map (default: estimated)
    Allowed values: estimated, value, region
    estimated: estimated resolution
    value: user-specified resolution
    region: current region resolution
    Default: estimated
resolution_value : float, optional
    Resolution of output raster map (use with option resolution=value)
extent : str, optional
    Output raster map extent
    Allowed values: input, region
    input: extent of input map
    region: extent of current region
    Default: input
nprocs : int, optional
    Number of threads for parallel computing
    Default: 1
memory : int, optional
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Used as: memory in MB
    Default: 300
flags : str, optional
    Allowed values: m, i, a, d, p
    m
        Collection Search Item Summary
    i
        Item metadata
    a
        Asset metadata
    d
        Dowload and import assets
    p
        Pretty print the JSON output
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

t.stac.item is a tool for exploring and importing SpatioTemporal Asset Catalog item metadata and assets into GRASS GIS. The tool is based on the PySTAC_Client (0.8) library and allows you to search items in a STAC Catalog. The search can be done by specifying the item ID, collection ID, datatime or by using a search query. The full list of search parameters and documentation can be found at PySTAC_Client ItemSearch.

NOTES

The t.stac.item tool is part of the t.stac temporal data processing framework. The tool requries that the data provider has implement the STAC API and conforms to Item Search specification.

REQUIREMENTS

EXAMPLES

Get the item metadata from a STAC API

    t.stac.catalog url="https://earth-search.aws.element84.com/v1/"
    t.stac.collection url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a"
    t.stac.item -i url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a" item_id="S2B_36QWD_20220301_0_L2A"

Get the asset metadata from a STAC API

    t.stac.catalog url="https://earth-search.aws.element84.com/v1/"
    t.stac.collection url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a"
    t.stac.item -a url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a" item_id="S2B_36QWD_20220301_0_L2A"

Use datetime filter

    t.stac.item url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a" datetime=2017-06-10/2017-06-11

Use query option

    t.stac.item url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a" query='{"eo:cloud_cover":{"lt":10}}'

To read more about query option please look at pystac_client documentation

Dpwnload the asset from a STAC API

    t.stac.item -d url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a" item_id="S2B_36QWD_20220301_0_L2A"

Download and import filtering by asset

    t.stac.item url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a" query='{"eo:cloud_cover":{"lt":10}}' asset=red,nir

SEE ALSO

Requirements t.stac.collection, t.stac.catalog

GRASS GIS Wiki: temporal data processing

AUTHORS

Corey T. White

Sponsors

Center for Geospatial Analytics at North Carolina State University

SOURCE CODE

Available at: t.stac.item source code (history)
Latest change: Tuesday Apr 01 23:14:57 2025 in commit 814b39c