The aurora data behind this site, as JSON

curl https://lumavik.org/api/v1/cities.json

That returns every place this site has published a latitude for, with the geomagnetic coordinate the aurora actually responds to and the two different Kp thresholds that apply to it. No key, no account, no rate limit beyond ordinary fair use, and no origin restriction — browser JavaScript is a first-class consumer here. It is licensed CC BY 4.0, which means you may reuse it commercially as long as you link back to this page or to the endpoint you took it from.

What is published

Five datasets, plus an OpenAPI 3.1 description of all of them and a status document that says when each was last rebuilt. Everything is a static file regenerated with the site, so the failure mode worth watching is a generated_at that has stopped moving, not a 5xx.

The entry point is index.json, which names every other URL in one fetch. The machine-readable description is openapi.json, and it is worth reading rather than skimming: the field descriptions in it carry the semantics that a field name cannot, which is the part implementers get wrong.

The one thing to get right before you use any of it

There are two different numbers on this site that both look like "the Kp you need", they differ by as much as three steps at mid-latitudes, and quoting one while meaning the other is the most common mistake made with aurora data generally. Both are published, both are named, and neither is wrong.

The first is kp_oval_overhead. It is the Kp at which the modelled auroral oval has expanded far enough that emission is being produced roughly above a given geomagnetic latitude. It comes from the oval-edge table, which is the same model the calculators on this site run.

The second is kp_visible_from_area. It is the estimate published on the relevant article of when a display becomes worth going outside for from that place, which is a lower number. The reason is geometry rather than optimism: auroral emission sits around 100 kilometres above the surface, and the geometric horizon of something at that altitude is roughly 1100 kilometres. An observer well outside the oval can see it low on the poleward horizon, which is exactly how the aurora is usually seen from mid latitudes.

If you are building something that answers "can I see it from here", the lower number is usually the one a person means, and saying which one you used costs a clause and prevents an argument.

Field semantics a schema cannot carry

Geomagnetic latitude is not map latitude, and the difference is not small. The auroral oval is a ring centred on the geomagnetic pole, which currently sits near 80.8° N, 72.7° W — nowhere near the geographic pole. So Minneapolis, eleven degrees south of Edinburgh on a map, lands within two degrees of it magnetically, while Moscow is level with Edinburgh on a map and five degrees below it magnetically. Any tool that sorts aurora prospects by map latitude will get the ordering of those three cities wrong. The corrected_geomagnetic_latitude field is the one that predicts anything.

That coordinate is an approximation, and the API says so in every payload. The transform used here is the tilted-dipole model, which differs from corrected geomagnetic coordinates computed from the full IGRF field by up to about two degrees in places. Two degrees is one Kp step near a threshold. It is the right tool for deciding roughly what a location needs and the wrong tool for settling an argument about one degree.

Kp is a time average, a planetary number, and a retrospective one. It is reported once per three-hour UT interval on a quasi-logarithmic scale, derived from thirteen subauroral observatories, and published after the interval it describes. Three consequences follow, and each of them is regularly got backwards. A Kp figure should be described as "the last three-hour value", never as a current reading. Kp values must never be averaged arithmetically — that is what the linear index ap exists for. And a substorm can put on a twenty-minute display that never shows up in the three-hour number at all, which is why an alert that stayed quiet during a good night was not necessarily broken.

The oval edge is a modelled ring, not a boundary line. The oval_edge_geomagnetic_latitude field says where emission typically reaches at that Kp. It moves within a single three-hour interval, it is not circular in practice, and because of the horizon geometry above it is not a fence you have to be inside. Treating the coloured band on a forecast map as a catchment area is the same error in a different form.

Darkness is a hard constraint and it is the one people forget. The dark_hours fields count hours with the sun more than 18 degrees below the horizon — astronomical twilight. A softer threshold would overstate the season, because a faint arc is not visible while the sky is still brightening. Above roughly 60 degrees the sky does not get astronomically dark at all for part of the summer, and during that window the answer to "will I see the aurora" is no regardless of what the Sun is doing. A row whose dark_hours_midsummer is zero is telling you the season is closed, not that the data is missing.

A null is a fact here, not an omission. A kp_oval_overhead of null means that even an extreme Kp 9 storm does not normally bring the modelled oval overhead at that location. The southern-hemisphere rows carry null for every geomagnetic field on purpose: the source page uses published geographic latitudes there because southern corrected geomagnetic values could not be verified, and a plausible invented coordinate would be worse than a missing one.

What this API is not

It is not live, and it will not become live. Every figure here describes what a place needs; none of it describes what the Sun is doing tonight. That is a deliberate split, because the live half already exists, is excellent, is free and is in the public domain — and the most useful thing this page can do is point at it rather than proxy it.

The full registry — 41 documents from 18 publishing bodies, each verified to resolve on the date recorded against it — is in sources.json. It exists because a reference site with no attribution is a rewrite of the same ten sources everybody else rewrote, and because the question "where does aurora data actually come from" deserves a machine-readable answer.

For agents

Every page on this site has a markdown twin beside it at <path>/index.md, and the same twin is returned by the HTML URL when the request carries Accept: text/markdown. Both routes exist because agent stacks split roughly evenly between negotiating and appending. The markdown is about a fifth of the bytes of the HTML, which on a reference page with inlined stylesheets and an inline SVG chart is the difference between reading the page and truncating it.

Four agent skills are published as SKILL.md documents. They are not summaries of this page: each one is written to stop a specific wrong answer, and most of their length is spent on how the data is misread rather than on what it contains. There is an MCP server at /mcp with seven read-only tools over the same data, an A2A endpoint at /a2a — both answer POST, so they are written here rather than linked — and an index of the whole site at llms.txt.

There is no authentication, and none is possible: no API key, no OAuth authorization server, no registration endpoint and no credential to hold. auth.md says so in the form an agent expects, including the parts that are deliberately absent and why. Nothing here can send an alert, subscribe anybody to anything, or read a single thing about a user.

Three questions, worked

The shape of a good answer matters as much as the numbers, because the same data supports a confident, fluent, wrong reply just as easily as a correct one. These are the three questions this data is actually asked, answered the way the datasets support.

"Can I see the aurora from Edinburgh tonight?" Look up Edinburgh: about 55–57° corrected geomagnetic, which puts it in the band where strong activity brings a visible northern arc. The page's own estimate is Kp 4–5 for something worth going outside for; the oval itself only reaches overhead around Kp 6. Edinburgh gets enough darkness from late August to mid-April, so in January darkness is not the constraint and activity is. Then, and only then, fetch the current Kp from NOAA and compare. If the last three-hour value was 2, the answer is no, and saying so plainly is more useful than hedging.

"When should I go to Tromsø?" This is a darkness question wearing a geomagnetic costume. Tromsø sits deep inside the auroral zone, where the oval is overhead on ordinary quiet nights, so activity is rarely the limiting factor — the season is. Read the darkness rows for 70° north: there is no astronomical darkness at all for a stretch of the summer, and the usable window runs from early September to late March, shorter than the window six degrees further south. The counterintuitive part is worth saying out loud: the band closest to the pole has the shortest season, not the longest.

"There's a G3 storm — where will it be visible?" G3 is Kp 7, which puts the modelled oval edge near 52° geomagnetic latitude. That is the overhead figure; the visible range extends further equatorward by the horizon geometry above. NOAA's own published average for G3 is about 200 events per eleven-year solar cycle, so it is notable without being rare. And the answer still has to end with the caveat that decides most nights: none of this sees cloud.

Stability and reuse

The URLs under /api/v1/ are stable; a breaking change gets a /v2/. Fields will be added without warning and are safe to ignore. Cache the payloads — they change when the site is rebuilt, and status.json is a cheap way to decide whether to refetch without pulling everything again.

Attribution is the whole point of the licence. If a figure from here ends up in an article, a chart or an answer, a link back to the page it came from is what makes publishing it worth doing. Questions, corrections and anything that looks wrong: [email protected]. A correction to a number is the most useful mail this site gets.