Note: This document is for an older version of GRASS GIS that has been discontinued. You should upgrade, and read the current manual page.

GRASS logo

NAME

t.stac.item - Downloads and imports data from a STAC API server.

KEYWORDS

raster, import, STAC, temporal

SYNOPSIS

t.stac.item
t.stac.item --help
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] [--help] [--verbose] [--quiet] [--ui]

Flags:

-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
--ui
Force launching GUI dialog

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.
Options: 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.
Options: cql2-json, cql2-text
sortby=string
A single field or list of fields to sort the response by
format=string
Output format
Options: 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)
Options: 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)
Options: 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
Options: 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

Table of contents

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"

Dpwnload the asset 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 -d url="https://earth-search.aws.element84.com/v1/" collection_id="sentinel-2-l2a" item_id="S2B_36QWD_20220301_0_L2A"
GRASS Jupyter Notebooks can be used to visualize the catalog metadata. 

    from grass import gs
    catalog = gs.parse_command('t.stac.catalog', url="https://earth-search.aws.element84.com/v1/")

    print(catalog)

    # Output
    {'conformsTo': ['https://api.stacspec.org/v1.0.0/core',
                'https://api.stacspec.org/v1.0.0/collections',
                'https://api.stacspec.org/v1.0.0/ogcapi-features',
                'https://api.stacspec.org/v1.0.0/item-search',
                'https://api.stacspec.org/v1.0.0/ogcapi-features#fields',
                'https://api.stacspec.org/v1.0.0/ogcapi-features#sort',
                'https://api.stacspec.org/v1.0.0/ogcapi-features#query',
                'https://api.stacspec.org/v1.0.0/item-search#fields',
                'https://api.stacspec.org/v1.0.0/item-search#sort',
                'https://api.stacspec.org/v1.0.0/item-search#query',
                'https://api.stacspec.org/v0.3.0/aggregation',
                'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core',
                'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30',
                'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson'],
 'description': 'A STAC API of public datasets on AWS',
 'id': 'earth-search-aws',
 'stac_version': '1.0.0',
 'title': 'Earth Search by Element 84',
 'type': 'Catalog'}

STAC Catalog plain text metadata


t.stac.catalog url=https://earth-search.aws.element84.com/v1/ format=plain

# Output
    Client Id: earth-search-aws
    Client Title: Earth Search by Element 84
    Client Description: A STAC API of public datasets on AWS
    Client STAC Extensions: []
    Client Extra Fields: {'type': 'Catalog', 'conformsTo': ['https://api.stacspec.org/v1.0.0/core', 'https://api.stacspec.org/v1.0.0/collections', 'https://api.stacspec.org/v1.0.0/ogcapi-features', 'https://api.stacspec.org/v1.0.0/item-search', 'https://api.stacspec.org/v1.0.0/ogcapi-features#fields', 'https://api.stacspec.org/v1.0.0/ogcapi-features#sort', 'https://api.stacspec.org/v1.0.0/ogcapi-features#query', 'https://api.stacspec.org/v1.0.0/item-search#fields', 'https://api.stacspec.org/v1.0.0/item-search#sort', 'https://api.stacspec.org/v1.0.0/item-search#query', 'https://api.stacspec.org/v0.3.0/aggregation', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson']}
    Client catalog_type: ABSOLUTE_PUBLISHED
    ---------------------------------------------------------------------------
    Collections: 9
    sentinel-2-pre-c1-l2a: Sentinel-2 Pre-Collection 1 Level-2A
    Sentinel-2 Pre-Collection 1 Level-2A (baseline < 05.00), with data and metadata matching collection sentinel-2-c1-l2a
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2015-06-27T10:25:31.456000Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------
    cop-dem-glo-30: Copernicus DEM GLO-30
    The Copernicus DEM is a Digital Surface Model (DSM) which represents the surface of the Earth including buildings, infrastructure and vegetation. GLO-30 Public provides limited worldwide coverage at 30 meters because a small subset of tiles covering specific countries are not yet released to the public by the Copernicus Programme.
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2021-04-22T00:00:00Z', '2021-04-22T00:00:00Z']]}}
    License: proprietary
    ---------------------------------------------------------------------------
    naip: NAIP: National Agriculture Imagery Program
    The [National Agriculture Imagery Program](https://www.fsa.usda.gov/programs-and-services/aerial-photography/imagery-programs/naip-imagery/) (NAIP) provides U.S.-wide, high-resolution aerial imagery, with four spectral bands (R, G, B, IR).  NAIP is administered by the [Aerial Field Photography Office](https://www.fsa.usda.gov/programs-and-services/aerial-photography/) (AFPO) within the [US Department of Agriculture](https://www.usda.gov/) (USDA).  Data are captured at least once every three years for each state.  This dataset represents NAIP data from 2010-present, in [cloud-optimized GeoTIFF](https://www.cogeo.org/) format.
    Extent: {'spatial': {'bbox': [[-160, 17, -67, 50]]}, 'temporal': {'interval': [['2010-01-01T00:00:00Z', '2022-12-31T00:00:00Z']]}}
    License: proprietary
    ---------------------------------------------------------------------------
    cop-dem-glo-90: Copernicus DEM GLO-90
    The Copernicus DEM is a Digital Surface Model (DSM) which represents the surface of the Earth including buildings, infrastructure and vegetation. GLO-90 provides worldwide coverage at 90 meters.
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2021-04-22T00:00:00Z', '2021-04-22T00:00:00Z']]}}
    License: proprietary
    ---------------------------------------------------------------------------
    landsat-c2-l2: Landsat Collection 2 Level-2
    Atmospherically corrected global Landsat Collection 2 Level-2 data from the Thematic Mapper (TM) onboard Landsat 4 and 5, the Enhanced Thematic Mapper Plus (ETM+) onboard Landsat 7, and the Operational Land Imager (OLI) and Thermal Infrared Sensor (TIRS) onboard Landsat 8 and 9.
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['1982-08-22T00:00:00Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------
    sentinel-2-l2a: Sentinel-2 Level-2A
    Global Sentinel-2 data from the Multispectral Instrument (MSI) onboard Sentinel-2
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2015-06-27T10:25:31.456000Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------
    sentinel-2-l1c: Sentinel-2 Level-1C
    Global Sentinel-2 data from the Multispectral Instrument (MSI) onboard Sentinel-2
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2015-06-27T10:25:31.456000Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------
    sentinel-2-c1-l2a: Sentinel-2 Collection 1 Level-2A
    Sentinel-2 Collection 1 Level-2A, data from the Multispectral Instrument (MSI) onboard Sentinel-2
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2015-06-27T10:25:31.456000Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------
    sentinel-1-grd: Sentinel-1 Level-1C Ground Range Detected (GRD)
    Sentinel-1 is a pair of Synthetic Aperture Radar (SAR) imaging satellites launched in 2014 and 2016 by the European Space Agency (ESA). Their 6 day revisit cycle and ability to observe through clouds makes this dataset perfect for sea and land monitoring, emergency response due to environmental disasters, and economic applications. This dataset represents the global Sentinel-1 GRD archive, from beginning to the present, converted to cloud-optimized GeoTIFF format.
    Extent: {'spatial': {'bbox': [[-180, -90, 180, 90]]}, 'temporal': {'interval': [['2014-10-10T00:28:21Z', None]]}}
    License: proprietary
    ---------------------------------------------------------------------------

Basic STAC catalog metadata


    t.stac.catalog url=https://earth-search.aws.element84.com/v1/ format=plain -b

    # Output
    Client Id: earth-search-aws
    Client Title: Earth Search by Element 84
    Client Description: A STAC API of public datasets on AWS
    Client STAC Extensions: []
    Client Extra Fields: {'type': 'Catalog', 'conformsTo': ['https://api.stacspec.org/v1.0.0/core', 'https://api.stacspec.org/v1.0.0/collections', 'https://api.stacspec.org/v1.0.0/ogcapi-features', 'https://api.stacspec.org/v1.0.0/item-search', 'https://api.stacspec.org/v1.0.0/ogcapi-features#fields', 'https://api.stacspec.org/v1.0.0/ogcapi-features#sort', 'https://api.stacspec.org/v1.0.0/ogcapi-features#query', 'https://api.stacspec.org/v1.0.0/item-search#fields', 'https://api.stacspec.org/v1.0.0/item-search#sort', 'https://api.stacspec.org/v1.0.0/item-search#query', 'https://api.stacspec.org/v0.3.0/aggregation', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30', 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson']}
    Client catalog_type: ABSOLUTE_PUBLISHED
    ---------------------------------------------------------------------------

AUTHENTICATION

The t.stac.catalog tool supports authentication with the STAC API using the GDAL's virtual fie system /vsi/.

Basic Authentication


    t.stac.catalog url="https://earth-search.aws.element84.com/v1/" settings="user:password"

AWS

AWS S3

Google Cloud Storage

Google Cloud Storage

Microsoft Azure

Microsoft Azure

HTTP

HTTP

SEE ALSO

Requirements t.stac.collection, t.stac.item

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)

Accessed: Tuesday Dec 17 06:49:39 2024

Main index | Temporal index | Topics index | Keywords index | Graphical index | Full index

© 2003-2024 GRASS Development Team, GRASS GIS 8.3.3dev Reference Manual