Tools

Eleven tools covering geocoding, weather forecasts, historical climate, probabilistic ensemble forecasts, marine conditions, air quality, terrain elevation, river discharge, CMIP6 climate projections, and SQL analytics over large datasets:

openmeteo_search_locations

Resolve a free-text place name to ranked coordinate matches. Required first step for name-based queries — all weather tools accept latitude/longitude, not place names.

• Returns name, country, admin1/admin2, latitude, longitude, elevation, IANA timezone, population, and GeoNames feature code
• Search by a bare place name — a city, region, or landmark ("Baoding", not "Baoding Hebei"; "Paris", not "Paris, France"); a compound "City Region" or "City, Country" string matches nothing
• Disambiguate same-named places (e.g., "Springfield") with the optional country filter (ISO 3166-1 alpha-2, e.g. US) or by raising count (default 5, up to 10) and reading the admin1/country fields on each result — those are output fields for choosing among matches, not search inputs
• Pass the timezone from an openmeteo_search_locations result directly to weather tools as the timezone parameter
• Fails with a no_results error (not an empty array) when nothing matches — retry the bare place name without qualifiers, or for a physical feature/landmark search the nearest populated place instead

openmeteo_get_forecast

Weather forecast for a coordinate pair with hourly and/or daily variable selection.

• Up to 16 forecast days ahead (forecast_days 1–16, default 7)
• past_days (0–92) covers recent history via the forecast model — use instead of openmeteo_get_historical for dates within the last ~5 days to avoid ERA5 lag
• Common hourly variables: temperature_2m, precipitation, wind_speed_10m, relative_humidity_2m, cloud_cover, uv_index, apparent_temperature, precipitation_probability, weather_code, surface_pressure, visibility, wind_direction_10m, wind_gusts_10m, dew_point_2m
• Common daily variables: temperature_2m_max, temperature_2m_min, precipitation_sum, wind_speed_10m_max, sunrise, sunset, uv_index_max, precipitation_hours, weather_code
• At least one of hourly_variables or daily_variables is required
• Hourly and daily are separate variable sets. A variable Open-Meteo documents under the other cadence is rejected before the request, by name, with the field it belongs in and the same-cadence alternatives (cloud_cover in daily_variables → cloud_cover_max/_mean/_min). Names in neither set are passed upstream unchanged
• Configurable temperature unit (Celsius/Fahrenheit), wind speed unit (km/h, mph, m/s, knots), and precipitation unit (mm/inch)
• Reshapes the API's columnar response into per-timestamp records with a parallel hourly_units / daily_units map
• A wide window (a large past_days plus many hourly variables) spills to DataCanvas when CANVAS_PROVIDER_TYPE=duckdb — output includes canvas_id and truncated: true; query with openmeteo_dataframe_query

openmeteo_get_historical

Historical weather from the ERA5 reanalysis archive, covering 1940 to approximately 5 days ago.

• Requires start_date and end_date (YYYY-MM-DD); ERA5 has a variable ~1–5 day lag
• Same variable vocabulary as openmeteo_get_forecast — past and forecast data are directly comparable on one schema
• At least one of hourly_variables or daily_variables is required
• Hourly and daily are separate variable sets; a variable documented under the other cadence is rejected before the request, by name, with the field it belongs in
• Large date ranges (multi-year hourly queries) spill to DataCanvas when CANVAS_PROVIDER_TYPE=duckdb — output includes canvas_id and truncated: true whenever a result is too large to return inline, which a wide multi-variable pull can be at any row count
• Spill → query workflow: call openmeteo_dataframe_describe with the canvas_id to list tables, then openmeteo_dataframe_query to run SQL SELECT against the staged data

openmeteo_get_marine

Marine wave and ocean conditions for coastal and open-ocean coordinates.

• Up to 8 forecast days (forecast_days 1–8, upstream default 7) with optional past_days (0–92)
• Or an archive range via start_date and end_date — real wave values go back to at least 2022
• One window per call: a date range is mutually exclusive with forecast_days/past_days, and needs both ends — a lone start_date or end_date is rejected
• Common hourly variables: wave_height, wave_direction, wave_period, wind_wave_height, wind_wave_direction, wind_wave_period, swell_wave_height, swell_wave_direction, swell_wave_period
• Common daily variables: wave_height_max, wave_direction_dominant, wave_period_max
• At least one of hourly_variables or daily_variables is required
• Hourly and daily are separate variable sets; a variable documented under the other cadence is rejected before the request, by name, with the field it belongs in
• Inland or sheltered-water points return near-zero wave values (physically correct); ocean_current_velocity is null for non-open-ocean coordinates
• Wide windows spill to DataCanvas when CANVAS_PROVIDER_TYPE=duckdb — output includes canvas_id and truncated: true; query with openmeteo_dataframe_query

openmeteo_get_air_quality

Modeled CAMS air quality, forecast and archive.