# Skyfrom > Real, physically based sky gradients for any place on Earth at any moment. skyfrom.app/lisbon is the sky from Lisbon, right now. Use it for a background, a palette or design tokens that match a real sky: fetch JSON or CSS from the API, link to a page, or drop a live `` element into any website. Everything is computed from the sun's position and a single-scattering atmosphere model (Rayleigh and Mie scattering, ozone, a filmic tone map), then reduced to 4 to 8 OKLCH colour stops. Stop position 0 is the horizon (bottom), 1 is the zenith (top). Gradients interpolate in OKLab; hex values are sRGB, OKLCH values may be wide gamut (Display P3). ## Describing a sky Every way in takes the same caption: - Place: `city` (a slug such as `lisbon`, `new-york`, `sao-paulo`; 448 cities, listed at https://skyfrom.app/api/cities), or `lat` and `lon` for any point. - Time: omit for now (live); `18:30` for that clock time today, local to the place; or `2026-11-13T18:30` for an exact local date and time. - Haze: 2 (crisp) to 10 (milky). Default 3. ## API (JSON, CSS, SVG, tokens) No key, CORS open, GET only. - `https://skyfrom.app/api/sky?city=lisbon`: the sky now, as JSON. - `https://skyfrom.app/api/sky?city=tokyo&t=18:30&h=4`: 18:30 today in Tokyo, haze 4. - `https://skyfrom.app/api/sky?lat=45.42&lon=-75.69&t=2026-12-21T16:00`: any point, exact date. - `&format=css`: two `background:` declarations (sRGB fallback, then OKLCH), ready to paste. - `&format=svg&width=1290&height=2796`: a standalone SVG gradient. - `&format=png&width=1290&height=2796`: a PNG (sRGB, dithered, no text), for wallpapers. - `&format=tailwind`: Tailwind CSS v4 `@theme` colours plus a `bg-skyfrom` utility. - `&format=tokens`: CSS custom properties on `:root`. - `&format=figma`: Design Tokens (DTCG) JSON for Figma variables or Tokens Studio. - `&angle=90`: rotate the gradient (degrees; 0 puts the horizon at the bottom). - `https://skyfrom.app/api/cities`: every city: slug, name, ISO country, lat, lon, IANA time zone. The JSON response: ```json { "place": { "name": "Lisbon", "city": "lisbon", "lat": 38.7223, "lon": -9.1393, "timeZone": "Europe/Lisbon" }, "time": { "utc": "2026-06-21T20:00:00.000Z", "local": "2026-06-21T21:00", "live": false }, "sun": { "elevation": -0.03, "azimuth": 300.68, "phase": "golden-hour", "rising": false }, "haze": 3, "stops": [ { "position": 0, "oklch": "oklch(74.7% 0.163 42.5)", "hex": "#ff8754" }, { "position": 1, "oklch": "oklch(44.5% 0.081 272.9)", "hex": "#455081" } ], "css": { "oklch": "linear-gradient(to top, …)", "srgb": "linear-gradient(to top, #ff8754 0%, …)" }, "url": "https://skyfrom.app/lisbon?t=2026-06-21T21:00", "embed": "\n" } ``` `phase` is one of `night`, `astronomical-twilight`, `nautical-twilight`, `blue-hour`, `golden-hour`, `day`. Errors return JSON with an `error` message and usage. ## Live embed: `` One script tag, no build step, about 7 KB gzipped. It paints the sky as a CSS gradient behind the element's content and, unless a time is set, follows the clock (recomputed every minute, cross-faded). It never asks for the visitor's location and inherits the host page's font. ```html

Content sits on top of the sky

``` Attributes: `city`, `lat`, `lon`, `time`, `haze`, `angle`, `live`, `blend` (fade into a colour, such as the page background, towards the horizon), `credit="off"` (hide the small "sky from Lisbon" link). Give the element a size; it fills its box. Respects `prefers-reduced-motion`. `/v1/` never gets breaking changes. ## Links Pages read like captions and open the full interactive site: - https://skyfrom.app/lisbon: now - https://skyfrom.app/lisbon?t=18:42: 18:42 today there - https://skyfrom.app/lisbon?t=2026-11-13T18:42&h=4.5: exact date and haze - https://skyfrom.app/?lat=38.72&lon=-9.14&t=18:42: any point ## In code `@skyfrom/core` is the same model as a pure TypeScript library (no dependencies; browsers, workers, Node): `sky({ lat, lon, date, turbidity })` returns the stops, sun and phase; `toCss`, `toSvg`, `toTokens`, `tokensToTailwind` and `tokensToFigma` format them; `@skyfrom/core/cities` has the city list. It is not on npm yet: until it is, use the API above, which returns the same results.