Connection check
verified live · 26h ago
weathersight
Historical weather and climate: 100+ years of station data, normals, extremes, and trends.
Tools
18
GitHub stars
—
Installs / wk
—
Licence
—
Transport
streamable-http
Last checked
26h ago
Tools & capabilities
18 toolsRead from the running server on 26h ago.
anom
read-only
namelocidlatlonymd_end*ymd_start*period_type
+1
Returns observations with 1991–2020 baseline comparisons at daily, weekly, or monthly granularity for a location and period. <br><b>When to use:</b> Graph or tabulate recent anomal… Returns observations with 1991–2020 baseline comparisons at daily, weekly, or monthly granularity for a location and period. <br><b>When to use:</b> Graph or tabulate recent anomalies at a location for a specific period — e.g. 'how did last month compare to normal?' <br><b>Date format:</b> YYYYMMDD for ymd; use groupby (day/week/month) to control granularity. For 'last week' use YYYYMMDD of 7 days ago. For 'last month' use YYYYMM of prior month. <br><b>Performance:</b> Computed on demand; moderate speed. <br><b>Prerequisites:</b> Use /location to obtain a locid first. <br><b>Investigate:</b> Use after /anomalies or /breaking. Identifies a city of interest; provides per-day/week detail for drill-down. Combine groupby=DAY/FULL_DAY with a recent date range for 'recent days with departure from normal' queries. <br><b>Augment:</b> Provides the per-period anomaly series for prose ('temperatures were above normal for 12 of the past 14 days'). Returns: loc, ts, vals, N, vals_ts, baseline.
anomalies
read-only
zymd*namelocidscopectryid
+5
Returns precomputed anomalous observations for locations in a given time period and scope. <br><b>When to use:</b> Survey anomalous weather at regional or global scale quickly with… Returns precomputed anomalous observations for locations in a given time period and scope. <br><b>When to use:</b> Survey anomalous weather at regional or global scale quickly without specifying individual cities. <br><b>Date format:</b> YYYY[MM[DD]]: YYYY for annual anomalies (scope=year), YYYYMM for monthly (scope=month), YYYYMMDD for weekly or daily (scope=week/day). <br><b>Performance:</b> Fast — retrieves precomputed data. <br><b>Prerequisites:</b> None; global or country-filtered. Use /countries for country IDs. <br><b>Investigate:</b> Good early call to identify which locations experienced anomalies before drilling into specifics with /anom or /dailycomp. <br><b>Augment:</b> Use for a first-pass global scan to identify story-worthy anomalies before fetching per-location detail. Returns: anomalies, anomaly.locid, anomaly.lat, anomaly.long, anomaly.obs_start, anomaly.obs_end, anomaly.obs_dur, anomaly.base_start, anomaly.base_end, anomaly.base_dur, anomaly.obs_period, anomaly.base_period, anomaly.outliers, outlier.obs_metric, outlier.percentile, outlier.obs_N, outlier.obs_X, outlier.base_N, outlier.base_X, outlier.obs_val, outlier.base_val, outlier.base_mean, outlier.base_stddev, outlier.min, outlier.max, outlier.max_key, outlier.min_key, outlier.obs_min_key, outlier.obs_max_key.
bestplace
read-only
timescopectryidlatlonbaselinecriteria*
+2
Given a single week, month, or day, ranks locations whose weather best matches a set of criteria (most optional criteria met first; all MUST criteria satisfied by every result). Fi… Given a single week, month, or day, ranks locations whose weather best matches a set of criteria (most optional criteria met first; all MUST criteria satisfied by every result). Filter by lat/lon+radius or countries. <br><b>When to use:</b> Answer 'where has the best weather for week/month/day X?' <br><b>Date format:</b> scope=day + time=YYYYMMDD (forecast); scope=week + time=MMDD; scope=month + time=MM. Defaults: week of today+14, month today+1, day today+1. <br><b>Performance:</b> Filter by area/countries to keep fast. <br><b>Prerequisites:</b> None; supply lat/lon+radius_km or a country list. <br><b>Investigate:</b> Rank places for a given time window. scope=day uses forecasts. <br><b>Augment:</b> Find the best destinations for a target week/month. <br><b>Notes:</b> Every criterion metric name is literal and fully qualified: the 'avg:' prefix, then the metric base (observation metrics keep their 'obs.' segment), then the attribute — e.g. avg:max_t.p50, avg:obs.rain.sum, avg:obs.is_rain.count. Dropping 'avg:' or 'obs.' is an error; the criteria parameter below lists every valid name. scope=day queries forecasts; week/month query the 1996-2025 historical baseline. Returns: scope, time, baseline, results, locid, location, criteria_met, criteria_met_count, record.
besttime
read-only
namelocidlatlonbaselinecriteria*when_type
+2
Given a location, ranks the weeks or months whose historical climatology best matches a set of weather criteria (most optional criteria met first; all MUST criteria satisfied by ev… Given a location, ranks the weeks or months whose historical climatology best matches a set of weather criteria (most optional criteria met first; all MUST criteria satisfied by every result). <br><b>When to use:</b> Answer 'when is the best time to visit X for weather like Y?' Choose when_type=week or month over the 1996-2025 baseline. <br><b>Date format:</b> when_type: week|month|day. Historical basis only for week/month. <br><b>Performance:</b> Sub-second per location. <br><b>Prerequisites:</b> Use /location to obtain a locid first. <br><b>Investigate:</b> Rank a location's calendar by weather suitability. For a specific upcoming day's forecast, use /api/anom with period_type=FUTURE_DAY. <br><b>Augment:</b> Find the typical best window for an activity at a place. <br><b>Notes:</b> Every criterion metric name is literal and fully qualified: the 'avg:' prefix, then the metric base (observation metrics keep their 'obs.' segment), then the attribute — e.g. avg:max_t.p50, avg:obs.rain.sum, avg:obs.is_rain.count. Dropping 'avg:' or 'obs.' is an error; the criteria parameter below lists every valid name. For daily forecasts use /api/anom (period_type=FUTURE_DAY). Weekly/monthly forecasts are planned. Returns: location, baseline, when_type, results, time, criteria_met, criteria_met_count, record.
breaking
read-only
ctryidbreaking_typemetric_category
Returns anomalous weather conditions (breaking news) across the world or specified countries in the very recent past (observations) or immediate future (forecast). <br><b>When to u… Returns anomalous weather conditions (breaking news) across the world or specified countries in the very recent past (observations) or immediate future (forecast). <br><b>When to use:</b> First call when looking for current or upcoming notable weather events globally or by country. <br><b>Date format:</b> No date params — always returns the most recent ~3 days of observations (breaking_type=obs) or next 7 days of forecast (breaking_type=forecast). <br><b>Performance:</b> Fast — retrieves precomputed anomaly snapshots. <br><b>Prerequisites:</b> Use /countries to get country IDs for filtering. <br><b>Investigate:</b> Start here for any 'what's happening right now?' or 'what's forecast this week?' query; follow up with /anom or /dailycomp for per-location detail. <br><b>Augment:</b> Primary source for identifying breaking weather news stories globally; use ctryid to narrow scope by country. Returns: anomalies, anomaly.locid, anomaly.name, anomaly.city, anomaly.country, anomaly.lat, anomaly.lon, anomaly.geohash, anomaly.elevation, anomaly.obs_start, anomaly.obs_end, anomaly.obs_dur, anomaly.pt, anomaly.anomalies, outlier.obsm, outlier.comps, comp.obsm_f, comp.oq, comp.bq, comp.scope, comp.val, comp.bval, comp.min, comp.max, comp.med, comp.mean, comp.std, comp.min_dt, comp.max_dt, comp.intensity, comp.intensity_f, comp.rp, comp.summary, comp.period, comp.base_N, comp.N, comp.ut, comp.start, comp.end.
climatecomps
read-only
locidsmonthslat_lonmetrics*src_typecountries
+3
Returns monthly distributions of selected metrics for locations compared against a baseline period. <br><b>When to use:</b> Compute normalized and absolute deviations from a baseli… Returns monthly distributions of selected metrics for locations compared against a baseline period. <br><b>When to use:</b> Compute normalized and absolute deviations from a baseline, inter-annual and intra-annual variations within months and seasons. Check base_N and obs_N to assess data completeness. <br><b>Date format:</b> obs_years as YYYY or YYYY-YYYY range; months as MM or MM-MM (e.g. '06', '06-08', 'All' for annual). <br><b>Performance:</b> Bulk query — can be slow for global or large-area queries. Filter with locids, lat_lon/radius_km, or countries. <br><b>Prerequisites:</b> Use /location to obtain locids first for point queries. <br><b>Investigate:</b> Use to compare a recent season or year against the long-term baseline across many locations simultaneously. Combine with /climatetrends for trend context. <br><b>Augment:</b> Identifies which locations had the most anomalous season compared to their historical distribution. <br><b>Notes:</b> Metric format: 'max_t' = distribution of daily Maximum Temperature over the period; 'max_t.means' = distribution of annual means of max_t (1 value per year); 'rain_sum' (accumulations) and 'obs.is_thunderstorm' (counts) follow the same pattern. Returns: results, comp.locid, comp.geohash, comp.lat, comp.lon, comp.elev, comp.area, comp.country, comp.src_type, comp.metric, comp.obs_years, comp.base_years, comp.month, comp.obs_N, comp.base_N, comp.obs, comp.base, comp.obs.{q} / comp.base.{q}.
climatetrends
read-only
avg_Nyearslocidsmonthslat_lonmetrics*
+4
Returns monthly timeseries of selected climate trend metrics for one or more locations, suitable for long-term trend analysis. <br><b>When to use:</b> Retrieve long-term monthly ti… Returns monthly timeseries of selected climate trend metrics for one or more locations, suitable for long-term trend analysis. <br><b>When to use:</b> Retrieve long-term monthly timeseries for statistical trend analysis across any number of locations including globally. Use num_years and avg_N to filter sparse records. <br><b>Date format:</b> years as YYYY- range (e.g. '1975-' for 1975 to present); months as MM or MM-MM range (e.g. '06' for June, '06-08' for June–August, 'All' for annual). <br><b>Performance:</b> Bulk query — can be slow for global or many-location queries. Filter with locids, lat_lon/radius_km, or countries to improve speed. <br><b>Prerequisites:</b> Use /location to obtain locids first for point queries. <br><b>Investigate:</b> Use for global or regional trend analysis. Metric name format: 'agg_func:metric_id.attribute' (e.g. 'avg:max_t.p50'). Check num_years to confirm data completeness before citing a trend. <br><b>Augment:</b> Backs trend claims with long-term data across many locations (e.g. 'temperatures rising across Southeast Asia'). <br><b>Notes:</b> Example metrics: avg:max_t.p50, avg:obs.temp.mean, sum:obs.is_rain.count. See /api/metrics for full list. Returns: results, trend.locid, trend.geohash, trend.lat, trend.lon, trend.elev, trend.area, trend.country, trend.src_type, trend.metric, trend.years, trend.month, trend.num_years, trend.avg_N, trend.mvals, trend.mvals.xvals, trend.mvals.yvals_by_metric.
compare
read-only
namelocidlatlonymd_end*ymd_start*period_type
+3
Compares a location's observed weather period against the corresponding periods in a historical baseline distribution. <br><b>When to use:</b> Quantify how extreme a specific perio… Compares a location's observed weather period against the corresponding periods in a historical baseline distribution. <br><b>When to use:</b> Quantify how extreme a specific period was across all metrics at once — e.g. how anomalous was March 2025 at New York vs the 1991–2020 baseline. <br><b>Date format:</b> YYYY[MM[DD]]: YYYYMMDD for a specific day or short window (period_type DAY/WEEK), YYYYMM for a month (period_type MONTH), YYYY for an annual comparison (period_type YEAR). <br><b>Performance:</b> Computed on demand; fast for short periods. <br><b>Prerequisites:</b> Use /location to obtain a locid first. <br><b>Investigate:</b> Best for 'how unusual was [period] at [location]?' — returns percentile and z-score across all metrics simultaneously. Set baseline_offset=1 for the standard 1991–2020 baseline. <br><b>Augment:</b> Provides the precise statistical framing ('the hottest March in 30 years') before describing the anomaly in prose. Returns: comparisons, comparison.locid, comparison.lat, comparison.long, comparison.obs_start, comparison.obs_end, comparison.obs_dur, comparison.base_start, comparison.base_end, comparison.base_dur, comparison.obs_period, comparison.base_period, comparison.outliers, outlier.obs_metric, outlier.percentile, outlier.obs_N, outlier.obs_X, outlier.base_N, outlier.base_X, outlier.obs_val, outlier.base_val, outlier.base_mean, outlier.base_stddev, outlier.min, outlier.max, outlier.max_key, outlier.min_key, outlier.obs_min_key, outlier.obs_max_key.
countries
read-only
ctryid
Returns countries with their canonical country IDs used in all other API calls. <br><b>When to use:</b> Resolve country names to canonical IDs, or obtain the full list of supported… Returns countries with their canonical country IDs used in all other API calls. <br><b>When to use:</b> Resolve country names to canonical IDs, or obtain the full list of supported countries. This list rarely changes. <br><b>Performance:</b> Fast — static data; safe to cache across calls. <br><b>Prerequisites:</b> None. <br><b>Investigate:</b> Call once if country-level filtering is needed; cache the result for the session. <br><b>Augment:</b> Fetch country IDs before making country-filtered calls to /anomalies or /breaking. Returns: countries, country.ctryid, country.name, country.regions.
dailycomp
read-only
namelocidlatlonwindowymd_end*category
+3
Returns per-day observed values with percentiles and z-scores vs a sliding N-day window over a historical baseline. <br><b>When to use:</b> Graph heatwaves, cold spells, and other… Returns per-day observed values with percentiles and z-scores vs a sliding N-day window over a historical baseline. <br><b>When to use:</b> Graph heatwaves, cold spells, and other streaks by showing daily departures from normal. Also compare two separate periods or locations using z-scores or percentiles for normalized severity. <br><b>Date format:</b> YYYYMMDD for ymd_start and ymd_end. Keep ranges ≤30 days for fast response; up to 90 days is feasible. <br><b>Performance:</b> Computed on demand; slower for long date ranges. <br><b>Prerequisites:</b> Use /location to obtain a locid first. <br><b>Investigate:</b> Best for detailed day-by-day anomaly investigation once approximate dates and location are known. Use separate calls for two periods to compare heatwave severity via z-score. Do NOT use for ranking top-N events across years — call /events with criteria for that and post-process the response. <br><b>Augment:</b> Provides the daily series needed to describe the arc of a heatwave or cold snap in a news narrative. Returns: locid, lat, lon, dates, num_years, avg_coverage, metrics, metrics.{key}.values, metrics.{key}.pcts, metrics.{key}.sigmas, metrics.{key}.p1 … p99, metrics.{key}.bmin / bmax, metrics.{key}.mean, metrics.{key}.stddev, metrics.{key}.coverage.
degreedays
read-only
unitlatlon*ymd_endymd_startindicatorsbase_temp_C
+1
Returns cumulative degree-day indicators (heating/cooling/growing) for a location and period using ERA5 reanalysis data. <br><b>When to use:</b> Estimate energy demand anomalies or… Returns cumulative degree-day indicators (heating/cooling/growing) for a location and period using ERA5 reanalysis data. <br><b>When to use:</b> Estimate energy demand anomalies or agricultural stress in a recent or upcoming period. <br><b>Date format:</b> YYYYMMDD for ymd_start and ymd_end. Maximum interval is 14 days per call. <br><b>Performance:</b> Computed on demand using ERA5; moderate speed. Keep intervals to ≤14 days. <br><b>Prerequisites:</b> Requires lat/lon directly — no locid needed. <br><b>Investigate:</b> Use when the query involves power grid strain or energy demand. For forecast context, use future ymd dates. <br><b>Augment:</b> Adds quantitative energy-demand context to heatwave or cold snap stories. Returns: meta, indicators.
events
read-only
namelocidlatlonbaselinecriteria*year_end
+3
Finds days matching one or more compound weather conditions (e.g. hot + humid, rainy + windy) for a location. Returns up to 5000 most-recent matching events plus the total count. <… Finds days matching one or more compound weather conditions (e.g. hot + humid, rainy + windy) for a location. Returns up to 5000 most-recent matching events plus the total count. <br><b>When to use:</b> Count occurrences of compound weather events across years, study extreme or unusual day combinations, or identify streaks of such events. <br><b>Date format:</b> year_start/year_end as YYYY; month_day_start/month_day_end as MMDD for seasonal filtering within each year. <br><b>Performance:</b> Computed on demand; returns up to 5000 most-recent matches. <br><b>Prerequisites:</b> Use /location to obtain a locid first. <br><b>Investigate:</b> Use when the query involves compound conditions — 'how many days had both extreme heat and thunderstorms?' Combine numeric and condition metrics with AND/OR logic. <br><b>Augment:</b> Provides event frequency counts for framing rarity in a story ('only 3 such days in the past 20 years'). <br><b>Notes:</b> Numeric metrics: cloudiness, dewp, dpd, gust, hail_size, hi, insolation, max_dewp, max_dpd, max_hi, max_t, max_wbgt, max_wbulb, max_wind, min_dewp, min_t, min_wchill, rain, rain_12hr, rain_1hr, rain_3hr, rain_6hr, snow, snow_12hr, snow_1hr, snow_3hr, snow_6hr, snow_depth, temp, visibility, wbgt, wbulb, wchill, wind, wind_dir. Condition metrics: is_drizzle, is_dust, is_duststorm, is_fog, is_frozen_rain, is_funnel_cloud, is_hail, is_haze, is_heavy_rain, is_heavy_snow, is_ice_pellets, is_mist, is_rain, is_smoke, is_snow, is_squall, is_thunderstorm. Do not specify lower or upper bound when dealing with absolutes unless it is required. Sensible defaults are populated automatically and if the values provided fall out of those, the request is deemed invalid. Returns: locid, name, total_events, events, datestamp, max_t, max_t_complete, min_t, min_t_complete, rain, rain_complete, snow, temp, dewp, wind, max_wind, gust, conditions, criteria_met.
extremes
read-only
namelevellocidmonthlatlonseason
+5
Returns extreme value analysis (return periods) for a specified location and metric. <br><b>When to use:</b> Quantify the statistical rarity of a record or near-record value. Typic… Returns extreme value analysis (return periods) for a specified location and metric. <br><b>When to use:</b> Quantify the statistical rarity of a record or near-record value. Typically called after other APIs establish that an observation is anomalous. <br><b>Performance:</b> Computed on demand; moderate speed. <br><b>Prerequisites:</b> Use /location to obtain a locid first. Prefer level='area' over 'city' for better recall and longer period of record. <br><b>Investigate:</b> Use after /recentextremes or /anom establishes a high value; provides the return-period framing ('a once-in-50-year event'). <br><b>Augment:</b> Provides the statistical rarity framing needed for record-event stories. Try both src_types 'Obs' and 'ERA5' for non-US locations to account for discontinuous station records. Returns: locid, period, months_covered, window_size, N, coverage_pct, results, result.metric, result.value, result.return_period.
location
read-only
namelocidlatlon
Returns meta information for a location given a name, locid, or lat/lon. <br><b>When to use:</b> Obtain the canonical locid needed by all location-specific API calls. Typically the… Returns meta information for a location given a name, locid, or lat/lon. <br><b>When to use:</b> Obtain the canonical locid needed by all location-specific API calls. Typically the first call in any workflow. <br><b>Performance:</b> Fast — precomputed lookup. <br><b>Prerequisites:</b> None — this is the entry point. <br><b>Investigate:</b> Call first whenever the user names a city or region; cache the locid for all subsequent calls in the session. Use 'City, State Country' format (e.g. 'Austin TX USA'). <br><b>Augment:</b> Resolve city names from the article to locids early; reuse them throughout augmentation to avoid repeated name lookups. Returns: name, locid, friendly, lat, long, country, icao, elevation, timezone, wmo.
metrics
read-only
Returns the catalogue of all supported weather metric identifiers with units and categories. <br><b>When to use:</b> Resolve metric IDs to human-friendly names, units, and categori… Returns the catalogue of all supported weather metric identifiers with units and categories. <br><b>When to use:</b> Resolve metric IDs to human-friendly names, units, and categories. Call once and cache per session. <br><b>Performance:</b> Fast — static data; safe to cache for the lifetime of a session. <br><b>Prerequisites:</b> None. <br><b>Investigate:</b> Call once at session start; use metric.id as a lookup key throughout the conversation. <br><b>Augment:</b> Translate metric IDs into readable labels for article text and chart axes. Returns: metrics, metric.id, metric.name, metric.cat, metric.type, metric.dist.
recentextremes
read-only
scopectryidmetricsymd_endymd_startperiod_type
+1
Returns recent weather records (all-time or period-of-record extremes) for the world or specified countries. <br><b>When to use:</b> Find which locations have broken or nearly brok… Returns recent weather records (all-time or period-of-record extremes) for the world or specified countries. <br><b>When to use:</b> Find which locations have broken or nearly broken records in a recent date window. Set history_years ≥ 15 to ensure a meaningful period of record. <br><b>Date format:</b> YYYYMMDD for ymd_start and ymd_end. Keep windows ≤ 3 months per call for reasonable performance. <br><b>Performance:</b> Computed on demand; slower for large date ranges. Start with scope='monthly' or 'yearly'; fall back to 'weekly' for near-records. <br><b>Prerequisites:</b> Use /countries for country IDs; use /location for locids. <br><b>Investigate:</b> Use after /breaking identifies a record-breaking event to get precise extreme-value context. For US locations use period_type='DAY'; for non-US use 'FULL_DAY'. Hourly-derived metrics (wet bulb, wind gusts) for non-US require period_type='DAY'. <br><b>Augment:</b> Provides the 'record' framing for a story — 'hottest day ever recorded at this station.' Note: FULL_DAY and DAY expose different metric sets. Returns: results, extreme.locid, extreme.name, extreme.country_code, extreme.lat, extreme.lon, extreme.elev, extreme.period_type, extreme.metric, extreme.ymd, extreme.anomaly_type, extreme.scope, extreme.value, extreme.history_years.
timeseries
read-only
namelocidlatlongroupbymetrics*hour_end
+6
Returns aggregated metric values as a yearly or monthly timeseries for a location. <br><b>When to use:</b> Detect long-term trends and compute statistical significance (r-squared,… Returns aggregated metric values as a yearly or monthly timeseries for a location. <br><b>When to use:</b> Detect long-term trends and compute statistical significance (r-squared, p-value). Best suited for multi-decade spans. <br><b>Date format:</b> mm_dd_start/mm_dd_end as MMDD (day-of-year window, not a calendar year); year_start/year_end as YYYY. Note: Use mm_dd_start/mm_dd_end as MM when months are specified and MMDD when week-level granularity is needed. When day-level info is needed use /events or /dailycomp. <br><b>Performance:</b> Computed on demand; slower for large date ranges or many metrics. <br><b>Prerequisites:</b> Use /location to obtain a locid first. <br><b>Investigate:</b> Use for trend analysis ('Is max temperature at location X increasing over decades?'). Combine with r-squared post-processing for significance. <br><b>Augment:</b> Provides decadal trend context alongside current anomalies ('temperatures have risen 1.5°C over 40 years'). Returns: locid, lat, lon, xvals, yvals.
typicalweather
read-only
namelocidlatlonymd_end*hour_endlookback
+2