Methodology and sources

The principle: no figure is ever invented

Every number on the site comes from a cited public source or from an in-house calculation over those sources, documented here. When a source does not cover a municipality, that field stays empty and the interface shows a dash rather than filling it with an interpolation dressed up as a measurement. It is the rule that has deleted the most content from this site, and the only one that is not up for negotiation.

Eclipse circumstances: the IGN table

Contact times, the instant of maximum, magnitude and solar azimuth for each municipality are taken from the table Spain's National Geographic Institute publishes at eclipses.ign.es. The pipeline parses the whole thing, all 8,131 Spanish municipalities, and preserves the time zone exactly as the IGN publishes it: mainland time for the peninsula and the Balearics, and local Canary time, one hour behind, for the two Canary provinces.

The duration of totality or annularity shown on the site is always the IGN figure, never that of the in-house ephemeris engine. The reason has been measured: the in-house engine, astronomy-engine, agrees with the IGN to within roughly 5 to 9 seconds on contact instants, but durations differ by 4 to 8 seconds because of differences in the lunar ephemeris. For times and solar geometry the in-house engine is good enough; for durations the official table wins, and that is what gets published.

Before every deploy the dataset goes through two automated tests. A fixed golden of twenty municipalities, chosen in advance and never rotated, checks that the five contacts run in strictly increasing order, that the published duration is exactly the difference between the start and end of totality, and that magnitude and solar altitude fall inside physical ranges. An integrity test walks all 8,131 municipalities and verifies unique, well-formed INE codes, coordinates inside the bounding box of Spain including the Canaries, and consistency between the totality flag and the duration. It is worth being exact about what this proves: it is internal consistency of the published table, not an independent recomputation of the ephemerides.

Solar altitude is not read from the IGN

The IGN publishes solar altitude rounded to whole degrees. With the Sun two or three degrees above the horizon, as it was across much of the 2026 path, an error of up to half a degree equals a full solar radius: enough to flip the verdict between seeing the corona and seeing it behind a ridge. That is why the observation index does not use that field.

Instead, for every municipality the refracted topocentric altitude of the Sun is computed with astronomy-engine, at the exact instant of its local maximum and in its correct time zone. Azimuth is still taken from the IGN, because the plus or minus two degree sweep performed by the horizon calculation already absorbs its rounding with room to spare.

The change was not cosmetic, and it was measured: across the 3,963 municipalities evaluated, 3,564 changed score, with a mean absolute difference of 0.57 points and a maximum of 7.7. Sixteen municipalities flipped their verdict, ten from visible to blocked and six the other way, and the count of towns with the Sun hidden behind terrain went from 85 to 89.

The horizon: ray-marching over the terrain

Knowing whether the Sun will be blocked takes more than the altitude of the municipality: it takes the terrain profile in the exact direction the Sun will be. The calculation casts rays over the project's elevation maps, derived from Terrain Tiles, from 400 metres out to 80 kilometres and sweeping plus or minus two degrees around the solar azimuth, and keeps the highest horizon angle it finds.

The ray accounts for the curvature of the Earth and for atmospheric refraction through the effective Earth radius with a coefficient k of 0.13, which is what makes a mountain 80 kilometres away appear slightly higher than flat geometry would suggest. The verdict is simple: the Sun counts as visible if the margin between its altitude and the horizon exceeds 0.25 degrees, one solar radius. Below that, the disc is already being bitten by the terrain.

The known limit of this calculation is the resolution of the elevation map: it sees mountain ranges, valleys and cliffs, not a building, a tree or the embankment beside the road you plan to watch from. That is what the sky viewer is for, tracing the real horizon profile from the exact point you pick.

Climate here is thirty years of statistics, not a forecast

This needs saying bluntly, because it is the most expensive misunderstanding anyone planning a trip can make: there is no weather forecast on this site. What is published is climatology, that is, how often the sky has been clear on that date over the last three decades.

The series comes from the ERA5 reanalysis retrieved through Open-Meteo: thirty full years, 1996 to 2025, over a window of days around the eclipse date, with cloud cover, maximum and minimum temperature, precipitation and sunshine hours. ERA5 has a resolution of 0.25 degrees, so the municipalities in the path are first grouped into cells of that size, roughly twenty-five kilometres across.

A twenty-five kilometre cell lumps the coast together with the mountains behind it, and it shows. To sharpen that, a machine learning model learns how those thirty-year statistics vary with latitude, longitude, altitude and distance to the sea, and brings them down to municipal resolution. The model is validated with five-fold cross-validation against the naive method of assigning the nearest cell, and a variable is only published if it improves: for clear sky the mean absolute error drops from 4.7 to 3.4 percentage points, and for maximum temperature from 1.3 to 0.6 degrees.

That residual error is real and belongs with the number: a municipality showing 30 per cent historically clear days may be three points either side of that. And even if the percentage were exact, it would still be a long-run probability. In the week of the event, the only source worth using is an actual forecast.

The observation index, and why its weights change between eclipses

The index is an in-house calculation that ranks the municipalities in the path by combining three things: how long the central phase lasts, how much clearance the Sun has above the real horizon, and how often the sky has been clear. For the 2026 eclipse the published formula was 40 per cent duration, normalised against the 110-second Spanish maximum, 30 per cent horizon margin saturating at two degrees, and 30 per cent historical probability of clear sky.

Those weights are not universal, and this is the part that almost never gets explained. In 2026 the Sun sat between 2 and 12 degrees above the horizon across the 3,963 municipalities in the path: at that height any significant relief in the right direction eats the solar disc, so the horizon component genuinely separated one place from another and deserved a heavy weight. At the total eclipse of 2 August 2027 the Sun will be between 37 and 41 degrees across the 105 municipalities in the path. At 37 degrees no mountain blocks anything short of pathological cases, so the horizon component saturates: it stops discriminating and, kept at the same weight, would only add a constant to a score that no longer ranks anything.

The logical consequence is that in 2027 the weight shifts to what actually varies. And before shifting it, the matter was measured rather than assumed: the same ray-march used in 2026, run over the 105 municipalities of the 2027 path, returns a terrain horizon that peaks at 10.7 degrees, in Jimera de Líbar, against a Sun that will sit between 37.3 and 41.2 degrees. The tightest margin anywhere along the path is plus 27.8 degrees. The horizon component, which saturates at two degrees, equals exactly 1.000 in all 105 municipalities: zero variance. So it stops being a weighted term and becomes a hard veto, with the same one-solar-radius threshold. The margin is still published town by town, but it no longer moves the score, because a constant term lifts everyone equally and ranks nobody.

The 2027 weights, now computed over the closed dataset, are 53 per cent duration, 29 per cent sky and 18 per cent shadow view. They come from a four-component design, 45, 25, 15 and a 15 per cent access term, and the access term is not published because that data does not exist: there is no dataset of roads, parking or distance to the town centre for these 105 municipalities, and filling it with a proxy such as population would have meant inventing it. It is dropped and the remaining three are renormalised over 0.85. That is stated in the data file itself, inside the weights block, and not in small print.

Duration is normalised against 240 seconds, four minutes, rather than against the 288 seconds of Ceuta, which is the real maximum of the path. Dividing by the maximum would crush everyone else against the floor of the component, and beyond four minutes the difference stops deciding a trip: with that much time you get the full corona, Baily's beads and the complete swing of light. Eleven municipalities saturate there. The sky term uses the 10:00 to 11:00 local window, the one that brackets maximum, rather than the daily mean: over the Strait the morning low cloud has not yet burned off at 10:45, and the difference is large. Barbate goes from 93.3 to 76.7 per cent of clear years, Ceuta from 70.0 to 56.7, and on the Almería coast the sign flips, with Adra rising from 73.3 to 86.7.

The new component is shadow view, and it is the same ray-march inverted: instead of looking for the terrain angle towards the Sun, it measures how far the horizontal line of sight runs before relief cuts it, in the direction the umbra arrives from. That direction is not assumed either; it comes out of the gradient of the IGN timing field, which gives an arrival bearing between 247.8 and 264.4 degrees depending on where along the path you stand. Where nothing cuts the line, the limit is set by the geometric horizon of the observer's own altitude, and that is what rewards height and an open sea in front. The median across the path is four kilometres: twenty-six municipalities clear thirty, and thirty have terrain above them at the very first step of the calculation. It is normalised logarithmically, because going from one to two kilometres of open view changes a site far more than going from forty to eighty.

That leaves the uncomfortable part, the one that almost never gets published: how much each component actually ranks anything. Multiplying each weight by the standard deviation of its component gives what it moves in score points, and the answer is 14.0 for duration, 6.5 for shadow view and 1.6 for sky. Sky carries a nominal 29 per cent, but the 2027 path is climatologically homogeneous, nearly all of it between 83 and 93 per cent of clear years at that hour, so it barely separates one town from another. The resulting index runs from 28.9 to 93.3 points, with a median of 65.9 and Conil de la Frontera at the top. Ceuta, which has the longest totality at 288 seconds, comes 39th: it pays for the worst morning cloud statistics along the path and for relief that cuts its view to the west.

The annular eclipse of 26 January 2028 will invert the problem again: solar altitude across its 3,259 municipalities in the path runs from minus one degree to 34, with annularity happening near sunset over much of the track. There the horizon takes charge once more, and harder than in 2026.

The dark-sky layer publishes radiance, not a Bortle class

The light pollution layer uses the annual VIIRS VNL v2 composite from the Earth Observation Group at the Payne Institute, Colorado School of Mines, under a CC BY 4.0 licence. The original has a resolution of 15 arcseconds and is aggregated here onto a 0.025-degree grid, with a neighbourhood convolution approximating the urban halo and a logarithmic encoding so it can be served as a lightweight image.

What it deliberately does not do: it does not convert that radiance into sky brightness in magnitudes per square arcsecond, nor into the Bortle scale. That conversion requires the full atmospheric propagation model, which is not a simple public formula, and approximating it would mean inventing constants. What is published is satellite radiance with cartographic breaks of our own, and it is labelled that way in the interface. It is good for comparing one valley with another; it is not a promise about limiting magnitude.

Known limits

Beyond those already mentioned, three are worth keeping in mind. First: the in-house obscuration model returns 1.0 for the odd municipality very close to the edge of the path, such as Madrid in 2026, because it does not model the irregular profile of the lunar limb; in those cases the interface defers to the IGN flag and never shows a 100 per cent that is not warranted.

Second: this is a static site, generated in full at build time, so the now the content talks about is that of the last deploy, not of your visit. The on-screen countdown does refine live in your browser.

Third: municipal climatology is a spatial interpolation of cell statistics, not a weather station in your town. It beats assigning the nearest cell, that much is measured, and it is still not a local measurement.

How an error gets fixed

When a genuine data fault appears, the procedure is always the same: reproduce it, fix it in the pipeline, measure how many municipalities change and by how much, and write it down. The solar altitude audit described above is the best documented example, and it is not the only one in the project's history.

If you spot a discrepancy, the contact page explains what is needed to reproduce it. A wrong figure corrected late is worse than a missing one.