search_imagery
Search satellite imagery catalogs for scenes over a location and date window, filtering by cloud cover and event coverage to find usable pre/post-event imagery.
Instructions
Search the satellite imagery catalog (Sentinel-1/2, OPERA RTC-S1) for scenes over an area and date window — the natural follow-up to a signal (find imagery over the event location). Returns scene metadata (id, datetime, footprint, cloud cover, platform, orbit geometry, coverage, catalog link) — no imagery bytes. Pass eventDate to classify each scene timing=pre/post/same_day_unknown (a same-day scene is same_day_unknown, never post, without a real event time) and get pre/post bracketing + window_status + SAR sar_pair_status in meta. Pass eventPoint [lon,lat] and/or eventAoi [minLon,minLat,maxLon,maxLat] to get each scene's target_relation (covers_event_geometry = pure geometry gate; usable_for_analysis additionally requires acceptable cloud for optical, so a 99%-cloud scene is geometry-covering but not analysis-usable) — so a scene that only clips the wide bbox is not mistaken for covering the event. Costs 2 token(s) per call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bbox | Yes | Bounding box [minLon, minLat, maxLon, maxLat] (WGS84). Required. | |
| date | No | Window end date, YYYY-MM-DD (UTC). Defaults to today. | |
| days | No | Window length in days. Defaults to 7. | |
| limit | No | Max scenes to return. Defaults to 25. | |
| eventAoi | No | Event AOI bbox [minLon, minLat, maxLon, maxLat] (WGS84). Drives target_relation.intersects_event_aoi / event_aoi_coverage_ratio. | |
| eventDate | No | Event date, YYYY-MM-DD (UTC). When set, each scene is tagged timing=pre/post/same_day_unknown and the search window is widened to the canonical pre/post span, so meta reports has_pre_baseline / has_post / bracketing_available / window_status; for sentinel-1-grd it also reports sar_pair_status (ready | not_ready | indeterminate_event_time) + orbit_note. | |
| collection | No | Catalog collection. Defaults to sentinel-2-l2a. | |
| eventPoint | No | Event point [lon, lat] (WGS84). When set, each scene reports target_relation.covers_event_point / usable_for_event so a scene that only clips the wide bbox is not presented as covering the event. | |
| cloudCoverMax | No | Sentinel-2 only: max cloud cover %. | |
| eventTimestamp | No | Full event timestamp (ISO 8601) when known — promotes same-day scenes from same_day_unknown to pre/post by time. | |
| responseFormat | No | Per-scene field detail. "concise" (default) returns id, collection, datetime, timing, cloud_cover, platform, orbit_state, relative_orbit, instrument_mode, product_type, coverage_ratio, covers_event_point, usable_for_event, stac_item_url, preview. "detailed" adds the full footprint bbox/geometry, the complete target_relation, constellation, polarizations, absolute_orbit, incidence_angle, and non-signed asset hrefs. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| meta | Yes | Query echo, token charge/balance (meta.tokens), and pagination where applicable. | |
| scenes | Yes | ||
| summary | No | One-line natural-language summary of the result, ready to relay to a user. |