DEV Community: zhiyuan

From API to Decision-Ready Meteograms: Unlocking Global 15-Day Hourly Weather Forecasts with Python

zhiyuan — Wed, 04 Nov 2026 05:27:36 +0000

In consumer weather apps, a brief summary like "light rain over the next three days, temperatures between 12°C and 18°C" compresses highly complex atmospheric physics into a single sentence. While sufficient for a daily commute, such coarse daily overviews fall short in rigorous data analysis and engineering applications. Whether you are forecasting solar photovoltaic (PV) power output at noon tomorrow, evaluating sudden wind gusts along an autonomous drone inspection route, or analyzing the exact onset and cessation of a precipitation event alongside shifting wind fields and cloud cover, you need continuously sampled hourly meteorological time-series data.

In this technical walkthrough, we explore the Global City Forecast API from Global Weather Data. Beyond demonstrating how to query the API in Python, we will focus on using Matplotlib to organize up to 23 meteorological variables into a clean, reproducible multi-panel meteogram—while systematically avoiding common engineering pitfalls such as timezone mismatches, mixed physical units, improper missing-value handling, and toponymic ambiguity.

Global Forecasts and Historical Weather: A Unified Spatiotemporal Platform

Before writing any code, let's examine the data architecture provided by Global Weather Data. The platform organizes global meteorological resources into three core product lines, available both via RESTful APIs for automated data pipelines and as downloadable flat or multidimensional files:

Data Product	Spatial Coverage	Temporal Horizon & Update Frequency	Variables	Delivery Format
Global City Forecast	Any global location	15-day hourly, updated 4 times daily	Up to 23	API or CSV
Global Gridded Forecast	Global 0.1° grid	15-day hourly, updated 4 times daily	Up to 23	API or NetCDF
Global City Historical Weather	12,000+ urban areas	10+ years hourly, ~10-day latency	Up to 24	API or CSV

These three products correspond to three distinct analytical perspectives in operational workflows:

Global City Forecast provides a point time-series view, focusing on a specific city or geographic coordinate pair to extract a continuous temporal profile. It is ideal for single-site operational forecasting.
Global Gridded Forecast offers a spatially continuous grid view, covering the globe at a 0.1° x 0.1° spatial resolution (approximately 10 km grid spacing at mid-latitudes). It captures the spatial distribution of atmospheric fields and is well-suited for regional weather comparisons and spatial interpolation modeling.
Global City Historical Weather serves as a long-term historical baseline, providing over a decade of hourly observations and reanalysis data (continuous datasets generated by assimilating historical observations into numerical models). It forms the foundation for training machine learning models, conducting historical backtesting, and performing climatological analysis.

Regarding delivery formats, CSV files integrate seamlessly into spreadsheet tools and standard tabular data workflows. Gridded datasets are delivered in NetCDF (Network Common Data Form), the industry-standard self-describing multidimensional array format in atmospheric and oceanic sciences, which pairs naturally with Python's xarray library for spatiotemporal slicing and scientific computing.

Understanding the "4 Daily Rolling Updates" NWP Mechanism

As noted in the product table above, forecast data is updated four times daily on a rolling basis. This schedule aligns with the four standard forecast cycles (or model runs) initiated daily at 00:00, 06:00, 12:00, and 18:00 Coordinated Universal Time (UTC) by major global Numerical Weather Prediction (NWP) models, such as ECMWF and GFS.

Consequently, a 15-day forecast for a given location is not a static table. Every few hours, as the latest global observations from meteorological satellites, weather radars, and surface stations undergo data assimilation (the process of fusing multi-source observations into an NWP model's initial state to minimize initial condition errors), a new model run computes an updated forecast trajectory. In production data engineering, we strongly recommend logging data provenance metadata—such as the request timestamp, query parameters, and API version—whenever persisting forecast data to disk. Without this metadata, conducting accurate model backtesting or post-event error analysis becomes nearly impossible, as you cannot verify which forecast cycle generated a given prediction.

Additionally, note that API rate limits and quotas vary by account tier; always review the official documentation before deploying batch ingestion scripts (basic accounts typically include up to 1,000 free API calls). Keep in mind that both city-level and gridded forecasts represent mesoscale background atmospheric conditions (spanning a few kilometers to several hundred kilometers horizontally) rather than street-level microclimates. Local topography, urban canopies, and the urban canyon effect in high-density built environments can all introduce noticeable deviations between localized in-situ measurements and grid-cell values.

Defining Operational Boundaries: A 15-day forecast is a numerical estimate of medium-range atmospheric evolution. Due to the nonlinear, chaotic nature of atmospheric dynamics, forecast uncertainty grows with lead time, and medium-range forecasts must not be conflated with long-term climate projections. For safety-critical applications—such as aviation, maritime navigation, severe weather mitigation, or industrial safety—never rely solely on a single API chart. Always cross-reference official meteorological warnings, in-situ sensor observations, and industry safety protocols.

Dissecting the Global City Forecast API: From Request Parameters to Columnar JSON

The Global City Forecast API uses a straightforward RESTful URL structure with path parameters:

https://global-weather-data.com/api/forecast/{location}/{api_key}

Each request requires two core path parameters:

location (Target Location Identifier): The endpoint accepts an English city name, a coordinate pair, or a GeoNames ID. When querying by coordinates, pass a comma-separated string such as -118.24368,34.05223. Note a critical convention in meteorological and GIS systems: coordinates must be specified in Longitude,Latitude order, corresponding to (x, y) on a Cartesian plane—the reverse of the everyday Latitude,Longitude convention.
api_key (Access Credential): Your unique authentication token obtained from the user dashboard. Treat this token with the same security posture as a database password. Before committing code to public repositories like GitHub, always externalize the key into environment variables or a secrets manager rather than hardcoding it in your scripts.

Among the three location formats, GeoNames ID (e.g., 5368361 for Los Angeles) is the most reliable choice for automated data pipelines. First, countless cities share identical names worldwide (there are dozens of settlements named Paris or Springfield), and a globally unique numeric ID eliminates toponymic ambiguity entirely. Second, city names containing spaces or special characters (like Los Angeles) require URL percent-encoding, whereas numeric IDs keep request URLs clean and predictable. If you pass coordinate pairs, ensure that the comma separating longitude and latitude is preserved unescaped during URL encoding.

Why Columnar Arrays Instead of an Array of Hourly Objects?

Developers new to meteorological APIs often notice that the JSON payload is not structured as a conventional row-oriented list (i.e., an array of 361 objects, each containing all 23 keys for a single hour). Instead, the response uses the following structure:

{
  "status": "success",
  "location_forecast_api_used_count": "...",
  "location_forecast_api_count_limit": "...",
  "location_info": {
    "geonameid": "5368361",
    "name": "Los Angeles",
    "admin1": "California",
    "country": "United States",
    "longitude": -118.24368,
    "latitude": 34.05223
  },
  "forecast_count": 361,
  "forecast_data": {
    "time": ["2026-11-03 06:00:00", "..."],
    "t2m": [16.2, "..."],
    "d2m": [9.4, "..."],
    "tp": [0.0, "..."]
  }
}

This payload design reflects several deliberate engineering choices:

Location Metadata Verification (location_info): When querying by city name, an HTTP 200 status only confirms a successful network round-trip, not necessarily the intended geographic match. Production code should inspect country, admin1 (first-level administrative division), and coordinates inside location_info to verify that the resolved location matches expectations.
Compact Columnar Layout (forecast_data): Inside forecast_data, time is an array of timestamps, while t2m, tp, and other meteorological variables are parallel numeric arrays of equal length. Elements at the same index i correspond to the same forecast validity time (e.g., forecast_data["tp"][i] is the precipitation at forecast_data["time"][i]). This columnar layout offers two major advantages for time-series workloads: it eliminates the payload overhead of repeating 23 field names 361 times over the wire, and it maps directly to NumPy vectorized operations and Pandas memory structures. Calling pd.DataFrame(payload["forecast_data"]) constructs a clean tabular DataFrame in a single line without row-by-row iteration.
Timezone Normalization: Notice that the timestamp strings in time (e.g., "2026-11-03 06:00:00") omit a trailing Z or UTC offset—making them naive datetime strings. However, per the API specification, all timestamps are strictly in UTC. Never parse these strings using host-local datetime functions; otherwise, scripts running on servers in different timezones will shift the diurnal cycle and misalign sunrise, sunset, and peak heating hours. Always attach explicit UTC timezone metadata during parsing (converting them into timezone-aware datetime objects) to establish a consistent baseline for cross-regional comparisons or local timezone conversions.
Why Does a 15-Day Forecast Return 361 Records? While 15 * 24 = 360 hours, forecast_count returns 361. This follows the classic fencepost principle (inclusive endpoints): a 360-hour horizon sampled hourly at the top of each hour—including both the initial boundary (hour 0) and the final boundary (hour 360)—yields 360 + 1 = 361 discrete timestamps.

All 23 Meteorological Variables Explained: Physical Definitions and Domain Applications

Our test query for Los Angeles returns 23 meteorological variables. The table below groups them by physical category (note that available fields may vary across product tiers; always rely on the keys returned in your live response):

Category	Field Keys	Physical Meaning	Unit
Temperature	`t2m`, `d2m`, `skt`	2 m air temperature, 2 m dew point, skin temperature	°C
Wind	`u10`, `v10`, `u100`, `v100`, `fg10`	10 m & 100 m zonal (u) and meridional (v) wind components, 10 m wind gust	m/s
Pressure	`msl`, `sp`	Mean sea-level pressure, surface pressure	hPa
Precipitation & Snow	`tp`, `sf`, `sd`, `ro`	Total precipitation, snowfall, snow depth, runoff	mm
Cloud Cover	`tcc`	Total cloud cover	0--1
Radiation	`ssrd`, `strd`, `ttr`, `ssr`, `str`	Surface downward/net solar & thermal radiation, top net thermal radiation	W/m²
Convection	`mucape`	Most-unstable convective available potential energy	J/kg
Column Water	`tcw`, `tcwv`	Total column water, total column water vapor	kg/m²

To extract maximum operational value from these parameters, let's examine how meteorologists and domain engineers interpret key variable combinations:

The Temperature Trio (t2m, d2m, skt): t2m represents standard shelter-level air temperature at 2 meters above ground. d2m (2 m dew point temperature) is the temperature to which air must be cooled—at constant pressure and water vapor content—for saturation and condensation to occur. In meteorological diagnostics, when the d2m curve converges toward or touches t2m (i.e., the dew point depression approaches zero), near-surface relative humidity is approaching 100%, signaling conditions conducive to fog, dew formation, or oppressive humidity. Meanwhile, skt (skin temperature) measures the radiative equilibrium temperature right at the land-atmosphere interface. Under intense daytime solar heating or clear-sky nocturnal radiative cooling, skt responds faster and exhibits larger swings than 2 m air temperature, making it a critical indicator for road icing and agricultural frost risk.
Orthogonal Wind Components and 100 m Hub-Height Winds (u10, v10, u100, v100, fg10): NWP datasets standardly decompose horizontal wind vectors into orthogonal components: zonal velocity u (eastward flow is positive, i.e., a westerly wind) and meridional velocity v (northward flow is positive, i.e., a southerly wind), rather than scalar speed and compass direction. Mathematically, wind direction is a circular variable (0° and 360° are identical), meaning linear arithmetic averaging or interpolation fails across the north boundary (averaging 1° and 359° northerly winds yields a 180° southerly wind). From u and v at the same height, scalar wind speed is easily derived via the Euclidean norm sqrt(u² + v²). Notably, the API provides 100 m wind components (u100, v100). Because modern utility-scale wind turbines typically have hub heights between 80 and 120 meters, these two fields serve as direct inputs for wind power forecasting. Finally, fg10 (10 m wind gust) captures the peak instantaneous wind speed over the interval, essential for structural wind-load and safety assessments.
Mean Sea-Level Pressure vs. Surface Pressure (msl, sp): Atmospheric pressure decays exponentially with altitude. sp measures the actual atmospheric pressure at local terrain elevation; comparing sp directly between a high-altitude city and a coastal city primarily reflects topography rather than weather patterns. To remove elevation bias and track synoptic-scale systems (such as migrating high-pressure ridges, cold fronts, or deepening low-pressure troughs), meteorologists reduce surface pressure to sea level using the hydrostatic equation, yielding msl (mean sea-level pressure).
Solar Shortwave and Thermal Longwave Radiation (ssrd, ssr, etc.): For solar resource assessment and PV power forecasting, ssrd (surface solar radiation downwards, widely known in the solar industry as Global Horizontal Irradiance, or GHI) is the primary driver. It quantifies the total shortwave solar irradiance (W/m²) reaching a horizontal surface after atmospheric attenuation and cloud scattering, correlating directly with PV array output.
Convective Instability and Column Moisture (mucape, tcw, tcwv): mucape (most-unstable convective available potential energy) quantifies buoyant thermal instability in the atmosphere. Spikes in mucape indicate a highly unstable stratification capable of fueling thunderstorms and severe convective updrafts (note that CAPE measures thermodynamic potential rather than precipitation probability). Concurrently, tcwv (total column water vapor, or precipitable water) and tcw (total column water, integrating vapor, cloud liquid water, and cloud ice) measure the total mass of moisture contained within a vertical column of unit cross-section extending from the surface to the top of the atmosphere. Heavy convective precipitation requires both ample moisture supply (high tcwv) and a thermodynamic trigger (high mucape).

Engineering Implementation: Building a 23-Variable Publication-Grade Meteogram in Python

Plotting 23 variables with vastly different physical units and magnitudes on a single vertical axis is impractical—atmospheric pressure (~10³ hPa) would flatten cloud cover (0--1) into an unreadable line along the bottom axis. The standard scientific visualization approach is to group variables by physical dimension and stack them vertically in a shared-time-axis multi-panel figure (sharex=True).

The complete Python script below is ready to run out of the box and incorporates several production-grade engineering practices:

Network Timeout Protection: Uses requests with an explicit timeout to prevent the process from hanging indefinitely during network stalls.
Two-Tier Error Handling: Separates HTTP transport errors from API-level business errors (an HTTP 200 response confirms connectivity, but the JSON status field must still be checked for invalid keys or exhausted quotas).
Explicit UTC Normalization: Parses all timestamps into timezone-aware UTC datetime objects, eliminating any dependency on the host machine's local timezone setting.
Array Alignment & Missing-Value Semantics: Validates that all variable arrays match the timestamp array length, and converts JSON null (None) values into np.nan. This distinction is vital: coercing missing data to 0 misrepresents sensor/model gaps as "zero precipitation, calm winds, or 0°C," whereas NaN instructs Matplotlib to cleanly break the line and leave a visual gap.
Domain-Appropriate Visual Encoding: Organizes the 23 variables into 8 vertically aligned panels. Continuous state variables (temperature, wind, pressure, radiation) are rendered as line or filled-area plots, while hourly accumulation fluxes (precipitation, snowfall, runoff) are rendered as grouped bar charts alongside a dashed line for snow depth.

First, install the required dependencies in your Python environment:

python -m pip install requests numpy matplotlib

Save the following script as plot_weather_forecast.py. Replace API_KEY at the top with your personal credential, and modify LOCATION if you wish to query a different city. Running the script generates both a high-resolution PNG and a vector PDF in the same directory:

from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import quote
import re

import matplotlib
matplotlib.use("Agg")
import matplotlib.dates as mdates
import matplotlib.pyplot as plt
import numpy as np
import requests

# Replace with your personal API key from the user dashboard; never commit real keys to public repos.
API_KEY = "PASTE_YOUR_API_KEY_HERE"
LOCATION = "5368361"  # Los Angeles GeoNames ID or city name or coordinations
API_URL = "https://global-weather-data.com/api/forecast"
OUTPUT_DIR = Path(__file__).parent


def fetch_forecast():
    if API_KEY == "PASTE_YOUR_API_KEY_HERE":
        raise ValueError("Please set your API_KEY at the top of the script first.")

    # quote() encodes spaces and special characters in city names while preserving commas in coordinate pairs.
    url = f"{API_URL}/{quote(LOCATION, safe=',')}/{API_KEY}"
    requested_at = datetime.now(timezone.utc)
    response = requests.get(url, timeout=60)

    # Check HTTP transport errors (401, 404, 429, 5xx) separately from JSON business status.
    response.raise_for_status()
    payload = response.json()
    if payload.get("status") != "success":
        raise RuntimeError(payload.get("message", "Forecast API request failed"))
    return payload, requested_at


def as_utc(value):
    # API timestamp strings may omit timezone suffixes, but the specification guarantees UTC.
    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
    if parsed.tzinfo is None:
        parsed = parsed.replace(tzinfo=timezone.utc)
    return parsed.astimezone(timezone.utc)


def draw(payload, requested_at):
    location = payload["location_info"]
    forecast = payload["forecast_data"]
    times = [as_utc(value) for value in forecast["time"]]
    if not times:
        raise ValueError("No timestamp records found in forecast_data")
    if any(len(values) != len(times) for values in forecast.values()):
        raise ValueError("Length mismatch between time array and meteorological variable arrays")

    def y(name):
        # Convert None to NaN to preserve missing-data semantics rather than plotting false zeros.
        return np.array(
            [np.nan if value is None else float(value) for value in forecast[name]],
            dtype=float,
        )

    colors = {
        "navy": "#17324d", "blue": "#2878b5", "teal": "#168c8c",
        "orange": "#e07a2d", "coral": "#cf5c5c", "purple": "#8064a2",
        "gold": "#c49a28", "dark": "#34495e", "cyan": "#43a6b8",
    }
    plt.rcParams.update({
        "font.family": "DejaVu Sans", "font.size": 8.5,
        "axes.titlesize": 10, "axes.labelsize": 8.5,
        "xtick.labelsize": 7.5, "ytick.labelsize": 7.5,
        "legend.fontsize": 7.1, "axes.edgecolor": "#b8c2cc",
        "axes.linewidth": 0.7, "grid.color": "#dbe2e8",
        "grid.linewidth": 0.55, "grid.alpha": 0.75,
        "savefig.bbox": "tight",
    })

    fig, axes = plt.subplots(
        8, 1, figsize=(16, 20.5), sharex=True,
        gridspec_kw={"height_ratios": [1.05, 1.2, .82, 1, .72, 1.25, .78, .8]},
    )
    fig.subplots_adjust(left=.075, right=.985, top=.932, bottom=.065, hspace=.24)
    fig.text(
        .075, .975, f"{location['name'].upper()} | 15-DAY HOURLY CITY FORECAST",
        color=colors["navy"], fontsize=16, fontweight="bold", ha="left", va="top",
    )
    fig.text(
        .075, .953,
        f"{location.get('admin1', '')}, {location.get('country', '')} | "
        f"{len(times)} hourly records | ALL TIMES UTC | "
        f"{times[0]:%d %b %Y %H:%M} - {times[-1]:%d %b %Y %H:%M} UTC",
        color="#536273", fontsize=9, ha="left", va="top",
    )
    for ax in axes:
        ax.grid(True, axis="y")
        ax.grid(True, axis="x", alpha=.38)
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)
        ax.axvline(requested_at, color="#596a7b", lw=1, ls=(0, (4, 3)), zorder=5)

    # 1. Temperature: three variables sharing a common Celsius axis.
    for key, label, color, style in [
        ("t2m", "2 m air temperature | t2m", colors["navy"], "-"),
        ("d2m", "2 m dew point | d2m", colors["teal"], "-"),
        ("skt", "Skin temperature | skt", colors["orange"], "--"),
    ]:
        axes[0].plot(times, y(key), color=color, lw=1.4, ls=style, label=label)
    axes[0].set_ylabel("deg C")
    axes[0].set_title("01  Temperature", loc="left")
    axes[0].legend(loc="upper left", ncol=3)

    # 2. Wind: u/v are signed orthogonal components; gust is non-negative.
    wind = [
        ("u10", "10 m eastward | u10", colors["blue"], "-"),
        ("v10", "10 m northward | v10", colors["teal"], "-"),
        ("u100", "100 m eastward | u100", colors["orange"], "--"),
        ("v100", "100 m northward | v100", colors["purple"], "--"),
        ("fg10", "10 m gust | fg10", colors["coral"], ":"),
    ]
    for key, label, color, style in wind:
        axes[1].plot(times, y(key), color=color, lw=1.15, ls=style, label=label)
    axes[1].axhline(0, color="#8995a1", lw=.65)
    axes[1].set_ylabel("m/s")
    axes[1].set_title("02  Wind components and gust", loc="left")
    axes[1].legend(loc="upper left", ncol=3)

    # 3. Pressure: both in hPa, but representing different reference levels.
    axes[2].plot(times, y("msl"), color=colors["navy"], label="Mean sea-level pressure | msl")
    axes[2].plot(times, y("sp"), color=colors["gold"], ls="--", label="Surface pressure | sp")
    axes[2].set_ylabel("hPa")
    axes[2].set_title("03  Atmospheric pressure", loc="left")
    axes[2].legend(loc="upper left")

    # 4. Hourly water fluxes as grouped bars; snow depth (state variable) as a dashed line.
    bar_width = (1 / 24) * .22  # Matplotlib date unit is 1 day; 1 hour = 1/24 day.
    x = mdates.date2num(times)
    for key, label, color, offset in [
        ("tp", "Precipitation | tp", colors["blue"], -bar_width),
        ("sf", "Snowfall | sf", colors["cyan"], 0),
        ("ro", "Runoff | ro", colors["orange"], bar_width),
    ]:
        axes[3].bar(x + offset, y(key), width=bar_width, color=color,
                    alpha=.72, linewidth=0, label=label)
    axes[3].plot(times, y("sd"), color=colors["dark"], ls="--", label="Snow depth | sd")
    axes[3].set_ylabel("mm")
    axes[3].set_title("04  Precipitation, snow and runoff", loc="left")
    axes[3].legend(loc="upper left", ncol=4)

    # 5. Cloud cover is expressed as a 0-1 fraction rather than a percentage.
    axes[4].fill_between(times, 0, y("tcc"), color=colors["cyan"], alpha=.17)
    axes[4].plot(times, y("tcc"), color=colors["teal"], label="Total cloud cover | tcc")
    axes[4].set_ylim(0, 1)
    axes[4].set_ylabel("fraction")
    axes[4].set_title("05  Cloud cover", loc="left")
    axes[4].legend(loc="upper left")

    # 6. Radiation fluxes in W/m2; sign conventions reflect directional flux definitions.
    radiation = [
        ("ssrd", "Surface solar downward | ssrd", colors["gold"], "-"),
        ("strd", "Surface thermal downward | strd", colors["purple"], "-"),
        ("ssr", "Surface net solar | ssr", colors["blue"], "--"),
        ("str", "Surface net thermal | str", colors["teal"], "--"),
        ("ttr", "Top net thermal | ttr", colors["coral"], ":"),
    ]
    for key, label, color, style in radiation:
        axes[5].plot(times, y(key), color=color, lw=1.05, ls=style, label=label)
    axes[5].axhline(0, color="#8995a1", lw=.65)
    axes[5].set_ylabel("W/m2")
    axes[5].set_title("06  Radiation fluxes", loc="left")
    axes[5].legend(loc="upper left", ncol=3)

    # 7. CAPE measures convective instability, not precipitation probability.
    axes[6].fill_between(times, 0, y("mucape"), color=colors["orange"], alpha=.14)
    axes[6].plot(times, y("mucape"), color=colors["orange"],
                 label="Most-unstable CAPE | mucape")
    axes[6].set_ylabel("J/kg")
    axes[6].set_title("07  Convective instability", loc="left")
    axes[6].legend(loc="upper left")

    # 8. Total column water and water vapor share units but represent distinct moisture budgets.
    axes[7].plot(times, y("tcw"), color=colors["blue"], label="Total column water | tcw")
    axes[7].plot(times, y("tcwv"), color=colors["teal"], ls="--",
                 label="Total column water vapor | tcwv")
    axes[7].set_ylabel("kg/m2")
    axes[7].set_title("08  Column water", loc="left")
    axes[7].legend(loc="upper left", ncol=2)

    locator = mdates.AutoDateLocator(minticks=7, maxticks=10, tz=timezone.utc)
    axes[-1].xaxis.set_major_locator(locator)
    axes[-1].xaxis.set_major_formatter(
        mdates.DateFormatter("%d %b", tz=timezone.utc)
    )
    axes[-1].set_xlim(times[0], times[-1])
    axes[-1].set_xlabel("Forecast validity | UTC")
    for ax in axes[:-1]:
        ax.tick_params(labelbottom=False)
    fig.text(
        .985, .012,
        f"Dashed line: API request time ({requested_at:%d %b %Y %H:%M} UTC). "
        "All 23 meteorological variables are shown; shared time axis is UTC.",
        ha="right", va="bottom", fontsize=7.3, color="#637282",
    )

    slug = re.sub(r"[^A-Za-z0-9]+", "_", location["name"]).strip("_")
    png = OUTPUT_DIR / f"{slug}_15_day_forecast.png"
    pdf = OUTPUT_DIR / f"{slug}_15_day_forecast.pdf"
    fig.savefig(png, dpi=240)
    fig.savefig(pdf)
    plt.close(fig)
    return png, pdf


if __name__ == "__main__":
    data, requested_at = fetch_forecast()
    png, pdf = draw(data, requested_at)
    print(f"Saved {png} and {pdf}")

Code Architecture & Implementation Highlights

Several subtle design choices in the script above address common meteorological plotting challenges:

Safe URL Encoding: Calling quote(LOCATION, safe=',') automatically percent-encodes spaces and special characters in city names while leaving the comma separator intact when passing Longitude,Latitude coordinate strings.
Marking the API Request Timestamp: Right as the HTTP request is dispatched, the script records datetime.now(timezone.utc) and draws a vertical dashed reference line across all eight panels. Because NWP models initialize at fixed synoptic hours (00Z, 06Z, 12Z, 18Z), an API call made midway through a cycle will often include a few initial hourly steps that have already elapsed. This reference line clearly separates the elapsed portion of the current model run from true future forecast hours.
Bar Width Scaling on Matplotlib Date Axes: In Panel 04 (precipitation, snowfall, and runoff), rather than passing datetime objects directly to bar(), we convert timestamps into floating-point numbers via mdates.date2num(times). Internally, Matplotlib represents date axes in units of days (1.0 = 1 day), meaning a 1-hour step equals 1/24 of a day. Setting bar_width = (1 / 24) * 0.22 and applying slight horizontal offsets places the three hourly water fluxes side by side without overlapping. Meanwhile, snow depth (sd)—an instantaneous state variable rather than an hourly flux—is overlaid as a dashed line to maintain clear visual hierarchy.
Parameterized Reusability & Dual-Format Export: The script dynamically constructs a sanitized filename from the resolved city name and exports both a 240 DPI PNG for web publishing and a lossless vector PDF for academic manuscripts or technical reports. Switching locations requires no changes to the plotting logic.

Post-Processing Tip: Building a Pandas DataFrame & Computing Scalar Wind Speed

If your workflow requires exporting the forecast to a tabular file or feeding features into a machine learning model, the API's columnar JSON structure lets you build a DataFrame and compute resultant wind speeds in just a few vectorized lines:

import pandas as pd
import numpy as np

# 1. Convert the columnar dictionary directly into a DataFrame with a UTC DatetimeIndex
df = pd.DataFrame(data["forecast_data"])
df["time"] = pd.to_datetime(df["time"], utc=True)
df.set_index("time", inplace=True)

# 2. Compute 10 m and 100 m scalar wind speeds (m/s) via vectorized hypotenuse calculation
df["ws10"] = np.hypot(df["u10"], df["v10"])
df["ws100"] = np.hypot(df["u100"], df["v100"])

# 3. Export to CSV or compressed Parquet
df.to_csv("los_angeles_forecast.csv")

Using np.hypot(u, v) computes the Euclidean norm sqrt(u² + v²) with C-level vectorization while guarding against numerical overflow, processing hundreds of hourly records instantaneously.

How to Read the Meteogram: Multi-Variable Synoptic Diagnostics

Once the multi-panel meteogram is generated, you can diagnose weather systems by scanning vertically across the shared timeline:

Verify Header Metadata & Timezone Baseline: The subtitle explicitly locks in the administrative division, record count, and exact UTC validity window. Including this spatiotemporal provenance prevents timezone misinterpretations when sharing charts across distributed international teams.
Cross-Panel Vertical Diagnostics: Setting sharex=True enables synoptic-scale pattern recognition across panels. For instance, if you spot a prominent blue precipitation bar (tp) in Panel 04, scan vertically along that exact timestamp: in Panel 01, air temperature (t2m) and dew point (d2m) will typically converge (near-surface saturation); in Panel 03, mean sea-level pressure (msl) often dips into a local trough (frontal or low-pressure passage); moving downward, Panel 05 shows total cloud cover (tcc) pinning at 1.0, Panel 06 reveals a sharp attenuation in downward solar radiation (ssrd), and Panel 08 shows total column water vapor (tcwv) peaking. Weather events never occur in isolation—multi-panel alignment exposes the underlying physical coupling.
Dual-Labeled Legends ("Physical Name | Field Key"): Every legend entry pairs a descriptive name with its exact JSON key (e.g., 2 m air temperature | t2m). Domain analysts can read the physical quantity at a glance, while software engineers can immediately map any curve back to its corresponding API field.

From Visualization to Operations: Domain Applications for Hourly Forecasts

Combining 15-day medium-range visibility with hourly temporal resolution and global point coverage unlocks practical applications across numerous industries. In production systems, meteorological data serves as the primary environmental input, which must then be combined with domain-specific constraints and risk thresholds:

Scientific Research & Environmental Modeling: Serves as forcing data for hydrological, ecological, and urban climate models, or for multi-site meteorological intercomparisons. When publishing research, uphold reproducibility standards by documenting the retrieval timestamp, coordinate definitions, UTC baseline, and missing-data handling procedures.
Precision Agriculture & Field Operations: Hourly windows help agronomists schedule irrigation, time pesticide or fertilizer applications (avoiding high wind drift and subsequent wash-off from rain), and trigger frost mitigation or early harvests by monitoring nocturnal t2m and skin temperature (skt). Operational decisions should integrate local soil moisture sensors, crop varieties, and phenological stages.
Logistics & Transportation Routing: Screening wind speed, gusts, precipitation, and snow depth over a two-week horizon helps supply-chain planners identify potential weather disruptions along highway corridors or port terminals. For safety-critical aviation, maritime, or highway closure decisions, always defer to official aviation/marine weather advisories and traffic control authorities.
Grid Load Forecasting & Renewable Energy Trading: Ambient temperature and dew point directly drive urban HVAC heating and cooling demand, while 100 m hub-height winds (u100/v100) and downward shortwave solar radiation (ssrd) are the primary predictors for wind and solar power generation. Operational trading models should couple these weather inputs with NWP ensemble error distributions, grid dispatch rules, and energy storage capacity.
Outdoor Events, Aerial Photography & Drone Operations: A 15-day horizon supports initial scheduling and site selection; within 1 to 3 days of execution, teams should transition to the latest rolling NWP updates alongside on-site anemometers and micro-weather stations.
Cultural Heritage & Ecological Conservation: Historic monuments, cave murals, and nature reserves are highly vulnerable to rapid thermo-hygrometric swings, heavy surface runoff (ro), and intense solar radiation. Hourly forecasts allow conservation teams to schedule preventive inspections; for indoor display cases or subterranean chambers, pair external forecasts with local IoT micro-environmental sensors.

Finally, bear in mind a fundamental scientific distinction: do not conflate weather forecasting with climate change assessment. A 15-day hourly forecast addresses short- to medium-range atmospheric evolution. If your objective is to evaluate multi-decade drought trends, extreme heatwave frequency, or long-term wind resource bankability, do not extrapolate a 15-day forecast—instead, switch to the platform's Global City Historical Weather dataset (10+ years of hourly records) or dedicated climate reanalysis archives.

Conclusion: Turning Visualizations into Auditable Engineering Records

By exposing clean RESTful APIs and standard scientific file formats, Global Weather Data spares engineering teams the heavy lifting of ingesting and decoding raw meteorological bulletins (such as multi-gigabyte GRIB2 files from national weather centers). Once the data is in hand, what elevates a chart from a casual plot to a decision-ready engineering artifact is not merely a polished color palette—it is an unambiguous UTC time baseline, physically consistent unit groupings, explicit NaN handling for missing data, and clear provenance markers.

We hope this guide and the accompanying Python script serve as a practical addition to your meteorological data toolkit. Pick a target city, run the script, and start exploring how the atmosphere will evolve over the next fifteen days.

Data Access: Global Weather Data · City Forecast Dashboard

Global Weather Data User Guide

zhiyuan — Mon, 19 Oct 2026 10:37:33 +0000

Global Weather Data User Guide

Global Weather Data (https://global-weather-data.com/) is a platform that provides global weather forecasts and historical weather data, offering tools for searching, visualizing, and downloading information. Designed to be as user-friendly as possible, the platform enables users worldwide to access the weather data they need. Users can search for any inhabited location globally—using a place name, ID, or geographic coordinates (latitude and longitude)—to retrieve relevant weather forecasts and historical data. Data can be downloaded directly in CSV format, or accessed programmatically via an API.

The platform includes the following types of weather data:

City weather forecasts (hourly data for the next 15 days, covering 20+ meteorological variables).
Gridded weather forecasts (hourly data for the next 15 days, based on a global 0.25° grid, covering 20+ meteorological variables).
Historical weather data (hourly data for over 12,000 towns and cities globally, spanning more than 10 years, covering 20+ meteorological variables).

1. Weather Forecast Data

In the weather forecast panel, users can search for a location by entering a place name (in any language), geographic coordinates, or an ID. The platform covers over 12,000 inhabited locations worldwide with populations exceeding 50,000, including cities, towns, and villages. The ID used is the "geonameID"—a unique identifier assigned to locations globally by the GeoNames database. Once a keyword is entered, the system automatically identifies and matches the most relevant location. Selecting a location loads an hourly weather forecast chart for the next 15 days; users can then click the "Download Data" button in the top-right corner to export the complete forecast dataset.

The forecast data is sourced from the ECMWF (European Centre for Medium-Range Weather Forecasts) and includes over 20 meteorological variables—such as air temperature, atmospheric pressure, wind speed, wind direction, humidity, solar radiation, ground temperature, soil moisture, and runoff—all provided with an hourly resolution. The API testing section below automatically generates an API call URL for the selected location. Clicking the "Test API" button retrieves a 15-day weather forecast, which can be accessed directly via a web application. Users also have the option to download the data as a CSV file. The API parameter documentation explains the available parameters; to retrieve a weather forecast for any location worldwide, simply provide a location identifier—such as a place name, an ID, or geographic coordinates—and the system will automatically identify the best match.

The table below provides detailed definitions, names, and physical units for all meteorological variables.

II. Gridded Forecast Data

On the gridded forecast data page, you can test API calls for weather forecasts across any specified geographic area (defined by latitude and longitude ranges). By providing the geographic range, the specific meteorological variable, and the desired time, the system returns a dataset with a 0.25° resolution. This represents the forecast for a given meteorological variable over a specific global region at a particular time within the next 15 days. This structured, gridded data can be overlaid onto geographic boundaries to create heatmaps or contour plots, or it can be imported into models for training purposes.

III. Historical Weather Data

In the historical weather data panel, users can select any location worldwide—again, by entering a place name, ID, or geographic coordinates—and the system will automatically identify the best match. This loads a chart displaying historical weather data for the past 15 days, covering over 20 parameters such as temperature, air pressure, precipitation, and radiation. Users can also download the complete historical dataset; please note that because the historical data spans a long period (over 10 years) and features high temporal resolution (hourly data), the download process may take several seconds to initiate.

The API testing section below automatically generates a URL for historical weather data for a given location. You can construct your own API request by adjusting the location and time-span parameters to quickly retrieve hourly historical weather data—covering the past few days, weeks, or even hundreds of days. Please note that longer time spans may result in slightly higher latency in the API response. The historical weather data is sourced from ERA5 and typically becomes available in the database with a delay of several days; for instance, if you request data for the "past day," the most recent available records may actually date back 7 to 10 days.
The table at the very bottom provides detailed definitions, names, and physical units for all available meteorological variables.