Magnetic declination

WMM2025, NOAA and BGS · checked against NOAA's published test values

Preview

The test data isn't published yet; the work is in issue #1. The case count, the expiry date and everything under Test data are made up to show how the finished page will look.

Planned · 4 cases · valid until 2029-12-31

What it is

A compass doesn’t point to true north. True north is fixed: along a meridian to the North Pole, the north on a map. Magnetic north is where a compass needle points, lined up with the Earth’s magnetic field. Almost everywhere the two differ, and the angle between them is magnetic declination.

True north straight up, magnetic north 15 degrees to its right, the angle between them labelled declination 15° E

East is positive. Declination is east when the needle points east of true north, as it does across most of western North America.
To turn a compass bearing into a true bearing, add the declination. With 15° E, a compass reading of 100° is 115° true.
It changes with place and over time. The field drifts, so the model is replaced every five years. WMM2025 is good from 2025 to the end of 2029.
Near the magnetic poles a compass is unreliable. The field’s horizontal part is too weak to steer a needle. The model flags these areas.

Operations

Operation	Gives
`field`	The magnetic field at a place and timeIn: `latitudeInDegrees`, `longitudeInDegrees`, `heightInKilometers`, `decimalYear` Out: `magneticDeclinationInDegrees`, `inclinationInDegrees`, `northIntensityInNanoteslas`, `eastIntensityInNanoteslas`, `downIntensityInNanoteslas`, `horizontalIntensityInNanoteslas`, `totalIntensityInNanoteslas`, `gridVariationInDegrees`, `blackout`
`decimalYear`	The decimal year for a dateIn: `date` Out: `decimalYear`

Fields

Field	Meaning
`latitudeInDegrees`	−90 to 90, WGS84, north positive
`longitudeInDegrees`	−180 to 180, WGS84, east positive
`heightInKilometers`	Above the WGS84 ellipsoid, −1 to 850
`decimalYear`	2025.0 to 2030.0: the year plus the day of the year over the year's length
`date`	A calendar date, YYYY-MM-DD
`magneticDeclinationInDegrees`	The angle from true north to magnetic north, east positive
`inclinationInDegrees`	The field's dip below the horizontal, down positive
`northIntensityInNanoteslas`	The field's north component, X
`eastIntensityInNanoteslas`	The field's east component, Y
`downIntensityInNanoteslas`	The field's down component, Z
`horizontalIntensityInNanoteslas`	The field's horizontal strength, H
`totalIntensityInNanoteslas`	The field's total strength, F
`gridVariationInDegrees`	Declination measured from grid north; null between 55° S and 55° N
`blackout`	none, caution (H under 6000 nT) or unreliable (H under 2000 nT)

Edge cases

Case	What's right
Near the north magnetic pole	`blackout: unreliable`, with `magneticDeclinationInDegrees` still given
The geographic poles	Longitude is undefined; the answer must still be a number
29 February 2028	Its `decimalYear` counts the leap day
After 2029-12-31	Still computed; the page shows the file has expired

For agents

Implement WMM2025 from its coefficient file, as the spherical harmonic expansion to degree 12 in the NOAA report’s notation. Convert geodetic input to geocentric before the expansion, and back after. Return magneticDeclinationInDegrees east positive, gridVariationInDegrees only above 55° N and below 55° S (null elsewhere), and blackout from horizontalIntensityInNanoteslas. Pass every case in vectors.json within its tolerance; never loosen a tolerance to pass.

Test data

In vectors.json, published 2026-01-01. Earth model: WGS84. How to read it: Test data format.

Field	Tolerance
`magneticDeclinationInDegrees`	± 0.01
`inclinationInDegrees`	± 0.01
`northIntensityInNanoteslas`	± 1
`eastIntensityInNanoteslas`	± 1
`downIntensityInNanoteslas`	± 1
`horizontalIntensityInNanoteslas`	± 1
`totalIntensityInNanoteslas`	± 1
`gridVariationInDegrees`	± 0.01
`decimalYear`	± 0.0001

Every other field is compared exactly.

Case	Input	Expected
`placeholder-1`field · published	`latitudeInDegrees` 11.11 `longitudeInDegrees` 22.22 `heightInKilometers` 0 `decimalYear` 2025.0	`magneticDeclinationInDegrees` 1.23 `inclinationInDegrees` 4.56 `totalIntensityInNanoteslas` 12345.6
`placeholder-2`field · published	`latitudeInDegrees` -33.33 `longitudeInDegrees` 44.44 `heightInKilometers` 100 `decimalYear` 2027.5	`magneticDeclinationInDegrees` -7.89 `inclinationInDegrees` -10.11 `gridVariationInDegrees` null
`placeholder-3`field · edge, polar	`latitudeInDegrees` 86.5 `longitudeInDegrees` 140 `heightInKilometers` 0 `decimalYear` 2026.0	`magneticDeclinationInDegrees` 12.34 `blackout` "unreliable"
`placeholder-4`decimalYear · edge, hand	`date` "2028-02-29"	`decimalYear` 2028.1234

Implementations

Repo	Status
gshaw/algorithms-swiftSwift	Incomplete

Each is a public repo that runs this page's test data with mise run test. See how implementations work.

Source

Standard	The US/UK World Magnetic Model for 2025–2030NOAA NCEI and the British Geological Survey · Public domain
Test values	WMM2025 test valuesNOAA NCEI · Public domain