wx All options

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

What happens to your request

  1. Method. Only GET and HEAD are answered. Anything else gets 405.
  2. 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.
  3. Your allowance. Each IP address may make 30 requests a minute. After that: 429 Too Many Requests, with Retry-After: 60.
  4. 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.
  5. 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.
  6. 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.
  7. When upstream says no. If a budget is spent or Open-Meteo fails, wx serves the copy it kept and says so: "stale": true in JSON and a cached copy note in the panel. With no copy to fall back on, the answer is 503 for a spent budget or 502 for a failed call.
  8. 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

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

CodeWhenTry
200It workedcurl wx.rejusamjohn.workers.dev/auckland
400Unknown option or bad valuecurl 'wx.rejusamjohn.workers.dev/auckland?zzz'
404Place not foundcurl wx.rejusamjohn.workers.dev/zzqqxx
405Method other than GET or HEADcurl -X POST wx.rejusamjohn.workers.dev/auckland
429More than 30 requests a minute from one addressPlease do not try this on purpose
502Open-Meteo failed and nothing is cachedNot on demand
503Upstream budget spent and nothing is cachedNot 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.

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)