Sunrise-Sunset API: Intelligence Source Guide

A free, keyless API returning sunrise, sunset, solar noon and the three twilight boundaries for any coordinate and date. Small, unglamorous and load-bearing: it is how you establish whether it was light, and therefore whether a photograph, a sighting or an alibi is possible.

At a glance

Source	Sunrise-Sunset API
Category	Aviation & Space › Space Weather & Astronomy
Homepage	https://sunrise-sunset.org/api
Machine interface	`https://api.sunrise-sunset.org/json`
Format	`JSON`
Access	Open — no account required
Disciplines	Meteorological Intelligence
Mission domains	Maritime Security, Aviation Security, Space & Satellite Intel, Energy Security

Free no-key sunrise, sunset, twilight and solar-noon times for any coordinates and date. — as catalogued in the platform’s own source registry.

This is a single-purpose calculation service. You supply a latitude, a longitude and optionally a date, and it returns the times of sunrise, sunset and solar noon, the length of the day, and the beginning and end of civil, nautical and astronomical twilight, with more recent versions of the interface also exposing first light and last light and allowing a timezone to be specified so the results come back in local rather than universal time. There is no account, no key and no authentication of any kind; a request is a plain HTTPS GET with query parameters and the response is JSON with a status field and a results object. It is important to understand what it is not. It holds no data. There is no database of sunrise times behind it, no observation network, no archive. Every response is computed on demand from a standard solar position algorithm using the coordinates and date you supplied, which is why it can answer for any point on Earth and any date, past or future, with equal facility. The output is an astronomical calculation presented over HTTP, and its correctness is the correctness of the algorithm plus the correctness of your inputs. That framing matters because it tells you exactly where the failure modes live: not in coverage or freshness, but in inputs, conventions and the physical assumptions the algorithm makes about the horizon.

Illumination is the quiet precondition under an enormous number of investigative claims, and this is the cheapest way to establish it. A photograph said to show a scene at dusk; a witness who describes seeing a face at a distance; a drone or aircraft operation constrained to daylight hours; a satellite image whose shadows imply a time; a claim that a vessel could not have been observed. Every one of those turns on where the sun was, and the twilight boundaries in particular carry meanings that the bare sunrise and sunset times do not. Civil twilight is roughly the period in which ordinary outdoor activity remains possible without artificial light and in which most photography still works. Nautical twilight is the window in which the horizon remains discernible against the sky, which is why it defines the beginning and end of the usable military and maritime day and why planners speak in terms of its boundaries rather than sunrise. Astronomical twilight is the threshold beyond which the sky is genuinely dark for observation purposes. Having those three boundaries for an arbitrary coordinate and date, in one request, turns a vague qualitative claim about light into a specific, checkable, falsifiable statement. That is the analytical job: converting an assertion about darkness into a time you can put in a report.

Who publishes it, and why that matters

This is a small independent web service with no institutional backing, no published funding model and no support commitment, and it has nonetheless been running reliably for years and is widely used. Its value comes precisely from being trivially simple – a deterministic calculation exposed without friction – and that simplicity is also what makes the dependency tolerable, because the entire capability can be replicated locally with a well-tested astronomy library in an afternoon. The realistic assessment is that this is a convenience wrapper you should be glad exists and should never depend on. If it stops, nothing is lost that cannot be rebuilt; if it changes its output conventions, an integration that assumed a format will break quietly. For casual and exploratory work, use it freely and gratefully. For anything that will end up in a case file, a court bundle or a published investigation, compute the same values with a documented local library, compare the two, and cite the local computation – not because this service is wrong, but because a finding should rest on something you can reproduce and version.

Provenance is the first question to ask of any dataset and the one most often skipped. Who collects it, what their incentive is, whether they publish a methodology, and whether they correct the record when they get something wrong all bear directly on how much weight a finding drawn from it can carry.

What a record actually contains

The fields you will be working with, what each one means, and whether it is something you can pivot on. Read the meanings carefully — more analysis is wrecked by misreading a field than by failing to find one, and a field that looks like an observation is often an inference.

Field	Type	What it means	Pivot value
`status`	enum	Request status, typically indicating success or an invalid request. It is the first thing to check, because an error response is still an HTTP 200 with JSON in it and a client that ignores this field will treat a rejection as data.	None; a validation gate rather than an analytical field.
`sunrise`	timestamp	The moment the sun's upper limb appears at the horizon, computed for a standard atmospheric refraction and a flat, unobstructed sea-level horizon. Not the moment the location becomes light, and not the moment the sun clears surrounding terrain.	Timeline anchoring, illumination window construction, plausibility testing of timestamped imagery.
`sunset`	timestamp	The corresponding evening event. The same refraction and flat-horizon assumptions apply, which means the reported time is systematically later than the sun's actual disappearance behind any real western skyline.	Timeline anchoring, shadow direction analysis, evening operational window definition.
`solar_noon`	timestamp	When the sun crosses the local meridian and is at its highest. This is the symmetry point of the solar day and the reference for shadow-based analysis, because shadows point true north or south at this instant.	Shadow azimuth analysis, longitude estimation from observed shadow timing, chronolocation of imagery.
`day_length`	int	Duration between sunrise and sunset, in seconds or as a formatted string depending on the format parameter. Useful as a sanity check on latitude and season, and as a quick discriminator between plausible and impossible date claims.	Latitude and season plausibility testing, cross-checking a claimed location against a claimed date.
`civil_twilight_begin`	timestamp	When the sun reaches six degrees below the horizon in the morning. Practically, when outdoor activity and most photography become possible without artificial light, and the threshold most often relevant to witness and imagery questions.	Photographic plausibility, witness visibility assessment, definition of the working daylight period.
`civil_twilight_end`	timestamp	The evening counterpart. Many national rules on lighting, driving and aviation reference this boundary rather than sunset, so it is frequently the legally relevant time rather than sunset itself.	Regulatory compliance questions, lighting requirements, end of usable natural light.
`nautical_twilight_begin`	timestamp	Sun twelve degrees below the horizon. The horizon becomes discernible against the sky, which is why this boundary defines the start of the usable day in military and maritime planning conventions.	Operational planning windows, maritime observation feasibility, celestial navigation opportunity.
`nautical_twilight_end`	timestamp	The evening boundary at twelve degrees. Together with its morning counterpart it brackets the period in which sea and sky are separable by eye, and it is the standard reference for the end of the effective operational day.	Operational planning windows, night vision transition planning, maritime watch scheduling.
`astronomical_twilight_begin`	timestamp	Sun eighteen degrees below the horizon. Below this the sky is functionally dark. At high latitudes in summer this boundary does not occur at all, which is a real condition the response has to represent somehow.	Genuine darkness determination, optical satellite observation planning, astronomical observation windows.
`astronomical_twilight_end`	timestamp	The evening eighteen-degree boundary. The most sensitive of the six twilight fields to the polar edge cases, and the first to become undefined as latitude and season combine.	Darkness windows, low-light imaging feasibility, correlation with satellite illumination state.
`timezone / utc_offset`	string	Where supported, the timezone in which results are expressed and its offset. Absent an explicit timezone request, results are in UTC, and assuming otherwise silently shifts every conclusion by the local offset.	Local time reconciliation; the single field most responsible for correct or incorrect downstream analysis.
`date`	timestamp	The date the calculation applies to, which is the local solar date at the supplied coordinates. Near the date boundary in a distant timezone the requested date and the local date can differ, which produces off-by-one-day errors that are hard to spot.	Verification that the returned day matches the day you meant; essential for automated batch queries.

Coverage — and what is not in it

Coverage is total and uniform in a way that no other source in this catalogue can claim, because there is nothing to collect. Any latitude, any longitude, any date in the past or the future returns a computed answer. There is no update cadence, no staleness, no geographic bias and no observation gap. What varies is not coverage but validity. The algorithm's assumptions hold well for ordinary locations at ordinary latitudes and degrade at the extremes: within the polar circles there are periods when the sun does not rise or does not set, and the twilight boundaries progressively cease to exist as latitude and season combine, so the service must represent a condition for which no time exists. Historical dates are computed with the same algorithm as future ones, which is correct for solar geometry but means that any long-past date carries the small accumulated uncertainty in the Earth's rotation that ephemeris work normally accounts for – irrelevant for investigative timescales, relevant for anything historical in a serious sense. The other dimension of coverage worth naming is what is absent entirely: there is no moon here. No moonrise, no moonset, no lunar phase, no illumination percentage. For any question about visibility at night rather than during twilight, this source answers only half of it.

Known blind spots

Absence of evidence here is not evidence of absence. These are the conditions under which Sunrise-Sunset API will not show you something that is nevertheless real:

There is no lunar data at all. Night-time visibility is dominated by moon phase, altitude and cloud, and an analysis that establishes darkness from this source and then reasons about what could be seen has ignored the principal light source.
The horizon is assumed flat, unobstructed and at sea level. In a valley, a city street, a forest or behind a ridge, effective sunrise is later and effective sunset earlier – sometimes by a very large margin – and none of that is modelled.
Observer elevation is not an input. From a mountain top or an aircraft the sun is visible before and after the times returned, and at altitude the discrepancy is minutes rather than seconds.
Weather is not modelled. Heavy overcast can make civil twilight functionally dark and thick fog can defeat visibility entirely at midday, so the computed illumination is an upper bound on what could actually be seen.
Polar day and polar night are edge cases where the requested events do not occur, and the way the response represents that is the least robust part of the interface – values in these conditions should be verified against an independent ephemeris rather than parsed optimistically.
Atmospheric refraction is assumed to be standard. Unusual temperature profiles, especially over water and in polar regions, change apparent sunrise and sunset by minutes and occasionally produce the sun appearing when geometry says it should not.
The service returns UTC by default, and the largest single error in practice is a downstream consumer rendering or comparing those times as local, which shifts every conclusion by the offset and can invert a day-night determination entirely.
It answers about the sun's geometric position, not about artificial lighting. In any urban environment the question of whether a scene was visible is dominated by street lighting, and this source is silent on it.
There is no service commitment, no versioning guarantee and no notification of changes to the output convention, so an integration can begin returning subtly different values without any signal.

Write the blind spot into the product. A statement that something “was not observed in Sunrise-Sunset API” is defensible; a statement that it “did not happen” is not, and the difference is what survives cross-examination.

Access, licensing and what you may do with it

Access model: Open — no account required

Send an HTTPS GET with latitude and longitude as query parameters, optionally a date and a formatting flag, and read the JSON response. There is no key to obtain and no account to create, which means there is also no support channel and no way to be told about changes. Two practical points determine whether your integration is correct. First, request unformatted output so times come back as unambiguous ISO 8601 strings with an explicit offset rather than as human-readable strings that a parser will guess at; guessed timezone handling is the dominant source of error in this domain. Second, check the status field before touching the results, because invalid coordinates and malformed dates come back as a successful HTTP response containing an error, and a client that assumes a 200 means data will happily store nothing. If you are batching many coordinates or many dates, do not – compute locally with an astronomy library instead. This is a courtesy service and the calculation is cheap to run yourself.

Licence

The service publishes its own terms and those are the authoritative statement; read them before building anything commercial on it. The underlying substance, however, is not licensable in any meaningful sense: the position of the sun is a fact of physics and the algorithms that compute it are published in the open scientific literature and implemented in many free libraries. That is a genuinely unusual property in this catalogue and it has a practical consequence worth stating plainly – if the terms of this service are ever inconvenient for your use case, the answer is not to negotiate but to compute the values yourself, with no loss of accuracy and a gain in reproducibility. Attribution is courteous where the service is used directly. For any published or evidential work, cite the algorithm and library you used rather than a web service, because that is what a reviewer can independently re-run.

Rate limits and fair use

No formal quota is published and none should be assumed. The operative constraint is etiquette applied to a small free service: keep request rates low, cache results, and recognise that for a fixed coordinate the answer for a given date never changes, so there is no reason ever to request the same coordinate and date twice. If your workload involves more than occasional lookups – a grid of coordinates, a year of dates, a batch of case locations – the correct engineering decision is to move the calculation in-house rather than to distribute it across polite delays. A local implementation runs in microseconds, works offline, is reproducible, and imposes nothing on anyone. Reserve the hosted service for interactive use, for cross-checking a local implementation, and for the cases where installing a dependency is disproportionate to the question.

Licensing changes, and it changes without warning. A dataset that was free for research this year may not be free for commercial or evidential use next year. Confirm the current terms before you build a dependency on it, and record the terms you relied on alongside the data — the licence in force at the time of collection is part of the provenance.

Collecting it

How Sunrise-Sunset API is actually pulled, in the order you would set it up. Prefer the bulk or export interface over per-item lookups wherever one exists: it is kinder to the publisher, faster for you, and gives a reproducible snapshot rather than a series of point-in-time answers you cannot reconstruct later.

Method	Format	Cadence	Notes
Single point-and-date query	JSON	on demand	The normal use. Supply coordinates and a date, request unformatted output, and store the full response including the parameters you sent.
Case location precomputation	JSON	once per case location	For an investigation anchored to a place, compute the full year of solar events once and store it. It never changes, so it should never be requested twice.
Local library computation	bulk	as needed	The preferred method for anything at volume or with evidential weight. A maintained astronomy library gives the same answer with a version number you can cite and no network dependency.
Cross-validation pull	JSON	periodic	Query the service for a sample of coordinates and compare against your local implementation. Disagreement indicates a convention difference – refraction, limb definition, timezone – that you need to understand before either is trusted.
Independent ephemeris check	JSON	for edge cases	For polar latitudes, high-altitude observers and any result that will be challenged, verify against a national observatory calculator or a full ephemeris rather than relying on a single simplified algorithm.

Ingesting it into the platform

Every step below is idempotent and cursor-based: interrupt one and it resumes from where it stopped rather than duplicating rows or losing progress. Collection is recorded per source, so a feed that quietly stops publishing shows up as a stale timestamp instead of silently thinning your coverage.

Register it as a calculator, not a dataset — Record in sources.php that this source computes rather than observes, so that a later analyst reading a stored sunrise time understands it is a model output for an idealised horizon rather than a recorded event.
Store the request with the response — During ingest.php, persist the coordinates, date, timezone parameter and retrieval time alongside the result. A stored sunset time whose originating coordinates were not recorded is uninterpretable and cannot be re-derived.
Normalise every time to UTC once, at the edge — Convert on ingest, store UTC, and render local only at presentation. Mixed time bases inside a case are the single most common cause of wrong day-night conclusions, and the fix has to be structural rather than a matter of care.
Flag the polar and edge conditions — Detect responses where twilight boundaries are absent or implausible and mark them for manual verification rather than storing them as ordinary values. These are exactly the cases where a silent parse failure becomes a confident wrong answer.
Attach solar events to the case timeline — Push the boundaries into timeline.php as background bands against which other timestamped events render, so that any observation in the case can be read against the illumination condition without a separate lookup.
Correlate with location-bearing records — Use correlate.php to test timestamped, geolocated records – imagery, sightings, device positions, vessel reports – against the illumination window, and record any contradiction as a finding rather than as a data quality note.
Recompute locally for anything evidential — Run a parallel computation with a versioned astronomy library through pipeline.php and store both. Where they agree, cite the local one; where they disagree, investigate the convention difference before either is used.
Add the missing lunar layer — Solar events alone do not answer night-time visibility. Compute moon phase, rise, set and altitude from an ephemeris library and store them alongside, so that darkness and visibility are not confused with each other in the case record.

Registered sources and their last-collected state are listed in sources.php, and the scheduled chain that keeps them current is in automation.php.

How it is wrong, and how to tell

Every dataset is wrong in characteristic ways. Knowing which ways is the difference between using a source and being used by one, and it is the part of source evaluation most often skipped because it is the part that takes work.

For the ordinary case the accuracy is entirely adequate and the limiting factor is never the algorithm. Standard solar position calculations of the kind this service uses agree with full ephemeris computations to within a small number of seconds for sunrise and sunset at typical latitudes, which is far finer than any investigative question requires. The real quality question is whether the answer means what you think it means, and there the honest assessment is that the systematic differences dwarf the algorithmic ones. A flat-horizon sunrise time can be twenty minutes or more away from the moment the sun actually clears a ridge to the east. A standard refraction assumption can be several minutes off over cold water. An observer three thousand metres up sees the sun materially earlier than the computed time. None of these are errors in the calculation; they are the calculation answering a slightly different question from the one you asked. Judge quality accordingly: trust the numbers, interrogate the mapping between the idealised model and the real place. Where the answer will be challenged, cross-check against a national observatory's calculator and a local library implementation, and if all three agree you have as solid a foundation as this class of question admits.

Characteristic false positives

Timezone handling is the dominant failure. Results are UTC unless a timezone is requested, and a consumer that renders or compares them as local time shifts every conclusion by the offset, which is often enough to invert a day-night determination entirely.
The flat-horizon assumption silently overstates daylight. In terrain, cities or forest the sun disappears well before the computed sunset, so a scene reported as being in daylight may have been in deep shadow.
Twilight is treated as darkness or as daylight depending on which suits the hypothesis. The three twilight bands have distinct, defined meanings, and collapsing them into a binary is an analytical choice that should be stated rather than made silently.
Polar edge cases parse into ordinary-looking values. Where the sun does not rise or set, or a twilight boundary does not occur, a naive client can store a placeholder time that looks entirely normal and is meaningless.
Date boundary confusion produces off-by-one-day results, because the date you request and the local solar date at the coordinates can differ when the location is far from your own timezone.
Coordinate transposition – latitude and longitude reversed, or a sign error – produces a perfectly well-formed answer for a completely different place, and there is nothing in the response to indicate it.
Solar illumination is confused with visibility. Cloud, fog, terrain shadow, artificial lighting and the moon all determine what could actually be seen, and none of them appear here, so a claim about visibility built only on this source is incomplete by construction.
The error response is an HTTP success. An invalid request returns status information inside a 200 response, so a client that checks only the status code will treat a rejection as data and store nothing while believing it stored something.

None of these make the source unusable. They make it a source that requires corroboration before an assertion built on it goes into a product, which is true of every source and admitted by few.

Ageing

In one sense nothing here ages, because the physics does not change and a computed sunrise for a past date will be the same next year as it is today. In another sense the ageing is subtle and worth naming. Your stored results age against changes in the service's conventions – a change in the refraction assumption, the limb definition, the handling of polar cases or the default timezone would alter future answers without altering the ones you already stored, producing a quiet inconsistency inside your own data. Political timezone changes age anything you stored in local time, because a jurisdiction that alters its offset or abandons seasonal clock changes retroactively affects the local rendering of a UTC instant, which is one more reason to store UTC and render late. And your case conclusions age against everything the source does not model: a determination that a location was in daylight remains true about the sun and may become false about the scene if you later learn about terrain, weather or an obstruction. A stale record here looks like a stored local time with no coordinates, no offset and no note of which service or library produced it, and it cannot be rescued after the fact.

What this source feeds

A source is only worth what it lets you conclude. These are the disciplines that collect through it, the mission domains it serves and the data points it yields — every one is a tag, so you can follow any thread from here into the rest of the library.

Collected by these intelligence disciplines

Meteorological Intelligence

Serves these mission domains

Yields these data points

How each sector uses Sunrise-Sunset API

The same dataset is worked very differently depending on who you are, what authority you hold, and what you are ultimately producing. A military analyst is supporting a commander’s decision; a journalist is meeting a publication standard; an NGO caseworker is protecting a person. The records are shared — the constraints, thresholds and outputs are not.

🎖 Military and defence

The relevant products are the nautical twilight boundaries, which define the beginning and end of the effective operational day in most planning conventions and which are used in preference to sunrise and sunset for exactly that reason. Practical applications are the timing of movement and observation windows, the transition points for night vision equipment, the illumination conditions for any imagery collection, and the reciprocal question of what an adversary's observation window looks like at a given location and date. The two limitations that matter operationally are the absence of lunar data, which dominates real night-time illumination, and the flat-horizon assumption, which is badly wrong in the terrain where operations are actually planned. Use it as a first-order planning input and replace it with a proper illumination product for anything where the answer drives a decision.

🕵 National intelligence

This is a small utility with an outsized role in verification. A great deal of imagery and reporting analysis reduces to a consistency check between a claimed time, a claimed place and the observable illumination, and this source supplies the reference against which such claims are tested. It supports chronolocation directly: shadow direction and length in an image constrain the solar azimuth and elevation, and solar noon supplies the symmetry reference that turns those constraints into a time. It also supports the negative finding, which is often the more useful product – a photograph that shows full daylight at a time and place where the sun was below the horizon is decisive evidence about the claim, not about the weather. Keep the analysis in UTC and state the horizon assumption whenever the terrain is not flat.

👮 Law enforcement

In casework the recurring question is whether a witness could have seen what they describe, and illumination is the first component of that. Civil twilight is often the legally or practically relevant boundary rather than sunset, and many national rules on lighting, driving and operation of vehicles or aircraft reference it explicitly. The same values test timestamps on photographs and video, corroborate or contradict accounts of movements, and establish the conditions under which an identification was made. Two cautions for evidential use: compute the values with a documented, versioned tool rather than citing a website, and be explicit that the calculation assumes an unobstructed horizon, because defence counsel will reach the terrain point before you do if you have not.

🔍 Private investigation and corporate security

Surveillance planning and reporting both depend on light. Knowing the civil twilight boundaries at a subject's location tells you when observation becomes practical and when photography stops working, and it lets you write a report that describes the conditions accurately rather than approximately. In insurance and liability work the same values test the plausibility of accounts involving visibility – a claimed sighting, a road incident, a reported condition at a site. The professional discipline is the same as everywhere else in this guide: record the coordinates, store times in UTC, and never let a computed sunset stand in for what the sky over a particular street actually looked like.

📰 Journalism and OSINT media

Verification desks use this constantly, usually without thinking of it as a source. When a video or photograph carries a claimed time and place, the illumination in the frame is one of the few things that can be checked against physics rather than against another account, and a mismatch is publishable. Shadow analysis for geolocation and chronolocation depends on solar position and the solar noon reference. The reporting practice worth adopting is to state the method and the assumption in the piece – that the calculation assumes a flat horizon and that terrain shifts the real times – because that is both honest and pre-empts the obvious objection. For anything contested, corroborate against a national observatory calculator.

🌍 NGO, humanitarian and human rights

Human rights documentation frequently rests on establishing that an event described as occurring in darkness or in daylight is consistent with the time and place claimed, and this is the cheapest available way to do it. It requires no budget, no account and no specialist training. Field operations use it more prosaically, to plan movement within daylight security windows and to schedule activities that must complete before dark. For documentation that will be challenged – and in this field it will be – compute the values with a documented open-source library so that the method is inspectable, record the coordinates and the horizon assumption, and pair the solar values with lunar data before making any statement about what witnesses could have seen at night.

🎓 University and research

Researchers in ecology, epidemiology, energy systems, criminology and human behaviour routinely need daylight and twilight covariates for large panels of locations and dates, and this is not the right way to get them. The correct approach is a local astronomy library, which is faster, reproducible, citable by version and imposes nothing on a free service. Where this API is genuinely useful in research is as a cross-check on an implementation and as a teaching tool that makes twilight definitions concrete. Any published work should cite the algorithm and library rather than a web endpoint, and should state the horizon and refraction assumptions, because those assumptions are the ones that matter when daylight is used as a covariate in a terrain-varied study area.

Playbook: working Sunrise-Sunset API end to end

A repeatable sequence from first pull to finished product. Each phase states what you are trying to establish, not merely what to click — the objective is a defensible chain of reasoning, not a completed checklist.

Phase 1 — State the question in terms of a threshold

Decide before you query which boundary the question actually turns on. Photography and ordinary outdoor visibility usually correspond to civil twilight; horizon discrimination and operational day-night transition to nautical; genuine darkness to astronomical. An analysis that asks vaguely whether it was dark will produce a vague answer that cannot be defended.

Phase 2 — Pin the coordinates to the place, not the region

Get the latitude and longitude of the actual location, at a precision appropriate to the question, and record the source of the coordinates. Sunrise time varies with longitude at roughly four minutes per degree, so a coordinate taken from a city centroid rather than the specific site introduces an error that is small but systematic.

Phase 3 — Query in UTC and convert once

Request unformatted output, store UTC, and defer any local rendering to presentation time. Then determine what the local time actually was on that date at that place, including whether seasonal clock changes were in force, and record the offset explicitly as part of the finding.

Phase 4 — Validate the response before using it

Check the status field, confirm the returned date matches the local solar date you intended, and sanity-check the day length against latitude and season. A transposed coordinate or an off-by-one date produces a completely well-formed answer about somewhere or somewhen else, and these are the errors that survive to publication.

Phase 5 — Correct for the real horizon

Establish what the skyline actually looks like from the observation point using terrain data, imagery or local knowledge, and adjust the effective sunrise and sunset accordingly. In hills, cities or forest this correction routinely exceeds twenty minutes and it moves in the direction that shortens daylight, which is the direction that matters for most claims.

Phase 6 — Correct for observer elevation

If the observer was materially above the surrounding surface – a hilltop, a tall building, an aircraft, a ship's bridge – the sun is visible earlier and later than the computed times. The service takes no altitude parameter, so this correction has to be applied deliberately or acknowledged as an unmodelled uncertainty.

Phase 7 — Add the lunar layer before any night-time claim

Compute moon phase, rise, set and altitude for the same place and date from an ephemeris library. A full moon high in a clear sky provides enough light for a great deal of activity and observation; a new moon provides none. Any statement about what could be seen at night that omits this is incomplete by construction.

Phase 8 — Bring in weather and lighting

Overcast, fog and precipitation reduce effective illumination sharply, and in built environments artificial lighting dominates entirely. Pull the observed weather for the time and place from a meteorological source and note the lighting environment. The solar calculation is an upper bound on natural light, not a description of the scene.

Phase 9 — Run the consistency test against the evidence

Compare the illumination conditions you have established against what the material actually shows: shadow direction and length, sky colour, whether lights are on, whether headlights are lit. Concordance is weak corroboration; a clear contradiction is a strong finding and is usually the most valuable output of this whole exercise.

Phase 10 — Use shadows to constrain time, not just to check it

Where an image shows a shadow of an object of known or estimable height, the shadow's direction constrains solar azimuth and its ratio to the object's height constrains solar elevation. Combined with solar noon at the candidate location this narrows the possible time substantially, and it is the standard method for chronolocating imagery.

Phase 11 — Recompute independently before you rely on it

For anything that will be challenged, compute the same values with a versioned local astronomy library and check against a national observatory's calculator. Three independent agreeing computations is a defensible basis; a single screenshot of a website is not, however correct the website happens to be.

Phase 12 — Write the assumptions into the finding

The finished statement should name the coordinates, the date, the time base, the twilight threshold used, the horizon and elevation assumptions, and the tool and version that produced the numbers. That paragraph is what makes an illumination finding survive review, and it costs four sentences.

The platform ships this as a step-checked workflow in playbooks.php, so progress is recorded against a case rather than held in someone’s head.

What to pair it with

No single source carries a finding. These are the datasets that corroborate, extend or contradict this one — and a source that contradicts is worth more than one that agrees, because it is the only thing that will tell you when you are wrong.

Source	Relationship	What it adds
NOAA Solar Calculator	corroborates	A government-published solar position calculator that gives an independent computation of the same quantities, including solar azimuth and elevation at arbitrary times rather than only at the event boundaries.
US Naval Observatory Astronomical Applications	corroborates	National observatory computations of rise, set and twilight, including lunar data. The authoritative cross-check when a result will be contested.
Skyfield	supersedes	Local ephemeris-quality computation of solar and lunar positions, rise and set times and twilight boundaries, with a version you can cite and no network dependency. The right tool for evidential and research work.
NOAA Space Weather Prediction Center	extends	Auroral activity is a real night-time illumination source at high latitudes and can materially affect what is visible in exactly the places where twilight analysis is most awkward.
N2YO	extends	Satellite illumination state and pass geometry, which combined with ground darkness determines whether an object in the sky could have been seen or photographed from a location.
Copernicus and national elevation datasets	prerequisite	Terrain models are what convert an idealised flat-horizon sunset into the time the sun actually disappeared behind the ridge, which is the correction that matters most in practice.
Bellingcat	extends	Published methodology on shadow-based chronolocation and geolocation, which is the analytical technique this data most often serves.

Legal, ethical and operational constraints

There is nothing sensitive about the position of the sun and no jurisdiction restricts calculating it, so the legal surface here is unusually small. What deserves attention is the use, not the source. Illumination findings are routinely deployed to test alibis, challenge witness accounts and assess the plausibility of claims about individuals, and in most jurisdictions the surrounding activity – collecting the location, the timestamp and the imagery that make the question meaningful – is subject to data protection and privacy rules even though the solar calculation is not. Where the finding will be used evidentially, the operative constraints are evidential rather than statutory: expert evidence about illumination has to rest on a documented, reproducible method, and citing a free web API in a court bundle invites a challenge you will lose on process even if your number is right. Compute locally with a named library and version, state the assumptions, and keep the web service as a cross-check. Where the terms of the service are the only remaining constraint, remember that the calculation is freely reimplementable and that is the correct answer to any licensing friction.

Operational security

The request itself is trivial – unauthenticated, unremarkable, indistinguishable from the traffic of a weather widget. The exposure is entirely in the content of the query, and it is real: a request contains the exact coordinates and date you are interested in, sent in the clear to the service's logs. A sequence of queries for a specific rural coordinate on a specific past date is a precise statement of investigative interest, more precise than most of the queries your organisation makes to any other source in this catalogue. If the location matters, do not query it. The calculation runs offline in microseconds with a library you already have, which removes the disclosure entirely and is faster besides. This is one of the few sources where the operationally correct advice is simply not to use the hosted version for anything sensitive, and where following that advice costs nothing at all.

Two rules that hold regardless of jurisdiction. Collection that is lawful is not automatically proportionate, and a dataset assembled for one purpose does not carry consent for another. Where the records concern identifiable people, the question is not only whether you may hold the data but whether holding it serves the purpose you are accountable for.

Is it earning its place?

Sources accumulate. Feeds get added during an incident and are never reviewed again, and a decade later the pipeline is carrying dead weight that nobody dares remove. These are the measures that show whether Sunrise-Sunset API is contributing anything, and they are worth baselining now so the answer is available later.

Proportion of stored solar events that carry their originating coordinates, date, time base and computing tool, which should be complete and is the difference between a reusable record and a number.
Number of case findings where an illumination check contradicted a claimed timestamp or account, which is the output this source exists to produce.
Rate of agreement between the hosted service and your local library implementation on a periodic sample, tracked so that a convention change is detected as a divergence rather than as a mystery.
Share of night-time visibility assessments in your work that include lunar data, as a direct measure of whether analysts are stopping at half the answer.
Count of findings in which a terrain-corrected horizon materially changed the conclusion from the flat-horizon computation, which tells you how much the unmodelled assumption is costing you.
Frequency of timezone-related corrections found in review, which is the leading indicator of whether your pipeline is storing UTC properly or relying on analyst care.
Number of edge-case responses at polar latitudes flagged for manual verification rather than stored silently, as a check that the validation layer is actually running.

Beware of volume. Indicator counts rise easily and say almost nothing. Unique contribution — findings this source produced that no other source in your stack would have — is the measure that matters, and it is usually far lower than anyone expects.

Tradecraft notes

The distinctions that separate a competent analyst from a fast one:

Name the threshold. Dark is not a fact, it is a definition, and civil, nautical and astronomical twilight mean different things. A finding that says it was dark without saying which boundary was used has not said anything checkable.
The flat horizon is the biggest error in the system and it is not in the data. Real skylines move effective sunrise and sunset by tens of minutes, always in the direction of less daylight, and correcting for terrain is usually more consequential than any refinement of the calculation.
Store UTC, render late. Every serious mistake in illumination analysis is a timezone mistake, and the only reliable defence is architectural rather than a matter of being careful.
The sun is half the answer at night. Moon phase and altitude determine what could actually be seen after dark, and an analysis that establishes astronomical twilight and then reasons about visibility has skipped the dominant light source.
Daylight is an upper bound on illumination, never a description of the scene. Cloud, fog, terrain shadow and building shade all subtract; street lighting adds. The computed value tells you what the sky was doing, not what the place looked like.
Shadows are the strongest use of this data. Direction gives azimuth, length ratio gives elevation, and solar noon gives the symmetry reference. Together they constrain time and place far more tightly than the event times alone.
Check the response, not the status code. An invalid request returns success with an error inside, and a client that trusts the HTTP layer will store nothing while reporting that it stored something.
Polar latitudes break assumptions rather than calculations. When the sun does not set, or a twilight boundary does not exist, the correct behaviour is to flag and verify, not to parse whatever came back.
For anything evidential, cite a library and a version. The website is right and irreproducible; a named implementation with a version number is what survives a challenge to method rather than to substance.

Questions analysts actually ask

What is the difference between the three twilights and which should I use?

Civil twilight ends when the sun is six degrees below the horizon and roughly corresponds to the limit of ordinary outdoor visibility and photography. Nautical twilight is twelve degrees and marks the point where the horizon becomes indistinguishable, which is why it bounds the operational day in military and maritime use. Astronomical twilight is eighteen degrees and marks genuine darkness. Choose by the physical question, and state the choice.

Why do the times not match what I observed?

Almost always terrain or elevation. The calculation assumes a flat, unobstructed horizon at sea level, so a ridge, a building line or a treeline makes the sun disappear earlier and appear later, sometimes by a great deal. Observer altitude works the other way. Neither is a defect in the calculation; both mean the model is answering a slightly different question from yours.

Are the times UTC or local?

UTC unless you explicitly request a timezone, and this is the single most common source of error in using this source. Store UTC, convert only for display, and when you convert be sure you know what the local offset actually was on that date at that place, including whether seasonal clock changes applied.

Does it handle the Arctic and Antarctic?

It returns something, and that something needs checking. Within the polar circles there are periods with no sunrise or no sunset, and at high latitudes in summer the astronomical twilight boundaries do not occur at all. Detect these cases explicitly and verify against a full ephemeris rather than parsing the response as if it were ordinary.

Can I use it for historical dates?

Yes – the calculation is performed on demand for whatever date you supply, so past and future are equally available. For investigative timescales this is entirely reliable. For genuinely historical work spanning centuries, the accumulated uncertainty in the Earth's rotation matters and you want a proper ephemeris rather than a simplified algorithm.

Does it tell me about moonlight?

No, and this is its most consequential omission. Night-time visibility is dominated by the moon, and establishing that the sun was well below the horizon tells you very little about what could be seen. Compute lunar phase, rise, set and altitude from an ephemeris library before making any night-time visibility statement.

Is it accurate enough for court?

The numbers are, and the citation is not. Standard solar algorithms agree with full ephemeris computations to within seconds, which is far beyond what any illumination question needs. But an evidential finding should rest on a documented, versioned, reproducible computation, so compute locally with a named library, state the horizon assumption, and use the web service as corroboration.

How do I use this for shadow analysis?

Solar noon gives you the moment shadows point true north or south, which anchors direction. For a specific time you need solar azimuth and elevation rather than just the event boundaries, so use a calculator or library that returns the sun's position continuously. The shadow's direction constrains azimuth and its length relative to the casting object's height constrains elevation.

Should I use the API or compute locally?

Use the API for one-off interactive checks and as a cross-check. Compute locally for anything batched, anything sensitive, anything evidential and anything that needs to be reproducible. Local computation is faster, offline, versionable and discloses nothing about the coordinates you are interested in.

Standards, formats and interoperability

What this source speaks natively, and what it has to be translated into before a partner can consume it. Work that arrives in a recognised format is easier to defend, easier to hand over and easier to automate against:

Civil, nautical and astronomical twilight are internationally standardised at six, twelve and eighteen degrees of solar depression respectively, which is why the three boundaries are comparable across sources and jurisdictions.
Sunrise and sunset are conventionally defined as the appearance and disappearance of the sun's upper limb with a standard atmospheric refraction correction, not as the geometric centre crossing the horizon.
ISO 8601 with an explicit offset is the correct interchange representation for these times, and requesting unformatted output is what produces it.
Standard solar position algorithms published in the astronomical literature underlie this and every comparable calculator; citing the algorithm is what makes a result reproducible.
The IAU reference frames and time scales define the underlying ephemeris conventions, which matter when comparing simplified algorithms against full ephemeris computations.
Nautical twilight boundaries correspond to the begin and end morning and evening nautical twilight conventions used in military and maritime operational planning.
The platform exports derived illumination conditions and correlations in STIX 2.1, MISP, CSV, JSON and JSONL, so a twilight window can be attached to a case timeline alongside any other timestamped observable.

References

Primary documentation and authoritative references for this source. Publishers revise and retire material, so treat the retrieval date as part of the citation and re-check before relying on any of it in a formal product.

Sunrise-Sunset API documentation — sunrise-sunset.org. The service documentation: parameters, response fields, formatting options and terms. Short enough to read in full, and you should.
Sunrise-Sunset JSON endpoint — sunrise-sunset.org. The endpoint itself. Request unformatted output so times return as unambiguous ISO 8601 strings rather than as human-readable text.
NOAA Solar Calculator — NOAA Global Monitoring Laboratory. Government-published solar position calculator with continuous azimuth and elevation, which is what shadow analysis actually needs.
US Naval Observatory Astronomical Applications Department — United States Naval Observatory. Authoritative rise, set, twilight and lunar computations from a national observatory. The cross-check to cite when a finding will be contested.
Skyfield — Brandon Rhodes. Ephemeris-quality local computation of solar and lunar events with a citable version. The correct tool for evidential and research work.
Astropy — Astropy Project. Widely used scientific astronomy library with coordinate and time handling, useful when illumination is one covariate among many in a larger analysis.
International Astronomical Union — IAU. The standards body behind the reference frames, time scales and conventions that make different implementations comparable.
Bellingcat — Bellingcat. Published open-source investigation methodology, including shadow-based chronolocation, which is the analytical technique this data most directly supports.
Copernicus Programme — European Union. Elevation and terrain data, which is what converts an idealised flat-horizon result into the time the sun actually cleared the skyline.

Link integrity: every reference above was verified with a live request when this page was generated. Where a publisher had moved or withdrawn a document, the link was repointed at a preserved copy in the Internet Archive and marked as archived. Anything with no reachable copy anywhere had its link removed rather than left to rot — the source is still credited, it simply cannot be linked.

Put it into practice

The Quantus Intel threat intelligence platform operationalises this source: it stores every solar event with its coordinates, date, time base and computing tool, renders the twilight boundaries as background bands on the case timeline, and flags any timestamped record that contradicts the illumination condition at its own location.. Browse the full source catalogue, or follow any tag above into the rest of the library.