search_catalog
Search Umbra's catalog and return compact context cards.
Filters (all optional, combine freely): ``bbox`` as
``[min_lon, min_lat, max_lon, max_lat]`` in WGS84 degrees; ``intersects`` as
a GeoJSON object (a ``Point``, ``Polygon``, or ``MultiPolygon``, or a
``Feature`` / ``FeatureCollection`` wrapping one; a point matches footprints
that contain it) to keep only footprints
intersecting it -- a tighter spatial filter than the rectangular ``bbox``,
and mutually exclusive with ``bbox`` / ``place``; ``place`` as a
free-text name geocoded to a bbox; ``area`` as a substring of the Umbra
task (site) name (set ``fuzzy`` to match it loosely -- word-order- and
punctuation-independent and typo-tolerant, resolved deterministically with
no model call, so ``"beet piler"`` still reaches ``"Beet Piler - ND"`` and
``"utah centerfield"`` still reaches ``"Centerfield,
Utah"``). When ``area`` matches no task and ``bbox``, ``intersects``, and
``place`` are omitted, it is geocoded and that footprint is searched; the
result then adds ``matched_by`` (``geocode``), ``resolved_place``, and
``resolved_bbox``. A name Nominatim does not know sets ``hint`` to
``no task named X; try place= or bbox=``. When geocoding is busy (the
Nominatim gate, or the public host's quick outbound pool) or
unreachable, ``hint`` is ``no task named X; geocoding was unavailable``
and ``resolved_area`` is the ``area`` that was tried. A task-name hit
adds nothing. Set ``semantic``
instead to treat ``area`` as a plain-language
*description* of a site whose name you don't know and resolve it to the
closest task names by *meaning* via the prebuilt embedding index, so
``"grain storage north dakota"`` reaches ``"Beet Piler - ND"`` -- a query
that shares no word with the label, which ``fuzzy`` cannot and should not
fake; ``semantic`` and ``fuzzy`` are mutually exclusive, and the resolved
task name is returned as ``resolved_area`` with the ranked candidates in
``semantic_matches`` so you can audit and retry with a different one, and
``min_score`` -- a cosine threshold in ``[0, 1]`` -- drops weak aliases, so
a description that matches nothing confidently returns an empty result
rather than an arbitrary top pick); ``start``/``end`` as acquisition-date
bounds -- an ISO
``YYYY-MM-DD`` date, a bare year/month (``2024``, ``2024-03``), or a
relative expression (``today``, ``yesterday``, ``3 months ago``,
``last month``), resolved deterministically with no model call;
``products`` to restrict to product types
(any of GEC, SICD, SIDD, CPHD); the SAR acquisition-property filters
``polarizations`` (keep items exposing any of these, e.g. ``["VV"]`` -- the
filter that keeps a change comparison like-with-like), ``min_incidence`` /
``max_incidence`` (view incidence-angle bounds in degrees) and
``max_resolution`` (keep items at least this fine, in metres) -- each a hard
predicate that excludes items missing that metadata; ``canonical`` to keep
the preferred copy of a collect Umbra republished under another prefix
(``True``), only the other copies (``False``), or every item when omitted;
``limit`` to cap
results (on the public host a value above 100 is clamped to 100 and the
result includes ``note``; the argument and its default are unchanged);
``max_per_task`` to cap items per site (use 1 for a one-pin-per-site
overview).
``local`` selects the backend: leave it unset to use the on-disk index when
present (instant) and fall back to a live S3 walk otherwise. When the server
is configured with a Canopy token (``$UMBRA_CANOPY_TOKEN``), the search runs
against Umbra's authenticated commercial archive instead and ``source`` is
reported as ``"canopy-archive"``. Returns the per-item context cards, not
full STAC JSON, to protect the context window; call ``get_item`` for one
item's full metadata.
Prefer ``fuzzy=True`` (or :func:`find_repeat_sites`) when ``area`` shares
words with a task name; that path is deterministic and needs no key.
``semantic=True`` is only for a description that shares **no** tokens with
the label. It requires a task-embedding index built ahead of time with
``umbra semantic build`` and a user-supplied embedding key (``OPENAI_API_KEY``,
optionally ``OPENAI_BASE_URL`` / ``UMBRA_EMBED_MODEL``); it raises a helpful
setup error otherwise, so it never runs implicitly. The only model call is
turning ``area`` into a vector -- the resolved search over the chosen backend
stays fully deterministic.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "search_catalog"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Inclusive acquisition-date upper bound. Same grammar as start. | |
| area | No | Task-name substring. If it matches no task and bbox, intersects, and place are omitted, it is geocoded. With semantic, a plain-language description. | |
| bbox | No | WGS84 [min_lon, min_lat, max_lon, max_lat]. When set, place is not geocoded. | |
| fuzzy | No | Loose task-name match for area (word order, punctuation, typos). No model. Cannot be combined with semantic. | |
| limit | No | Maximum cards. Default 20. The public host clamps a value above 100 to 100 and adds note. | |
| local | No | True uses only the local index; False forces a live walk. Omit to use the index when present. True cannot be combined with a Canopy token. | |
| place | No | Free-text place name. Geocoded to a bbox only when bbox is omitted. | |
| start | No | Inclusive acquisition-date lower bound: ISO date, bare year or month, or a relative expression such as 3 months ago. | |
| products | No | Keep items that expose one of these types (GEC, CSI, SIDD, SICD, CPHD). A collection id such as umbra-gec or umbra-open-data raises; use the product type. | |
| semantic | No | Resolve area by embedding similarity. Needs a semantic index and an embedding key. Cannot be combined with fuzzy. | |
| canonical | No | True keeps the preferred copy of a republished collect; False keeps only the other copies. Omit to keep every item. | |
| min_score | No | Cosine cutoff in [0, 1] for semantic matches. Scores below it are dropped. | |
| intersects | No | One GeoJSON Point, or a Polygon or MultiPolygon, optionally wrapped in a Feature, FeatureCollection, or GeometryCollection. A point matches footprints that contain it. Cannot be combined with bbox or place. | |
| max_per_task | No | Maximum items per task (site). 1 is one pin per site. | |
| max_incidence | No | Maximum incidence angle in degrees. Items missing incidence are dropped. | |
| min_incidence | No | Minimum incidence angle in degrees. Items missing incidence are dropped. | |
| polarizations | No | Keep items exposing any listed polarization, such as VV. Missing values are dropped. | |
| max_resolution | No | Keep items this fine or finer, in metres. Items missing resolution are dropped. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||