Day and night world map widget

Every option

Options travel in the query string of the frame address. Each one is read on its own and clamped to something sensible, so a typo changes one setting instead of breaking the widget. The schema is versioned with v: if a link carries a version this build does not recognise, the widget ignores the whole option set and draws the defaults rather than applying half of an unknown configuration.

view

globe (default) draws an orthographic sphere. flat draws an equirectangular world map, kept at its true 2:1 shape and letterboxed inside your frame instead of stretched, because a stretched map misstates every distance on it.

theme

auto (default) follows each reader's own light or dark setting. dark and light pin it.

places

A comma separated list of up to 4 identifiers, drawn from 158 cities and 197countries and territories. Each one gets a marker on the map and a live clock. An identifier that is not in the dataset is dropped in silence: the widget will never invent a place or guess which city you meant. A country pin carries the time zone that governs that country's own reference coordinate, and the picker says which zone that is when a country uses more than one. On a small frame, one or two pins read best: four clock chips crowd a 300 pixel square.

controls

1 (default) shows the small view and motion buttons in the corner of the frame. 0 hides them and leaves a clean map.

spin

1 (default) lets the globe drift slowly. 0 holds it still. Either way, a reader whose system asks for reduced motion gets a still map that repaints once a minute and nothing more.

w and h

The frame size the snippet asks for, from 240 to 1600 wide and 180 to 1200 tall, in CSS pixels. Values outside that range are clamped. The widget itself always fills whatever box you give it, so it stays correct inside a responsive layout.

What it computes, and what it does not

The daylight and night sides are physics, not decoration. For every pixel the widget recovers the point on Earth's surface, takes the dot product of that point with the direction of the sun, and gets the sine of the sun's altitude there. The shadow then ramps through civil, nautical and astronomical twilight, with a warm band along the terminator where the sky really does glow. The sun marker sits at the subsolar point: the single place where the sun is directly overhead at that instant. Solar positions come from the standard NOAA and Meeus equations, accurate to about a minute for sunrise and sunset outside the polar regions.

Local times come from the reader's own browser, which carries the IANA time zone database, so daylight saving changes are as current as the browser is. Nothing about the reader is sent anywhere: the widget requests one file, the outline map on this site, makes no other network call, sets no cookies, and carries no advertising and no analytics. That last part is enforced in code rather than promised: the site-wide script loader returns nothing on the embed route, so even a fully monetized build of World Time Lab puts no advertising or analytics tag inside your page. It never asks for a location; the map opens on the reader's own meridian using the time zone offset the browser already reports.

What it is not: it is not weather, not cloud cover, and not a photograph. Country outlines are a simplified 110m Natural Earth map, fine at widget size and far too coarse for measuring anything. Time zone boundaries are not drawn at all in the widget, so a country marker shows one zone rather than every zone that country uses. For those, the full world clock globe has the real boundary polygons.

Accessibility notes

A map is useless to a reader who cannot see it, so the widget says the same thing in words. The canvas is exposed as an image with a name and a description that are written from the same solar computation as the pixels: which regions have the sun up, which are in twilight, which are in night, where the sun is overhead, and the local time and daylight state at every pinned place. Both are refreshed with the minute.

• The description names each region after testing the sun at one reference point inside it, and says so, because a region as large as Africa can be lit at one end and dark at the other.
• The view and motion buttons are real buttons with pressed states, reachable by keyboard, with a visible focus ring.
• Clock chips update quietly rather than announcing themselves every minute, which would make the widget hostile to listen to. Changes you make with the buttons are announced.
• Keep the title attribute on the iframe. Without it, screen reader users meet an unlabelled frame. The configurator fills in a sensible default.
• With JavaScript switched off the frame shows a short written explanation instead of a dead canvas. It states no time and no sun position, because a static page cannot honestly know either.

Attribution and terms

The widget is free to use on any site, personal or commercial. The one condition is that the small World Time Lab link in the corner of the frame stays visible and clickable. It is deliberately restrained, it opens in a new tab, and it carries rel="nofollow noopener" so it passes no ranking signal and cannot touch the page that frames it.

Please embed the frame from this site rather than copying the code into your own build: that way daylight saving changes, time zone corrections and accessibility fixes reach your readers without you doing anything. Frame the widget as it is, do not overlay advertising on it, and do not present it as your own product. No advertising renders inside the frame, and the embed route is excluded from the ad and analytics loader in code so that stays true as the rest of the site changes.

Map outlines come from Natural Earth (public domain). Solar positions are computed from published NOAA and Meeus equations. Time zone rules come from the reader's browser.