API reference

Basics

• Base URL: https://www.wxdial.com/api/v1 (HTTPS only).
• Method: every endpoint is a read-only GET. Responses are JSON (UTF-8).
• Times are ISO 8601 with the offset of the response's time zone, e.g. 2026-10-22T14:40:00-07:00. Dates are yyyy-MM-dd.
• Coordinates are decimal degrees (WGS 84): latitude −90…90, longitude −180…180.
• Missing values are null: a station that doesn't measure something (many airports have no sun sensor) returns null for it.
• CORS: responses allow any origin, so you can call the API from a browser. Keep in mind that a key in browser code is visible to anyone; use a server where you can.
• Versioning: fields may be added to responses at any time; build your parser to ignore fields it doesn't know. Fields are not removed or renamed within v1.

Authentication

Every request needs an API key. Create keys on your account page (up to 5; a key is shown once, when you create it). Send it in a header:

X-API-Key: wxd_your_key

or, where you can't set headers, as a query parameter: ?key=wxd_your_key (less safe: URLs end up in logs and browser history). A missing, wrong or revoked key gets 401. Revoke a key from your account page and it stops working immediately.

Units

Every weather endpoint accepts units:

Without units, you get your account's default (set on your account page), which is imperial unless you change it. Temperatures and wind are rounded to 1 decimal. Field names are the same in both systems, and responses include a units object saying which were used:

"units": { "system": "metric", "temperature": "°C", "wind": "km/h", "pressure": "hPa", "rain": "mm", "distance": "km", "timeZone": "America/Los_Angeles" }

Humidity is always %, wind direction degrees (0 = from the north, 90 = from the east), solar radiation W/m², and UV index the standard index.

Time zones

Every endpoint accepts tz, an IANA time zone name such as America/New_York, Europe/London or Asia/Tokyo, or UTC. It decides:

• How times are written. Every time in the response is given in that zone, with its offset, including daylight saving time: tz=America/Los_Angeles gives 2026-10-22T14:40:00-07:00, and tz=UTC gives the same moment as 2026-10-22T21:40:00+00:00. It's the same instant either way; only how it's written changes.
• What "today" means in /observations: the today high and low cover the current calendar day in that zone. For a station's own local highs and lows, pass the station's zone (it's in each observation's timeZone when known).

Without tz, you get your account's default time zone (set on your account page), which is UTC unless you change it. The zone used is named in the response's units.timeZone. An unknown name gets 400.

A few things always follow the station's own day, whatever tz says: today in /home and the date of each /home/history row (both are Venice Beach days), and today in /groups (each group's local day). Their times are still written in your zone.

Station types and ids

A station is named by its type and id, joined with a vertical bar: Type|Id, e.g. Nws|KLAX. That's the station value /stations returns, and what /observations takes. Types are case-insensitive. You can also filter station searches by type with type=, or to government and airport stations only with official=true.

Don't build ids by hand: find stations with /stations and use the station value it returns.

GET /stations

Finds stations. Give one of: q (a name or id), lat + lon (nearest first), or bbox (everything in a box).

GET https://www.wxdial.com/api/v1/stations?lat=33.99&lon=-118.47&official=true&limit=2

[
  { "station": "Nws|KSMO", "type": "Nws", "id": "KSMO", "name": "Santa Monica Airport",
    "latitude": 34.016, "longitude": -118.451, "distance": 2.3, "distanceUnit": "mi" },
  { "station": "Nws|KLAX", "type": "Nws", "id": "KLAX", "name": "Los Angeles Intl, CA",
    "latitude": 33.938, "longitude": -118.387, "distance": 5.8, "distanceUnit": "mi" }
]

GET /observations

The latest observation from up to 10 stations in one request.

GET https://www.wxdial.com/api/v1/observations?station=Nws|KLAX&station=Self|self&tz=America/Los_Angeles

{
  "units": { "system": "imperial", "temperature": "°F", "wind": "mph", "pressure": "inHg", "rain": "in", "distance": "mi", "timeZone": "America/Los_Angeles" },
  "stations": [
    {
      "station": "Nws|KLAX",
      "observation": {
        "name": "Los Angeles International Airport", "source": "NWS", "id": "KLAX",
        "latitude": 33.938, "longitude": -118.387, "timeZone": "America/Los_Angeles",
        "updated": "2026-10-22T21:53:00-07:00", "sky": "PTCLDY",
        "temperature": 66.0, "humidity": 70, "dewPoint": 55.9, "pressure": 29.96,
        "windDirection": 250, "wind": 12.7, "windGust": null, "solarWm2": null, "uvIndex": null,
        "rainRate": null, "rainToday": 0,
        "today": { "high": 74.0, "highAt": "2026-10-22T14:53:00-07:00", "low": 61.0, "lowAt": "2026-10-22T06:53:00-07:00", "partialSince": null },
        "climate": null, "error": null
      },
      "error": null
    },
    { "station": "Self|self", "observation": { "name": "Venice Beach", "source": "WxDial", … }, "error": null }
  ]
}

Stations come back in the order you asked. Each has observation (see the observation object) or null with an error: "Not an available station" (unknown type or bad id), "Station not found", "Source not responding" or "Source is busy, retrying". One failing station doesn't fail the request; the call still counts as one request.

GET /places

Cities and towns with WxDial weather pages (14,000+): every place of 30,000+ people worldwide, and of 5,000+ in the US, Canada, the UK, Ireland, Australia and New Zealand. Give q, or lat + lon, or country (optionally with region).

GET https://www.wxdial.com/api/v1/places?q=elmira&country=US&limit=1

[ { "place": "elmira-ny-us", "name": "Elmira", "display": "Elmira, NY", "country": "US", "region": "NY",
    "latitude": 42.0898, "longitude": -76.8077, "population": 28213, "timeZone": "America/New_York",
    "url": "https://www.wxdial.com/weather/elmira-ny-us", "distance": null, "distanceUnit": null } ]

GET /forecast

The forecast and today's outlook for one location. Give one of place (from /places), station (an official station: Nws|KELM, or just KELM) or lat + lon. Forecasts come from the National Weather Service in the US and MET Norway elsewhere (credit "MET Norway" if you show them; CC BY 4.0).

GET https://www.wxdial.com/api/v1/forecast?place=elmira-ny-us&tz=America/New_York

{
  "units": { "system": "imperial", "temperature": "°F", … },
  "location": { "name": "Elmira, NY", "place": "elmira-ny-us", "station": null, "latitude": 42.0898, "longitude": -76.8077, "timeZone": "America/New_York",
                "page": "https://www.wxdial.com/weather/elmira-ny-us" },
  "source": "National Weather Service", "sourceUrl": "https://www.weather.gov",
  "detailsUrl": "https://forecast.weather.gov/MapClick.php?lat=42.0898&lon=-76.8077", "radarUrl": "https://radar.weather.gov/station/kbgm/standard",
  "alerts": [ { "event": "Frost Advisory", "headline": "Frost Advisory issued …", "severity": "Minor", "ends": "2026-10-27T09:00:00-04:00" } ],
  "periods": [ { "name": "Today", "start": "2026-10-26T06:00:00-04:00", "isDaytime": true, "temperature": 64, "text": "Sunny",
                 "precipitationChance": null, "wind": "NW 5 to 10 mph", "detail": "Sunny, with a high near 64. …" }, … ],
  "hourly": [ { "time": "2026-10-26T13:00:00-04:00", "temperature": 63, "precipitationChance": 0, "text": "Sunny" }, … ],
  "sun": { "sunrise": "2026-10-26T07:32:00-04:00", "sunset": "2026-10-26T18:09:00-04:00", "daylightMinutes": 637 },
  "today": { "station": "Elmira-Corning Rgnl, NY", "normalLow": 38, "normalHigh": 58, "recordLow": 20, "recordLowYears": [1976], "recordHigh": 82, "recordHighYears": [1963] },
  "last24Hours": { "station": "Elmira-Corning Rgnl, NY", "readings": [ { "time": "…", "temperature": 52.0 }, … ] }
}

GET /climate

Daily climate for a station: the 1991–2020 normal high and low and the record high and low (with every year it happened) for every day of the year, plus a summary for each month. Available for US airport stations with 20+ years of daily records (see /climate/stations). With place or lat+lon, the nearest such station within 150 km is used. Data: NOAA Regional Climate Centers (ACIS), refreshed monthly.

GET https://www.wxdial.com/api/v1/climate?station=KELM&month=10&day=26

{
  "units": { "system": "imperial", "temperature": "°F", … },
  "station": { "station": "Nws|KELM", "id": "KELM", "name": "Elmira-Corning Rgnl, NY", "latitude": 42.16, "longitude": -76.89,
               "url": "https://www.wxdial.com/station/nws/kelm/climate" },
  "firstYear": 1948, "lastYear": 2026, "normalsPeriod": "1991-2020", "updated": "2026-10-26T…",
  "source": "NOAA Regional Climate Centers, Applied Climate Information System (ACIS)",
  "months": null,
  "days": [ { "date": "10-26", "month": 10, "day": 26, "normalLow": 37, "normalHigh": 56,
              "recordLow": 19, "recordLowYears": [1976, 1962], "recordHigh": 79, "recordHighYears": [1963] } ]
}

Without day, months lists each month: normalLow, normalHigh (averages of the daily normals), recordLow with recordLowDate (MM-dd) and recordLowYears, and the same for recordHigh. Record years are newest first; ties list every year. 404: no station with records nearby; 503: the station's records are still being prepared.

GET /climate/stations

The stations that /climate covers: all of them (by id), or the nearest first with lat + lon (limit, default 25). Each has station, id, name, position, firstYear, lastYear, hasNormals and the url of its climate page.

GET /regional

The closest official (government and airport) stations to a location that are reporting right now, nearest first, each with its latest observation: what the live page's "Official regional weather" table shows. Give one of place, station (that station is left out of the list) or lat + lon. Stations with nothing to report are skipped.

GET https://www.wxdial.com/api/v1/regional?station=KMDT&limit=3

{
  "units": { "system": "imperial", … },
  "location": { "name": "Harrisburg Intl, PA", "place": null, "station": "Nws|KMDT", "latitude": 40.1962, "longitude": -76.7725 },
  "stations": [
    { "station": "Nws|KCXY", "name": "Harrisburg/Capital City Arpt, PA", "latitude": 40.2184, "longitude": -76.8552, "distance": 4.6,
      "page": "https://www.wxdial.com/station/nws/kcxy", "observation": { "temperature": 47.0, "humidity": 71, … } }, …
  ]
}

Each call counts as one request, however many stations it returns. distance is in km or miles (see Units).

GET /radar

What's falling at a location right now, from WxDial's own radar with the precipitation type: the lower 48 US states every 4 minutes from NOAA's Multi-Radar Multi-Sensor (MRMS) system, southern Canada every 6 minutes from Environment and Climate Change Canada's surface precipitation type, and most of Europe every 10 minutes from EUMETNET OPERA's composite (CC BY 4.0). Give one of place, station or lat + lon. Also lists the frames of the last two hours, for /radar/image.

GET https://www.wxdial.com/api/v1/radar?place=elmira-ny-us

{
  "location": { "name": "Elmira, NY", "place": "elmira-ny-us", "station": null, "latitude": 42.0898, "longitude": -76.8077 },
  "time": "2026-10-27T07:12:00-04:00",
  "precipitation": { "type": "ice/mix", "intensity": "moderate", "dbz": "15–25", "estimated": true },
  "note": "Ice/mix (freezing rain or sleet) is estimated from airport reports and NOAA model temperatures.",
  "frames": [ { "time": "2026-10-27T06:16:00-04:00", "id": 1793096160000 }, …, { "time": "2026-10-27T07:12:00-04:00", "id": 1793099520000 } ],
  "image": "https://www.wxdial.com/api/v1/radar/image?frame={id}&bbox={west},{south},{east},{north}&size={width},{height}",
  "source": "NOAA Multi-Radar Multi-Sensor (MRMS) SeamlessHSR and PrecipFlag; colors and ice/mix estimate by WxDial"
}

404: the location is outside WxDial's radar (NOAA's strength-only radar for Alaska, Hawaii, Puerto Rico and Guam isn't part of this API). 503: the radar is briefly unavailable.

GET /radar/image

One radar frame as a transparent PNG covering a box, in the same colors as WxDial's maps: rain green → yellow → red, snow light → dark blue, ice/mix pink, hail purple. The image is in plain latitude/longitude (EPSG:4326, equirectangular): stretch it over the box on your map. Every region is drawn in each image (the other regions' frames nearest the frame's time). Each image counts as one request. Images of Europe include EUMETNET OPERA data: credit "EUMETNET OPERA, CC BY 4.0" where you show them.

GET https://www.wxdial.com/api/v1/radar/image?bbox=-80.5,39.5,-73.5,44.5&size=700,500

For an <img> tag, the key can go in the address as &key= (keep such pages private: the key is visible).

GET /home

Current conditions at WxDial's own station in Venice Beach, California, a block from the ocean. Its temperature is solar-corrected: the sun-driven warm bias of the sensor is removed minute by minute (sensorTemperature is the uncorrected value). Updated every minute.

{
  "units": { "system": "imperial", … },
  "station": "Venice Beach", "latitude": 33.985905, "longitude": -118.471176, "timeZone": "America/Los_Angeles",
  "observed": "2026-10-22T21:33:04-07:00", "updated": "2026-10-22T21:33:04-07:00",
  "temperature": 70.1, "sensorTemperature": 70.4, "solarCorrection": 0.3,
  "humidity": 78.6, "dewPoint": 63.1, "heatIndex": 70.1,
  "wind": 2.2, "windAvg10": 2.2, "windGust10": 5.5, "windDirection": 297,
  "pressure": 29.96, "pressureTrend3h": 0.01,
  "solarWm2": 0, "uvIndex": 0, "sky": "CLEAR",
  "rain": { "today": 0, "rate": 0, "month": 0.6, "rainYear": 0.6 },
  "storm": { "inProgress": false, "total": 0.54, "start": "2026-10-19T…", "end": "2026-10-20T…" },
  "today": { "high": 77.4, "highAt": "2026-10-22T14:40:00-07:00", "low": 69.8, "lowAt": "2026-10-22T03:50:00-07:00" }
}

(Shown with tz=America/Los_Angeles.)

GET /home/history

One row per completed day at Venice Beach, oldest first. Records start on August 15, 2026.

{ "units": { … }, "days": [
  { "date": "2026-10-21", "low": 63.3, "lowAt": "…", "high": 77.4, "highAt": "…", "sensorLow": 63.3, "sensorHigh": 78.9, "rain": 0.6 }
] }

low/high are solar-corrected; sensorLow/sensorHigh are the sensor's own. rain is the day's total; null if unknown.

GET /groups

The station groups shown on the WxDial home page (for example "Around the area"), each with its stations' latest observations, including normals and records for the day where available.

Parameters: units, tz (for the times; each group's today is its own local day).

{ "units": { … }, "groups": [ { "title": "Around the area", "timeZone": "America/Los_Angeles", "stations": [ { observation… }, … ] } ] }

GET /usage

Your plan, limits and usage. Free: this call doesn't count toward your limits.

{ "plan": "developer", "name": "API for Developers", "perMinute": 60, "perDay": 10000, "perMonth": 100000,
  "overageBilled": true, "today": 1532, "thisMonth": 48210, "overagePending": 0,
  "defaults": { "units": "imperial", "timeZone": "America/Chicago" } }

plan is personal, developer, business or custom. overagePending is requests over your allowance not yet billed (paid plans). defaults are the units and time zone your account uses when a request doesn't give units or tz.

The observation object

Sky and weather codes

sky uses short codes; new ones may appear, so show unknown codes as they are.

Attribution

On the Personal (free) plan, wherever you show the data, show "Weather data: WxDial" near it, linked to https://www.wxdial.com or to the matching WxDial page (location.page in /forecast, page in /regional). Without a place for a link (print, screens, voice), the words alone are enough; you may qualify the link (rel="nofollow" is fine). Paid plans need no WxDial credit. Every free-plan response includes X-Attribution: Weather data: WxDial (https://www.wxdial.com) as a reminder. Credit the original sources on every plan (see API Terms).

<a href="https://www.wxdial.com/weather/elmira-ny-us">Weather data: WxDial</a>

Limits and headers

Every request counts as one, including requests refused for bad parameters, except /usage and requests refused with 429. Days and months are UTC. The per-minute limit is a hard limit on every plan. Each response carries:

Errors

Errors return JSON with an error message:

{ "error": "Unknown station type 'Bogus'. Types: Nws, Metar, EcSwob, Dwd, Jma, MetOffice, WeatherLinkPublic, AmbientPublic, Aprs, Self, AmbientFeed" }

Freshness and good practice

• WxDial caches each station for roughly its source's update interval (one minute for private stations, five minutes for airports outside the US, up to an hour for the Met Office). Polling faster than that returns the same data and uses up requests.
• Always check updated: a station that has stopped reporting keeps returning its last observation.
• Ask for several stations in one /observations call rather than one call each.
• Station lists change slowly: cache /stations results for a day or more.
• If you show the data publicly, credit its sources: National Weather Service, Aviation Weather Center, Environment and Climate Change Canada, Deutscher Wetterdienst, Japan Meteorological Agency, Met Office, WeatherLink, Ambient Weather or CWOP, plus WxDial.
• Data is provided as is, without warranty. See the API Terms.

Questions or something missing here? Contact us.