Search the AQUAVIEW catalog — a comprehensive collection of 268K+ global oceanographic, atmospheric, and marine datasets from 15 sources (NOAA, NDBC, IOOS, WOD, CoastWatch, etc.), intended for scientific research, data analysis, and environmental monitoring.
This searches METADATA — which datasets exist. To pull the actual observations
(temperature profiles, buoy readings, float positions), use get_data instead;
list_data_sources shows which sources support it.
You must provide at least one of: q, bbox, datetime, collections, filter, or token.
Hint: When the user asks for a region, prefer the 'bbox' parameter over including region name in 'q'. Use the geo_hints resource for common bounding boxes.
Args:
q: Free-text search across title, description, and keywords (e.g., "sea surface temperature"). Case-insensitive, OR logic across terms.
bbox: Bounding box as "west,south,east,north" (e.g., "-98,24,-80,31" for Gulf of Mexico).
datetime: Temporal filter. Single datetime, range ("2020-01-01T00:00:00Z/2024-12-31T23:59:59Z"), or open-ended ("../2024-01-01T00:00:00Z" or "2020-01-01T00:00:00Z/..").
collections: Comma-separated collection IDs to search within (e.g., "NOAA,NDBC,WOD"). Use list_collections to see available IDs.
exclude_collections: Comma-separated collection IDs to omit from results (e.g., "INCIDENT_NEWS" to drop oil-spill reports from free-text searches). Applied as a CQL2 NOT filter, so it composes with `filter`.
filter: CQL2-JSON filter as an object or JSON-encoded string. Supports flat and nested property paths. Flat example: {"op": "=", "args": [{"property": "aquaview:institution"}, "NOAA/NCEI"]}. Nested example (filter by per-variable stats summary): {"op": "<=", "args": [{"property": "aquaview:column_stats_summary.variables.Pressure.min"}, 10]}. Supported operators: =, <>, <, >, <=, >=, like, between, in, and, or, not.
license: Comma-separated SPDX license id(s) to match exactly (e.g., "CC-BY-4.0,CC0-1.0"). Also accepts the
Parametersqbboxlimittokenfieldsfiltersortbylicensedatetimecollectionsoutput_formatinclude_assets+1 more
Fetch a single AQUAVIEW dataset item with full details, properties, and download links (assets).
STAC items embed assets inline — each asset includes an href (download URL) and media type, so there is no need for a separate "files" call.
Args:
collection: The collection ID the item belongs to (e.g., "NOAA", "NDBC", "WOD"). Available from search results or list_collections.
item_id: The unique item identifier (e.g., "wod_xbt_ZZ144579"). Available from search results.
output_format: "toon" (default) or "json".
Returns:
Full STAC item with geometry, properties (title, description, datetime, institution, variables, per-variable descriptions under aquaview:variable_descriptions when available, etc.), and assets (download links with media types).
Parametersitem_idrequiredcollectionrequiredoutput_format
List all available AQUAVIEW data collections (sources).
Returns a summary of each collection with ID, title, description, spatial/temporal extent, and keywords. Use collection IDs to filter searches.
These are CATALOG collections. Several are also queryable row by row — see
list_data_sources for the sources get_data can pull observations from.
A collection's bbox and temporal range are OUTER BOUNDS, not a promise of
coverage. They are the envelope around everything in the collection, so
most of the box usually holds no data at all — an Argo collection spans
the global ocean, a partner collection with one point either side of the
date line spans the whole planet. An empty result for a point or window
inside the extent is the normal answer, not a failure: report "no data
there", not "the query did not work", and do not widen a search on the
strength of a bbox alone.
Args:
tag: Only collections with this tag, e.g. "uxs" for uncrewed systems. Pass the returned IDs as `collections` to search_datasets to search only those.
output_format: "csv" (default, sectioned CSV — ~20% fewer tokens than TOON for this tabular response), "json", or "toon". Use "json" for deterministic/structured consumers.
Returns:
List of collections with count. CSV mode emits a single `## collections`
section with columns id,title,bbox,temporal,keywords,description;
bbox is rendered as "west,south,east,north"; temporal as "min|max";
keywords ";"-joined.
Parameterstagoutput_format
Run aggregation queries on the AQUAVIEW catalog — get counts, spatial distributions, temporal distributions, and per-collection breakdowns without fetching individual items.
Args:
aggregations: Comma-separated aggregation types (required). Valid types: total_count, datetime_max, datetime_min, datetime_frequency, collection_frequency, geometry_geohash_grid_frequency, geometry_geotile_grid_frequency.
collections: Comma-separated collection IDs to scope the aggregation (e.g., "NOAA,NDBC").
exclude_collections: Comma-separated collection IDs to omit from the aggregation (e.g., "INCIDENT_NEWS"). Applied as a CQL2 NOT filter, so it composes with `filter`.
bbox: Bounding box as "west,south,east,north".
datetime: Temporal filter (same format as search_datasets).
q: Free-text search to scope the aggregation. Multi-word queries are tokenised on whitespace and OR-combined to mirror search_datasets semantics (aggregate compiles q to CQL2 LIKE clauses on title/description; a raw %multi word% substring match would return 0 for most queries).
filter: CQL2-JSON filter as an object or JSON-encoded string. Flat example: {"op": "=", "args": [{"property": "aquaview:institution"}, "NOAA"]}. Nested example: {"op": "<=", "args": [{"property": "aquaview:column_stats_summary.variables.Pressure.min"}, 10]}.
license: Comma-separated SPDX license id(s) to scope the aggregation (e.g., "CC-BY-4.0,CC0-1.0"), or one of "public-domain", "proprietary", "various", "unknown". Matched against `aquaview:license`.
precision: Grid precision for geo aggregations (1-12, higher = finer grid). Applied to whichever geo aggregation type is requested.
datetime_frequency_interval: Interval for datetime_frequency (e.g., "month", "year", "day").
output_format: "csv" (default, sectioned CSV — ~50% fewer tokens than TOON for bucket responses), "json" (structured STAC API response), or "toon". Use "json" for deterministic/structured consumers.
Returns:
Aggregation resu
Parametersqbboxfilterlicensedatetimeprecisioncollectionsaggregationsrequiredoutput_formatexclude_collectionsdatetime_frequency_interval
List the AQUAVIEW data sources you can pull actual rows from, or describe one in detail.
Call this BEFORE get_data on a source you have not used. Variable names are
canonical per source and cannot be guessed — this is where they come from.
With an API key, sources your account is entitled to appear here too.
Args:
source_id: Omit to list every visible source. Give one (e.g. "gadr") to get its
full detail: canonical variable names, units, row limits, and filterable columns.
output_format: 'csv' (compact, default), 'json', or 'toon'.
Parameterssource_idoutput_format
Pull actual observation rows from an AQUAVIEW data source — not catalog metadata.
Use this whenever the question needs the measurements themselves (temperature
profiles, float positions, buoy readings), rather than which datasets exist.
Call list_data_sources first for a source's canonical variable names, its
`qc_modes`, and its `engine` (gridded "xarray" sources have no rows to pull).
READ 'returned' FIRST. It is one of three values:
- 'complete': 'rows' holds EVERY matching row (or your whole 'limit'). Safe
to compute anything from.
- 'head': 'rows' holds the FIRST rows in the source's natural order (see
'head.order'), out of 'head.of' total. These are not a random sample —
later rows differ systematically — so never average or take a maximum
from them. To get more, set 'limit' up to 'head.max_inline'; beyond that,
narrow the request or fetch 'download_url'.
- 'none': no rows. 'refusal.reason' says why. 'unscoped_query' means add a
bbox/datetime/depth/filter. 'no_natural_order' means the source has no
column to order a partial read by, so no partial set can be given
honestly — narrow until it fits, or use 'stats'. The rest are
transient; retry.
OTHER FIELDS:
- 'stats': exact minimum, maximum, mean and spread computed over EVERY
matching row. Use these for any numeric claim — exact at any data size.
- 'stats_basis': what shaped those numbers. If 'qc' is null the values are
UNSCREENED and may include implausible outliers from bad sensor readings;
say so, or re-run with a quality filter. When a mode was applied,
'qc_screened' lists the variables it actually checked — a variable not
in it was NOT flag-checked, and an empty list means nothing was
screened despite 'qc' naming a mode. 'qc_note', when present, explains
that the screen drops whole rows, so it shapes every variable's figures.
- 'structure': how many distinct floats/stations/profiles matched — often
the real answer ("16 profil
Parametersqcbboxdepthlimitformatsourcerequiredfiltersdatetimevariablesrequiredoutput_formatinclude_sample
