Weather API: current conditions and forecast as JSON

Before the first request

Who may call it

Anyone, today, without a credential: these three routes are in the public namespace /api/public/v1. They are rate-limited per client and per route, HELPERG offers no service-level agreement for them, and additive fields may appear at any time; a breaking change would be a new version segment, not a change to these paths. There is no paid tier and nothing to sign up for — and therefore no promise about tomorrow beyond the versioning rule.

Whose data it is

MET Norway’s, from its Locationforecast service, under CC BY 4.0. Every response carries the attribution text the licence asks for, and meta.attributionRecords[].required is true: show it wherever you show the readings. The readings are model output for a point, published by the provider — not a station observation, not a measurement, and HELPERG does not alter the values.

Where the point goes

Coordinates are rounded to 2 decimal places (about 1.1 km) before the provider is asked, and the point in the body is the one served. That is the provider’s own terms for anonymous use, and it means two callers inside the same square share one cached answer.

Quickstart

The coordinate in these examples is central Prague. Replace it with your own point; the response shape is the same for any coordinate.

curl

curl -sS "https://helperg.com/api/public/v1/weather/current?lat=50.0755&lon=14.4378"
curl -sS "https://helperg.com/api/public/v1/weather/forecast?lat=50.0755&lon=14.4378&hours=12&days=5&tz=Europe/Prague"

JavaScript

// Node.js 18+ or any runtime with fetch. No key, no header beyond Accept.
const response = await fetch("https://helperg.com/api/public/v1/weather/forecast?lat=50.0755&lon=14.4378&days=3&tz=Europe/Prague", {
  headers: { Accept: "application/json" },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`); // 400, 429 or 503: see Errors below
const { data, meta } = await response.json();
for (const day of data.forecast.days) {
  console.log(day.date, day.temperatureMinC, day.temperatureMaxC, day.condition.code);
}
console.log(meta.attributionRecords[0].text); // show this wherever the readings are shown

Python

import json, urllib.request

url = "https://helperg.com/api/public/v1/weather/current?lat=50.0755&lon=14.4378"
with urllib.request.urlopen(urllib.request.Request(url, headers={"Accept": "application/json"})) as r:
    body = json.load(r)
current = body["data"]["current"]
print(current["temperatureC"], current["condition"]["code"], current["providerModelUpdatedAt"])
print(body["meta"]["attributionRecords"][0]["text"])

Units, freshness and what “current” means

Units

Metric by default: degrees Celsius, metres per second, hectopascals, millimetres; meta.canonicalUnits states them. With units=imperial the values are converted and the field names say so; the body’s units field names the system in use, so a reading is never shown in one unit and stored in another.

How fresh: three layers, no fixed lag

The HTTP response carries Cache-Control: public, max-age=600 for current conditions and max-age=1800 for the forecast: a shared cache, or your own, may hold a response that long on top of everything below. Underneath, HELPERG keeps the provider’s payload for as long as the provider’s own Expires header says, clamped to 5 minutes to 1 hour for current conditions and 15 minutes to 6 hours for the forecast; when that passes it asks again with If-Modified-Since, and a 304 keeps the same payload with meta.cacheAgeSeconds back at 0 — so 0 means “just confirmed with the provider”, not “just produced”. The provider’s model run is providerModelUpdatedAt; meta.fetchedAt is when the payload was fetched or last confirmed. If the provider cannot be reached once the copy has expired, the expired copy is served with meta.stale: true, meta.degraded: true and its real age, for as long as that age — counted from the fetch or the last 304 confirmation, not from the expiry — is at most 22200 seconds (370 minutes) for current conditions and 90000 seconds (25 hours) for the forecast: the policy’s default TTL (10 minutes and 1 hour) plus its stale allowance (6 hours and 24 hours), whatever Expires actually set. A copy older than that is not served: the route answers 503. There is no promise of a maximum lag behind the provider’s newest run: a reading can be as old as these layers add up to, and the fields above say how old.

What “current” means

observedAt is the time of the first entry of the series the provider returned when the payload was fetched — normally the hour then in progress. The payload is reused for as long as the layers above allow and observedAt stays where it was, so with an older copy it can sit hours behind the clock: compare it with meta.fetchedAt and meta.cacheAgeSeconds before calling a reading “now”. It is never the time of a measurement, because none was taken; if your product needs observations from stations, this is not the source for it.

What this API does not provide

• Warnings and alerts. A warning belongs to the meteorological authority that issued it; this deployment carries no authority feed and derives none from a threshold.
• Sunrise, sunset, moon. They come from a different MET Norway service that this deployment does not call.
• History. Only the current run and its horizon; past readings are not stored and cannot be requested.
• More than the provider publishes. About 48 hours of hourly and roughly nine to ten days of daily values; there is no 14-day forecast because there is none at the source.
• Radar, satellite, air quality. Not part of the service read.
• A guarantee of availability. The status of the weather domain is public at API status; that page, not this one, is the place to check before relying on a call.

Attribution text to show with the readings: Weather data from MET Norway (Norwegian Meteorological Institute), CC BY 4.0 — the exact wording and links are in every response under meta.attributionRecords. Full provider detail on the sources page; the economic endpoints have their own quickstart.