b3e7f75e50
The monthly temperature-range visualization now spans the 10th-percentile daily low to the 90th-percentile daily high (from climatology's p10/p90) — the band most days fall within — instead of just the average low to average high, giving a truer sense of each month's spread. The normals table keeps the average high/low figures.
660 lines
30 KiB
Python
660 lines
30 KiB
Python
"""Server-rendered, crawlable content pages (climate hub / per-city / month /
|
||
records / glossary / about) plus robots.txt and sitemap.xml.
|
||
|
||
These are the SEO surface: real URLs with the climate stats in the HTML, rendered
|
||
with Jinja2 from the same builders the API uses, linking into the interactive tool.
|
||
Registered on the app (via register()) BEFORE the StaticFiles mount so they win.
|
||
"""
|
||
import datetime
|
||
import hashlib
|
||
import json
|
||
import os
|
||
|
||
import polars as pl
|
||
from fastapi import HTTPException, Request, Response
|
||
from fastapi.responses import PlainTextResponse
|
||
from jinja2 import Environment, FileSystemLoader, select_autoescape
|
||
|
||
import cities
|
||
import city_events
|
||
import climate
|
||
import grading
|
||
import grid
|
||
from views import OBS_COLS
|
||
|
||
_BASE = os.environ.get("THERMOGRAPH_BASE", "/thermograph").strip("/")
|
||
BASE = f"/{_BASE}" if _BASE else ""
|
||
|
||
TEMPLATES_DIR = os.path.join(os.path.dirname(__file__), "templates")
|
||
_env = Environment(
|
||
loader=FileSystemLoader(TEMPLATES_DIR),
|
||
autoescape=select_autoescape(["html", "xml", "j2"]),
|
||
trim_blocks=True,
|
||
lstrip_blocks=True,
|
||
)
|
||
|
||
MONTHS = ["january", "february", "march", "april", "may", "june",
|
||
"july", "august", "september", "october", "november", "december"]
|
||
MONTHS_TITLE = [m.capitalize() for m in MONTHS]
|
||
MONTH_INDEX = {m: i + 1 for i, m in enumerate(MONTHS)}
|
||
|
||
# Meteorological seasons as (northern-hemisphere label, southern-hemisphere label,
|
||
# month numbers, span text). The same three months are one season everywhere — only
|
||
# the name flips across the equator (Dec–Feb is winter in the north, summer in the
|
||
# south), so a city's latitude picks the label.
|
||
SEASONS = [
|
||
("Winter", "Summer", [12, 1, 2], "Dec–Feb"),
|
||
("Spring", "Autumn", [3, 4, 5], "Mar–May"),
|
||
("Summer", "Winter", [6, 7, 8], "Jun–Aug"),
|
||
("Autumn", "Spring", [9, 10, 11], "Sep–Nov"),
|
||
]
|
||
|
||
# Display labels for the graded metrics (order = how they appear on the page).
|
||
METRIC_LABELS = [
|
||
("tmax", "High"), ("tmin", "Low"), ("feels", "Feels-like"),
|
||
("humid", "Humidity"), ("wind", "Wind"), ("gust", "Gust"), ("precip", "Precip"),
|
||
]
|
||
_TEMP_METRICS = {"tmax", "tmin", "feels"}
|
||
|
||
|
||
def _c(f: float) -> int:
|
||
return round((f - 32) * 5 / 9)
|
||
|
||
|
||
def _temp(f) -> str:
|
||
"""A Fahrenheit value shown in both units: '72°F (22°C)'."""
|
||
if f is None:
|
||
return "—"
|
||
return f"{round(f)}°F ({_c(f)}°C)"
|
||
|
||
|
||
def _fmt(metric: str, v) -> str:
|
||
if v is None:
|
||
return "—"
|
||
if metric in _TEMP_METRICS:
|
||
return _temp(v)
|
||
if metric == "precip":
|
||
return f"{v:.2f} in"
|
||
if metric == "humid":
|
||
return f"{v:.1f} g/m³"
|
||
return f"{round(v)} mph" # wind, gust
|
||
|
||
|
||
# Absolute-temperature colour tiers (°F upper bounds) mapped to the site's diverging
|
||
# cold→hot palette — the same 9 tiers the interactive grader uses. Colouring records
|
||
# and normals by these turns the tables into a heat map in the site's own visual
|
||
# language, rather than a plain grid.
|
||
_TEMP_TIERS = [
|
||
(20, "rec-cold"), (32, "very-cold"), (45, "cold"), (58, "cool"),
|
||
(70, "normal"), (80, "warm"), (90, "hot"), (100, "very-hot"),
|
||
]
|
||
# °F axis for the monthly temperature-range strip on the city page.
|
||
_AXIS_LO, _AXIS_HI = -10.0, 115.0
|
||
|
||
|
||
def temp_class(f) -> str:
|
||
"""Diverging-palette tier name for an absolute Fahrenheit temperature (or 'none')."""
|
||
if f is None:
|
||
return "none"
|
||
for upper, cls in _TEMP_TIERS:
|
||
if f < upper:
|
||
return cls
|
||
return "rec-hot"
|
||
|
||
|
||
def _range_bar(low_f, high_f) -> dict | None:
|
||
"""Geometry for one month's low→high bar on the shared _AXIS_LO.._AXIS_HI axis:
|
||
left offset + width as percentages, and the tier colour at each end (for a
|
||
gradient fill). None when a value is missing."""
|
||
if low_f is None or high_f is None:
|
||
return None
|
||
lo = max(_AXIS_LO, min(_AXIS_HI, low_f))
|
||
hi = max(_AXIS_LO, min(_AXIS_HI, high_f))
|
||
span = _AXIS_HI - _AXIS_LO
|
||
return {
|
||
"left": round((lo - _AXIS_LO) / span * 100, 1),
|
||
"width": round(max(2.0, (hi - lo) / span * 100), 1),
|
||
"c1": temp_class(low_f), "c2": temp_class(high_f),
|
||
}
|
||
|
||
|
||
_env.globals["temp_class"] = temp_class
|
||
|
||
|
||
def _month_doy(month_idx: int) -> int:
|
||
return datetime.date(2001, month_idx, 15).timetuple().tm_yday
|
||
|
||
|
||
# --- helpers -----------------------------------------------------------------
|
||
def origin(request: Request) -> str:
|
||
proto = request.headers.get("x-forwarded-proto") or request.url.scheme
|
||
host = request.headers.get("host") or request.url.netloc
|
||
return f"{proto}://{host}"
|
||
|
||
|
||
def _respond_html(request: Request, template: str, **ctx) -> Response:
|
||
o = origin(request)
|
||
html = _env.get_template(template).render(base=BASE, origin=o, base_url=f"{o}{BASE}", **ctx)
|
||
etag = f'W/"{hashlib.sha1(html.encode()).hexdigest()[:20]}"'
|
||
inm = request.headers.get("if-none-match")
|
||
if inm and etag in {t.strip() for t in inm.split(",")}:
|
||
return Response(status_code=304, headers={"ETag": etag})
|
||
return Response(html, media_type="text/html", headers={"ETag": etag})
|
||
|
||
|
||
# --- robots.txt & sitemap.xml -------------------------------------------------
|
||
def robots_txt(request: Request) -> Response:
|
||
base_url = f"{origin(request)}{BASE}"
|
||
body = (
|
||
"User-agent: *\n"
|
||
"Allow: /\n"
|
||
f"Disallow: {BASE}/api/\n" # JSON endpoints, nothing to index
|
||
f"Disallow: {BASE}/alerts\n" # per-user, requires login
|
||
f"Sitemap: {base_url}/sitemap.xml\n"
|
||
)
|
||
return PlainTextResponse(body)
|
||
|
||
|
||
def sitemap_xml(request: Request) -> Response:
|
||
base_url = f"{origin(request)}{BASE}"
|
||
today = datetime.date.today().isoformat()
|
||
urls: list[tuple[str, str, str]] = [] # (loc, changefreq, priority)
|
||
|
||
def add(path: str, changefreq: str, priority: str) -> None:
|
||
urls.append((f"{base_url}{path}", changefreq, priority))
|
||
|
||
add("/", "daily", "1.0")
|
||
for p in ("/climate", "/about", "/glossary", "/calendar", "/compare", "/legend"):
|
||
add(p, "weekly", "0.6")
|
||
for slug in cities.all_slugs():
|
||
add(f"/climate/{slug}", "daily", "0.8")
|
||
add(f"/climate/{slug}/records", "monthly", "0.5")
|
||
for m in MONTHS:
|
||
add(f"/climate/{slug}/{m}", "monthly", "0.5")
|
||
|
||
parts = ['<?xml version="1.0" encoding="UTF-8"?>',
|
||
'<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">']
|
||
for loc, cf, pr in urls:
|
||
parts.append(
|
||
f"<url><loc>{loc}</loc><lastmod>{today}</lastmod>"
|
||
f"<changefreq>{cf}</changefreq><priority>{pr}</priority></url>"
|
||
)
|
||
parts.append("</urlset>")
|
||
return Response("\n".join(parts), media_type="application/xml")
|
||
|
||
|
||
# --- per-city climate pages ---------------------------------------------------
|
||
def _history_for(cell: dict):
|
||
"""Cached archive for a cell, fetching once if missing (self-heals like the
|
||
notifier). Returns a polars frame or None."""
|
||
hist = climate.load_cached_history(cell)
|
||
if hist is not None and not hist.is_empty():
|
||
return hist
|
||
try:
|
||
hist, _ = climate.get_history(cell)
|
||
except Exception: # noqa: BLE001 - upstream unavailable: caller renders a 503
|
||
return None
|
||
return hist if (hist is not None and not hist.is_empty()) else None
|
||
|
||
|
||
def _monthly_normals(history) -> list[dict]:
|
||
"""One row per month: average high/low and average precip, from the ±7-day
|
||
climatology around each month's 15th."""
|
||
rows = []
|
||
for i, name in enumerate(MONTHS_TITLE, start=1):
|
||
clim = grading.climatology(history, _month_doy(i))
|
||
tmax, tmin, precip = clim.get("tmax"), clim.get("tmin"), clim.get("precip")
|
||
high_f = tmax["mean"] if tmax else None
|
||
low_f = tmin["mean"] if tmin else None
|
||
# The range strip spans the typical spread: 10th-percentile daily low to
|
||
# 90th-percentile daily high (the band most days fall within).
|
||
rng_lo = tmin["p10"] if tmin else None
|
||
rng_hi = tmax["p90"] if tmax else None
|
||
rows.append({
|
||
"name": name,
|
||
"slug": MONTHS[i - 1],
|
||
"high": _temp(tmax["mean"]) if tmax else "—",
|
||
"high_f": high_f,
|
||
"low": _temp(tmin["mean"]) if tmin else "—",
|
||
"low_f": low_f,
|
||
"range_lo_f": rng_lo,
|
||
"range_hi_f": rng_hi,
|
||
"precip": f"{precip['mean']:.2f} in" if precip else "—",
|
||
"precip_v": precip["mean"] if precip else None,
|
||
"bar": _range_bar(rng_lo, rng_hi),
|
||
})
|
||
return rows
|
||
|
||
|
||
def _period_records(history, months: list[int]) -> dict:
|
||
"""Record high (tmax) and record low (tmin), with the dates they occurred, over a
|
||
set of calendar months — the shared primitive behind the monthly and seasonal
|
||
records tables. Reuses grading.all_time_records on the month-filtered archive."""
|
||
if len(months) == 1:
|
||
sub = history.filter(pl.col("date").dt.month() == months[0])
|
||
else:
|
||
sub = history.filter(pl.col("date").dt.month().is_in(months))
|
||
rec = grading.all_time_records(sub) if not sub.is_empty() else {}
|
||
tmax, tmin = rec.get("tmax"), rec.get("tmin")
|
||
return {
|
||
"high": _temp(tmax["max"]) if tmax else "—",
|
||
"high_f": tmax["max"] if tmax else None,
|
||
"high_date": tmax["max_date"] if tmax else "—",
|
||
"low": _temp(tmin["min"]) if tmin else "—",
|
||
"low_f": tmin["min"] if tmin else None,
|
||
"low_date": tmin["min_date"] if tmin else "—",
|
||
}
|
||
|
||
|
||
def _monthly_records(history) -> list[dict]:
|
||
"""Record high and low for each of the 12 months (each row links to its month page)."""
|
||
return [
|
||
{"name": name, "slug": MONTHS[i - 1], **_period_records(history, [i])}
|
||
for i, name in enumerate(MONTHS_TITLE, start=1)
|
||
]
|
||
|
||
|
||
def _seasonal_records(history, lat: float) -> list[dict]:
|
||
"""Record high and low for each meteorological season, labelled for the city's
|
||
hemisphere (Dec–Feb reads as winter north of the equator, summer south of it)."""
|
||
south = lat < 0
|
||
return [
|
||
{"name": (south_lbl if south else north_lbl), "span": span,
|
||
**_period_records(history, months)}
|
||
for north_lbl, south_lbl, months, span in SEASONS
|
||
]
|
||
|
||
|
||
def _today_vs_normal(history, cell) -> dict | None:
|
||
"""Grade the latest recorded day against its climatology, for the hero block."""
|
||
try:
|
||
recent = climate.get_recent_forecast(cell)
|
||
except Exception: # noqa: BLE001
|
||
return None
|
||
if recent is None or recent.is_empty() or "date" not in recent.columns:
|
||
return None
|
||
today = datetime.date.today()
|
||
observed = recent.filter(pl.col("date") <= today).sort("date")
|
||
if observed.is_empty():
|
||
return None
|
||
row = observed.row(observed.height - 1, named=True)
|
||
obs = {k: row[k] for k in OBS_COLS if k in row}
|
||
graded = grading.grade_day(history, row["date"], obs)
|
||
cards = []
|
||
for key, label in METRIC_LABELS:
|
||
g = graded.get(key)
|
||
if not g:
|
||
continue
|
||
cards.append({
|
||
"label": label, "metric": key,
|
||
"value": _fmt(key, g.get("value")),
|
||
"percentile": g.get("percentile"),
|
||
"grade": g.get("grade"), "cls": g.get("class"),
|
||
})
|
||
date = row["date"]
|
||
return {
|
||
"date": date.isoformat() if hasattr(date, "isoformat") else str(date),
|
||
"cards": cards,
|
||
}
|
||
|
||
|
||
def _city_context(request, city, cell, history) -> dict:
|
||
name = city["name"]
|
||
display = cities.display_name(city)
|
||
years = history["date"].dt.year()
|
||
year_range = [int(years.min()), int(years.max())]
|
||
months = _monthly_normals(history)
|
||
warmest = max((m for m in months if m["high_f"] is not None), key=lambda m: m["high_f"], default=None)
|
||
coldest = min((m for m in months if m["low_f"] is not None), key=lambda m: m["low_f"], default=None)
|
||
wettest = max((m for m in months if m["precip_v"] is not None), key=lambda m: m["precip_v"], default=None)
|
||
records = grading.all_time_records(history)
|
||
tool_hash = f"{city['lat']:.5f},{city['lon']:.5f}"
|
||
# Unique editorial blurb (Wikipedia, CC BY-SA) so the page isn't just templated
|
||
# stats, and a travel/comfort CTA that pre-fills this city on the compare page.
|
||
flavor = cities.flavor(city["slug"])
|
||
event = city_events.get(city["slug"]) # hand-curated; None → page falls back to the blurb
|
||
compare_url = f"{BASE}/compare#loc={city['lat']:.4f},{city['lon']:.4f}"
|
||
|
||
breadcrumb = [("Home", f"{BASE}/"), ("Climate", f"{BASE}/climate")]
|
||
if city.get("country"):
|
||
breadcrumb.append((city["country"], None))
|
||
breadcrumb.append((name, None))
|
||
|
||
o = origin(request)
|
||
page_url = f"{o}{BASE}/climate/{city['slug']}"
|
||
jsonld = {
|
||
"@context": "https://schema.org",
|
||
"@graph": [
|
||
{"@type": "Dataset",
|
||
"name": f"{display} climate normals and records",
|
||
"description": f"Average temperatures, precipitation and record highs and lows for "
|
||
f"{display}, from ~{year_range[1] - year_range[0]} years of daily climate history.",
|
||
"url": page_url,
|
||
"temporalCoverage": f"{year_range[0]}/{year_range[1]}",
|
||
"spatialCoverage": {"@type": "Place", "name": display,
|
||
"geo": {"@type": "GeoCoordinates",
|
||
"latitude": city["lat"], "longitude": city["lon"]}},
|
||
"creator": {"@type": "Organization", "name": "Thermograph"},
|
||
"isBasedOn": "https://open-meteo.com/ (ERA5 reanalysis)"},
|
||
{"@type": "BreadcrumbList",
|
||
"itemListElement": [
|
||
{"@type": "ListItem", "position": i + 1, "name": nm,
|
||
**({"item": f"{o}{href}"} if href else {})}
|
||
for i, (nm, href) in enumerate(breadcrumb)]},
|
||
],
|
||
}
|
||
return {
|
||
"section": "climate",
|
||
"city": city, "display": display, "name": name,
|
||
"year_range": year_range, "n_years": year_range[1] - year_range[0],
|
||
"months": months, "warmest": warmest, "coldest": coldest, "wettest": wettest,
|
||
"records": records, "today": _today_vs_normal(history, cell),
|
||
"tool_hash": tool_hash, "flavor": flavor, "event": event, "compare_url": compare_url,
|
||
"breadcrumb": breadcrumb,
|
||
"canonical_path": f"/climate/{city['slug']}",
|
||
"page_title": f"{display} climate: average temperatures, records & how today compares",
|
||
"page_description": (f"Average monthly high and low temperatures, rainfall, and all-time records "
|
||
f"for {display}, plus how today's weather compares — graded against "
|
||
f"~{year_range[1] - year_range[0]} years of local climate history."),
|
||
"jsonld_str": json.dumps(jsonld, ensure_ascii=False, separators=(",", ":")),
|
||
}
|
||
|
||
|
||
def _resolve_city(slug: str):
|
||
"""(city, cell, history) for a slug, or raise 404 (unknown) / 503 (warming)."""
|
||
city = cities.get(slug)
|
||
if city is None:
|
||
raise HTTPException(status_code=404, detail="Unknown city.")
|
||
cell = grid.snap(city["lat"], city["lon"])
|
||
history = _history_for(cell)
|
||
if history is None:
|
||
raise HTTPException(status_code=503, detail="Climate data is warming up; please retry shortly.")
|
||
return city, cell, history
|
||
|
||
|
||
def city_page(request: Request, slug: str) -> Response:
|
||
city, cell, history = _resolve_city(slug)
|
||
return _respond_html(request, "city.html.j2", **_city_context(request, city, cell, history))
|
||
|
||
|
||
# --- month & records pages ----------------------------------------------------
|
||
def _month_context(request, city, history, month_idx: int) -> dict:
|
||
display = cities.display_name(city)
|
||
name = city["name"]
|
||
month_name = MONTHS_TITLE[month_idx - 1]
|
||
month_slug = MONTHS[month_idx - 1]
|
||
years = history["date"].dt.year()
|
||
year_range = [int(years.min()), int(years.max())]
|
||
|
||
clim = grading.climatology(history, _month_doy(month_idx))
|
||
tmax, tmin, precip = clim.get("tmax"), clim.get("tmin"), clim.get("precip")
|
||
mdf = history.filter(pl.col("date").dt.month() == month_idx)
|
||
mrec = grading.all_time_records(mdf) if not mdf.is_empty() else {}
|
||
|
||
stats = []
|
||
if tmax:
|
||
stats.append(("Average high", _temp(tmax["mean"])))
|
||
stats.append(("Typical high range", f"{_temp(tmax['p10'])} to {_temp(tmax['p90'])}"))
|
||
if tmin:
|
||
stats.append(("Average low", _temp(tmin["mean"])))
|
||
stats.append(("Typical low range", f"{_temp(tmin['p10'])} to {_temp(tmin['p90'])}"))
|
||
if precip:
|
||
stats.append(("Average daily precipitation", f"{precip['mean']:.2f} in"))
|
||
records = []
|
||
if mrec.get("tmax"):
|
||
records.append({"label": "Warmest on record", "value": _temp(mrec["tmax"]["max"]),
|
||
"date": mrec["tmax"]["max_date"], "cls": temp_class(mrec["tmax"]["max"])})
|
||
if mrec.get("tmin"):
|
||
records.append({"label": "Coldest on record", "value": _temp(mrec["tmin"]["min"]),
|
||
"date": mrec["tmin"]["min_date"], "cls": temp_class(mrec["tmin"]["min"])})
|
||
|
||
prev_i = 12 if month_idx == 1 else month_idx - 1
|
||
next_i = 1 if month_idx == 12 else month_idx + 1
|
||
breadcrumb = [("Home", f"{BASE}/"), ("Climate", f"{BASE}/climate"),
|
||
(name, f"{BASE}/climate/{city['slug']}"), (month_name, None)]
|
||
return {
|
||
"section": "climate", "city": city, "display": display, "name": name,
|
||
"month_name": month_name, "month_slug": month_slug,
|
||
"year_range": year_range, "n_years": year_range[1] - year_range[0],
|
||
"avg_high": _temp(tmax["mean"]) if tmax else "—",
|
||
"avg_low": _temp(tmin["mean"]) if tmin else "—",
|
||
"avg_high_cls": temp_class(tmax["mean"]) if tmax else "none",
|
||
"avg_low_cls": temp_class(tmin["mean"]) if tmin else "none",
|
||
"stats": stats, "records": records,
|
||
"tool_hash": f"{city['lat']:.5f},{city['lon']:.5f}",
|
||
"compare_url": f"{BASE}/compare#loc={city['lat']:.4f},{city['lon']:.4f}",
|
||
"prev": {"name": MONTHS_TITLE[prev_i - 1], "slug": MONTHS[prev_i - 1]},
|
||
"next": {"name": MONTHS_TITLE[next_i - 1], "slug": MONTHS[next_i - 1]},
|
||
"breadcrumb": breadcrumb,
|
||
"canonical_path": f"/climate/{city['slug']}/{month_slug}",
|
||
"page_title": f"Average weather in {display} in {month_name}",
|
||
"page_description": (f"Average high and low temperatures, typical range, records and rainfall for "
|
||
f"{display} in {month_name}, from ~{year_range[1] - year_range[0]} years of local records."),
|
||
}
|
||
|
||
|
||
def month_page(request: Request, slug: str, month: str) -> Response:
|
||
if month not in MONTH_INDEX:
|
||
raise HTTPException(status_code=404, detail="Unknown month.")
|
||
city, cell, history = _resolve_city(slug)
|
||
return _respond_html(request, "month.html.j2", **_month_context(request, city, history, MONTH_INDEX[month]))
|
||
|
||
|
||
def _records_context(request, city, history) -> dict:
|
||
display = cities.display_name(city)
|
||
name = city["name"]
|
||
years = history["date"].dt.year()
|
||
year_range = [int(years.min()), int(years.max())]
|
||
n_years = year_range[1] - year_range[0]
|
||
rec = grading.all_time_records(history)
|
||
rows = []
|
||
for key, label in METRIC_LABELS:
|
||
r = rec.get(key)
|
||
if not r:
|
||
continue
|
||
if key == "precip":
|
||
# "Record low" rain is meaningless (it's just 0), so the low side shows
|
||
# the longest dry streak and the date it began instead.
|
||
days, dry_start = grading.longest_dry_streak(history)
|
||
low = f"{days}-day dry spell" if days else "—"
|
||
low_date = dry_start or "—"
|
||
else:
|
||
low, low_date = _fmt(key, r["min"]), r["min_date"]
|
||
is_temp = key in _TEMP_METRICS
|
||
rows.append({
|
||
"label": label,
|
||
"high": _fmt(key, r["max"]), "high_date": r["max_date"],
|
||
"high_f": r["max"] if is_temp else None,
|
||
"low": low, "low_date": low_date,
|
||
"low_f": r["min"] if is_temp else None,
|
||
})
|
||
monthly = _monthly_records(history)
|
||
seasonal = _seasonal_records(history, city["lat"])
|
||
hemisphere = "Southern" if city["lat"] < 0 else "Northern"
|
||
|
||
breadcrumb = [("Home", f"{BASE}/"), ("Climate", f"{BASE}/climate"),
|
||
(name, f"{BASE}/climate/{city['slug']}"), ("Records", None)]
|
||
o = origin(request)
|
||
page_url = f"{o}{BASE}/climate/{city['slug']}/records"
|
||
jsonld = {
|
||
"@context": "https://schema.org",
|
||
"@graph": [
|
||
{"@type": "Dataset",
|
||
"name": f"{display} monthly and seasonal weather records",
|
||
"description": f"Record high and low temperatures for {display} by month and by "
|
||
f"meteorological season, with the dates they occurred, from ~{n_years} "
|
||
f"years of daily climate history.",
|
||
"url": page_url,
|
||
"temporalCoverage": f"{year_range[0]}/{year_range[1]}",
|
||
"spatialCoverage": {"@type": "Place", "name": display,
|
||
"geo": {"@type": "GeoCoordinates",
|
||
"latitude": city["lat"], "longitude": city["lon"]}},
|
||
"creator": {"@type": "Organization", "name": "Thermograph"},
|
||
"isBasedOn": "https://open-meteo.com/ (ERA5 reanalysis)"},
|
||
{"@type": "BreadcrumbList",
|
||
"itemListElement": [
|
||
{"@type": "ListItem", "position": i + 1, "name": nm,
|
||
**({"item": f"{o}{href}"} if href else {})}
|
||
for i, (nm, href) in enumerate(breadcrumb)]},
|
||
],
|
||
}
|
||
return {
|
||
"section": "climate", "city": city, "display": display, "name": name,
|
||
"year_range": year_range, "n_years": n_years,
|
||
"rows": rows, "monthly": monthly, "seasonal": seasonal,
|
||
"hemisphere": hemisphere, "all_time": rec,
|
||
"canonical_path": f"/climate/{city['slug']}/records",
|
||
"breadcrumb": breadcrumb,
|
||
"page_title": f"{display} weather records: monthly & seasonal record highs and lows",
|
||
"page_description": (f"Record high and low temperatures for {display} by month and by season, with the "
|
||
f"dates they occurred, plus all-time extremes — from ~{n_years} years of daily "
|
||
f"climate history."),
|
||
"jsonld_str": json.dumps(jsonld, ensure_ascii=False, separators=(",", ":")),
|
||
}
|
||
|
||
|
||
def records_page(request: Request, slug: str) -> Response:
|
||
city, cell, history = _resolve_city(slug)
|
||
return _respond_html(request, "records.html.j2", **_records_context(request, city, history))
|
||
|
||
|
||
# --- hub / glossary / about ---------------------------------------------------
|
||
def _breadcrumb(*items):
|
||
return list(items)
|
||
|
||
|
||
def hub_page(request: Request) -> Response:
|
||
groups = cities.by_country()
|
||
ctx = {
|
||
"section": "climate",
|
||
"groups": groups,
|
||
"n_cities": sum(len(v) for v in groups.values()),
|
||
"n_countries": len(groups),
|
||
"canonical_path": "/climate",
|
||
"breadcrumb": [("Home", f"{BASE}/"), ("Climate", None)],
|
||
"page_title": "City climate pages — averages, records and how today compares",
|
||
"page_description": ("Browse climate pages for hundreds of cities worldwide: average temperatures by "
|
||
"month, all-time records, and how today's weather compares to local history."),
|
||
}
|
||
return _respond_html(request, "hub.html.j2", **ctx)
|
||
|
||
|
||
# Weather-terms glossary. Each entry: slug -> (term, short definition, body HTML).
|
||
GLOSSARY: dict[str, dict] = {
|
||
"climate-normal": {
|
||
"term": "Climate normal",
|
||
"short": "The typical value of a weather metric for a place and time of year, averaged over decades.",
|
||
"body": "A <b>climate normal</b> is the long-term average of a weather variable (say, the daily high) "
|
||
"for a specific place and time of year. Thermograph builds each day's normal from every "
|
||
"historical day within ±7 days of that day-of-year, across ~45 years — so a day is judged "
|
||
"against its own season, not a single annual average.",
|
||
},
|
||
"percentile": {
|
||
"term": "Percentile",
|
||
"short": "Where a value ranks within a distribution — the 90th percentile is warmer than 90% of days.",
|
||
"body": "A <b>percentile</b> says where a value falls within a range of past values. If today's high is at "
|
||
"the 97th percentile, only about 3% of comparable days in this location's history were warmer. "
|
||
"Thermograph grades every day by its percentile against the local ±7-day seasonal distribution.",
|
||
},
|
||
"temperature-anomaly": {
|
||
"term": "Temperature anomaly",
|
||
"short": "How far a temperature departs from normal — the difference from the long-term average.",
|
||
"body": "A <b>temperature anomaly</b> is how much warmer or colder it is than the local normal for the "
|
||
"time of year. Thermograph expresses the same idea as a percentile and a grade (from “Below "
|
||
"Normal” to “Near Record”), so an anomaly is easy to read at a glance for any location.",
|
||
},
|
||
"feels-like": {
|
||
"term": "Feels-like temperature",
|
||
"short": "What the air actually feels like once humidity and wind are accounted for.",
|
||
"body": "<b>Feels-like</b> (apparent temperature) combines air temperature with humidity and wind. In heat "
|
||
"it uses the <a href=\"{base}/glossary/heat-index\">heat index</a>; in cold it uses "
|
||
"<a href=\"{base}/glossary/wind-chill\">wind chill</a>. Thermograph grades feels-like against its "
|
||
"own local history, so “Near Record” means extreme <i>for that place</i>.",
|
||
},
|
||
"heat-index": {
|
||
"term": "Heat index",
|
||
"short": "How hot it feels when humidity is factored into the air temperature.",
|
||
"body": "The <b>heat index</b> is the apparent temperature on a hot, humid day: high humidity slows sweat "
|
||
"evaporation, so it feels hotter than the thermometer reads. Thermograph folds it into the "
|
||
"<a href=\"{base}/glossary/feels-like\">feels-like</a> metric and grades how unusual it is locally.",
|
||
},
|
||
"wind-chill": {
|
||
"term": "Wind chill",
|
||
"short": "How cold it feels when wind is factored into the air temperature.",
|
||
"body": "<b>Wind chill</b> is the apparent temperature on a cold, windy day: wind strips away body heat, so "
|
||
"it feels colder than the air temperature. It's the cold-weather half of "
|
||
"<a href=\"{base}/glossary/feels-like\">feels-like</a>.",
|
||
},
|
||
"humidity": {
|
||
"term": "Absolute humidity",
|
||
"short": "The actual mass of water vapor in the air, in grams per cubic meter.",
|
||
"body": "Thermograph reports <b>absolute humidity</b> (g/m³) — the real amount of water vapor in the "
|
||
"air — rather than relative humidity, which shifts with temperature. Graded against local history, "
|
||
"it shows genuinely muggy or unusually dry days.",
|
||
},
|
||
"reanalysis": {
|
||
"term": "Reanalysis (ERA5)",
|
||
"short": "A gridded, physically-consistent record of past weather for anywhere on Earth.",
|
||
"body": "A <b>reanalysis</b> blends historical observations with a weather model to produce a consistent "
|
||
"record of past conditions everywhere — even where no station exists. Thermograph's ~45-year history "
|
||
"comes from ECMWF's <b>ERA5</b> reanalysis (via Open-Meteo), which is why it works for any point on Earth.",
|
||
},
|
||
}
|
||
|
||
|
||
def _glossary_body(entry: dict) -> str:
|
||
return entry["body"].replace("{base}", BASE)
|
||
|
||
|
||
def glossary_index(request: Request) -> Response:
|
||
ctx = {
|
||
"terms": [{"slug": s, **e} for s, e in GLOSSARY.items()],
|
||
"canonical_path": "/glossary",
|
||
"breadcrumb": [("Home", f"{BASE}/"), ("Glossary", None)],
|
||
"page_title": "Weather & climate glossary — heat index, feels-like, percentile, and more",
|
||
"page_description": ("Plain-language definitions of weather and climate terms: climate normal, percentile, "
|
||
"temperature anomaly, feels-like, heat index, wind chill, humidity, and reanalysis."),
|
||
}
|
||
return _respond_html(request, "glossary.html.j2", **ctx)
|
||
|
||
|
||
def glossary_term(request: Request, term: str) -> Response:
|
||
entry = GLOSSARY.get(term)
|
||
if entry is None:
|
||
raise HTTPException(status_code=404, detail="Unknown term.")
|
||
ctx = {
|
||
"term": entry["term"], "body": _glossary_body(entry),
|
||
"canonical_path": f"/glossary/{term}",
|
||
"breadcrumb": [("Home", f"{BASE}/"), ("Glossary", f"{BASE}/glossary"), (entry["term"], None)],
|
||
"page_title": f"{entry['term']} — what it means | Thermograph",
|
||
"page_description": entry["short"],
|
||
"others": [{"slug": s, "term": e["term"]} for s, e in GLOSSARY.items() if s != term],
|
||
}
|
||
return _respond_html(request, "glossary_term.html.j2", **ctx)
|
||
|
||
|
||
def about_page(request: Request) -> Response:
|
||
ctx = {
|
||
"canonical_path": "/about",
|
||
"breadcrumb": [("Home", f"{BASE}/"), ("About", None)],
|
||
"page_title": "About Thermograph — how the weather grades are calculated",
|
||
"page_description": ("How Thermograph works: ~45 years of ERA5 climate history, a ±7-day seasonal "
|
||
"window, and empirical percentiles that grade each day relative to its own location."),
|
||
}
|
||
return _respond_html(request, "about.html.j2", **ctx)
|
||
|
||
|
||
# --- registration ------------------------------------------------------------
|
||
def register(app) -> None:
|
||
"""Attach all content routes. Call from app.py BEFORE the StaticFiles mount."""
|
||
app.add_api_route(f"{BASE}/robots.txt", robots_txt, methods=["GET"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/sitemap.xml", sitemap_xml, methods=["GET"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/about", about_page, methods=["GET", "HEAD"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/glossary", glossary_index, methods=["GET", "HEAD"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/glossary/{{term}}", glossary_term, methods=["GET", "HEAD"], include_in_schema=False)
|
||
# Hub before /climate/{slug} so the literal path wins.
|
||
app.add_api_route(f"{BASE}/climate", hub_page, methods=["GET", "HEAD"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/climate/{{slug}}", city_page, methods=["GET", "HEAD"], include_in_schema=False)
|
||
# Records before the {month} param so the literal path wins.
|
||
app.add_api_route(f"{BASE}/climate/{{slug}}/records", records_page, methods=["GET", "HEAD"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/climate/{{slug}}/{{month}}", month_page, methods=["GET", "HEAD"], include_in_schema=False)
|