Under the hood
How wx answers a request, where its numbers come from, and how to check them yourself. The limits and durations on this page come from the code that serves it and are checked against its configuration by tests.
The stack
- Clients: anything that speaks HTTP. The same URL gives a terminal text, a browser a page and a program JSON.
- The edge: one Cloudflare Worker written in plain TypeScript, with no framework. It reads the URL, applies the limits, keeps the cache, works out the statistics and draws the answer.
- Upstream: the Open-Meteo forecast and geocoding APIs. One forecast call fetches all 8 models for 7 days.
What happens to your request
- Method. Only GET and HEAD are answered. Anything else gets
405. - Options. The path is the place and the query holds the options. An unknown option or a bad value gets
400, and the body lists the valid options. - Your allowance. Each IP address may make 30 requests a minute. After that:
429Too Many Requests, withRetry-After: 60. - The place. Coordinates are used as given. A place name goes to the geocoder once and the answer is kept for 30 days. A name that is not found is remembered for 6 hours (
404), so a typo costs the shared budget once, not on every attempt. - The forecast cache. Coordinates are rounded to 0.1 degrees (about 11 km), so nearby requests share one copy. A copy is fresh for 30 minutes and kept for 6 hours.
- The shared budget. Only a cache miss calls Open-Meteo, and it has to fit two budgets: 3 uncached lookups a minute per IP address, and about 5 a minute per Cloudflare location. Cloudflare documents these limits as approximate and per location.
- When upstream says no. If a budget is spent or Open-Meteo fails, wx serves the copy it kept and says so:
"stale": truein JSON and a cached copy note in the panel. With no copy to fall back on, the answer is503for a spent budget or502for a failed call. - The answer. The same data becomes a panel for terminals, a page for browsers, JSON for programs, one line for status bars or a postcard. Data responses carry
X-Data-Source: Open-Meteo.com (CC BY 4.0).
In practice: thirty requests for Auckland share one place lookup and one forecast call. Requests for thirty different towns need about sixty upstream calls, and if they all reach the same Cloudflare location, a budget of about 5 a minute turns most of them away.
Methods
- Consensus is the median of the models for that hour.
- Percentiles (the bands, and
p25andp75in JSON) use linear interpolation between order statistics, which is NumPy's default, sonumpy.percentilegives the same numbers. - Spread is the warmest model minus the coolest. With fewer than 3 models it is not shown.
- Daily maximum and minimum count for a model only when all 24 hours are present. Otherwise the cell shows
-. - The weather symbol is the most common WMO weather code across the models. A tie goes to the more severe code.
- Postcards draw the sky from that code, rain density from the models' median rain rate, and the sun from the NOAA solar position equations. Help explains every mark.
JSON rounds values to one decimal place and the statistics are worked out before rounding, so a check made from the rounded values can differ by up to about 0.1.
Status codes you can trigger
| Code | When | Try |
|---|---|---|
200 | It worked | curl wx.rejusamjohn.workers.dev/auckland |
400 | Unknown option or bad value | curl 'wx.rejusamjohn.workers.dev/auckland?zzz' |
404 | Place not found | curl wx.rejusamjohn.workers.dev/zzqqxx |
405 | Method other than GET or HEAD | curl -X POST wx.rejusamjohn.workers.dev/auckland |
429 | More than 30 requests a minute from one address | Please do not try this on purpose |
502 | Open-Meteo failed and nothing is cached | Not on demand |
503 | Upstream budget spent and nothing is cached | Not on demand |
Reproduce it yourself
The wx API notebook takes one wx response apart with requests and pandas, checks the statistics with NumPy, and walks through the steps above from the outside.
curl 'wx.rejusamjohn.workers.dev/auckland?format=json'curl -i 'wx.rejusamjohn.workers.dev/auckland?zzz'curl -I wx.rejusamjohn.workers.dev/wellingtoncurl 'wx.rejusamjohn.workers.dev/christchurch?models=ecmwf,gfs&days=2'
Privacy
No cookies, no analytics and no stored IP addresses. The address is used as the key for the rate limits, and invocation logs are switched off. Your approximate location is used only to answer the request: to find you for /, and to choose °C or °F when no unit is given.
Weather data by Open-Meteo.com (CC BY 4.0)