**Aurora Data API: Kp Thresholds, Darkness and Sources as JSON**

> A free, keyless JSON API over the aurora visibility thresholds, geomagnetic latitudes, darkness model, glossary and source registry published by Lumavik. CC BY 4.0.

Source: https://lumavik.org/api/

[Home](https://lumavik.org/) /API

# 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](https://creativecommons.org/licenses/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 five datasets, their size, and what each one contains.*

| Dataset | Size | What it contains |
| --- | --- | --- |
| [Visibility thresholds](https://lumavik.org/api/v1/visibility.json) | 10 Kp steps, 5 bands | The equatorward edge of the auroral oval at each Kp, the NOAA storm scale over it, the viewing bands, the forecast products by lead time, and emission colour by altitude. |
| [Locations](https://lumavik.org/api/v1/cities.json) | 14 places | Geographic and corrected geomagnetic latitude, both Kp thresholds, and hours of astronomical darkness at each solstice. |
| [Darkness and season](https://lumavik.org/api/v1/darkness.json) | 8 latitude bands × 12 months | Hours of astronomical darkness, the usable season it produces, and the camera exposure model. |
| [Glossary](https://lumavik.org/api/v1/glossary.json) | one sentence per term | Every aurora and space-weather term the site defines, written to survive being extracted on its own. |
| [Sources and live feeds](https://lumavik.org/api/v1/sources.json) | 41 sources, 4 feeds | The primary documents behind every figure, and the keyless NOAA endpoints carrying current conditions. |

The entry point is [index.json](https://lumavik.org/api/v1/index.json), which names every other URL in
one fetch. The machine-readable description is
[openapi.json](https://lumavik.org/api/v1/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.

*The same city, under both definitions. Minneapolis sits 45° on
 a map and 53–55°
 geomagnetically, which is why the map latitude tells you almost nothing.*

| Field | Value | Means |
| --- | --- | --- |
| `kp_visible_from_area` | Kp 4–5 | A display may become visible, typically low toward the north. |
| `kp_oval_overhead` | Kp 7 | The modelled oval itself reaches roughly overhead. |

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 live feeds this site itself reads in the browser. All published by NOAA SWPC, all
 keyless, all CORS-open, so a web app can fetch them directly with no server in between.*

| Feed | Endpoint |
| --- | --- |
| Planetary K-index, 1-minute estimate | `https://services.swpc.noaa.gov/json/planetary_k_index_1m.json` |
| 3-day geomagnetic forecast | `https://services.swpc.noaa.gov/text/3-day-forecast.txt` |
| OVATION aurora 30-minute forecast | `https://services.swpc.noaa.gov/json/ovation_aurora_latest.json` |
| Real-time solar wind (DSCOVR/ACE plasma and magnetic field) | `https://services.swpc.noaa.gov/products/solar-wind/mag-1-day.json` |

The full registry — 41 documents from 18 publishing bodies, each verified to resolve on the date recorded against it — is in
[sources.json](https://lumavik.org/api/v1/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
`/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](https://lumavik.org/.well-known/agent-skills/index.json) 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](https://lumavik.org/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](https://lumavik.org/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](https://lumavik.org/api/v1/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:
[support@lumavik.org](mailto:support@lumavik.org). A correction to a number is the
most useful mail this site gets.

[Get the app](https://lumavik.org/get/) Free · NOAA data · no account

---

HTML version: https://lumavik.org/api/
Structured data for this site: https://lumavik.org/api/v1/openapi.json · https://lumavik.org/llms.txt
Free to quote and reuse with a link back to the source URL above (CC BY 4.0).