search-stac

name	search-stac
description	Search and download satellite imagery from Microsoft Planetary Computer. Browse available collections, search by bbox and time range, list assets, and download specific items.
argument-hint	<collection|list> [--bbox <minx,miny,maxx,maxy>] [--datetime <range>] [--download] [--output DIR]
allowed-tools	Bash

You are helping the user search and download satellite imagery from the Planetary Computer STAC catalog using geoai.

Input: $@

Follow these steps in order.

Step 1 -- Determine the action

Parse $@ to identify what the user wants:

• If the input is list, collections, or asks "what is available": list collections.
• If a collection name and --bbox are provided: search for items.
• If --download is present: download items after searching.

Step 2 -- List collections (if requested)

python3 -c "
import geoai
df = geoai.pc_collection_list()
print(df.to_string())
"

If the user provided a filter keyword, pass it:

python3 -c "
import geoai
df = geoai.pc_collection_list(filter_by='FILTER')
print(df.to_string())
"

Report the available collections and stop (unless the user also specified a search).

Step 3 -- Search for items

Parse the collection name, bounding box (--bbox), and optional datetime range (--datetime).

The datetime range should be in the format YYYY-MM-DD/YYYY-MM-DD (start/end).

python3 -c "
import geoai

items = geoai.pc_stac_search(
    collection='COLLECTION',
    bbox=[MINX, MINY, MAXX, MAXY],
    time_range='TIME_RANGE',
    limit=LIMIT,
)
print(f'Found {len(items)} items')
print('---')
for item in items[:20]:
    assets = list(item.assets.keys())
    print(f'  {item.id}: {item.datetime} - assets: {assets}')
"

Replace COLLECTION, MINX, MINY, MAXX, MAXY, TIME_RANGE, and LIMIT with actual values. Use limit=10 by default.

If time_range was not specified, omit it or pass None.

Step 4 -- List assets for an item (optional)

If the user asks about available assets or bands for a specific item:

python3 -c "
import geoai
assets = geoai.pc_item_asset_list(item_id='ITEM_ID', collection='COLLECTION')
for name, info in assets.items():
    print(f'  {name}: {info}')
"

Step 5 -- Download items (if --download flag or user confirms)

python3 -c "
import geoai, os

items = geoai.pc_stac_search(
    collection='COLLECTION',
    bbox=[MINX, MINY, MAXX, MAXY],
    time_range='TIME_RANGE',
    limit=LIMIT,
)

output_dir = 'OUTPUT_DIR'
os.makedirs(output_dir, exist_ok=True)

result = geoai.pc_stac_download(
    items,
    output_dir=output_dir,
)
print(f'Downloaded to: {output_dir}')
for f in os.listdir(output_dir):
    fpath = os.path.join(output_dir, f)
    if os.path.isfile(fpath):
        size_mb = os.path.getsize(fpath) / (1024 * 1024)
        print(f'  {f} ({size_mb:.1f} MB)')
"

Default output directory: ./stac_data/

Step 6 -- Report and suggest follow-ups

Summarize the search or download results. Then suggest:

• "Use /geoai-skills:inspect-geo to examine any downloaded files."
• "Use /geoai-skills:process-raster to clip or mosaic the imagery."

Error handling

• import geoai fails -> delegate to /geoai-skills:install-geoai.
• Invalid collection name -> list available collections and suggest the closest match.
• No items found -> suggest expanding the bbox, adjusting the date range, or trying a different collection.
• Download failure -> report the error and suggest retrying with fewer items.