---
title: "Sun times and solar data (v2, recommended)"
method: GET
path: "/v2"
---

# Sun times and solar data (v2, recommended)

`GET /v2`

All astronomical data for a location and date (or date range). Times in ISO 8601 with offset, in the local timezone of the coordinates unless `tz` is given. If you fetch the same location every day, request a full year once with `date_start`/`date_end` instead of one request per day.

## Query parameters

- `lat` number, required
- `lng` number, required
- `date` string
- `date_start` string, date
- `date_end` string, date
- `tz` string
- `time_format` 'iso8601' | 'unix'

## Response `200`

Single day (object) or range (object with `days` array). Explicit dates are served with `Cache-Control: immutable` -- same input always returns the same output.

- union
  - V2Day — Per-day fields, shared by single-day responses and the items of a range `days` array (which omit tzid/lat/lng). Moon: moonrise/moonset are the FIRST rise and LAST set within the local calendar day (at high latitudes the moon can cross the horizon more than twice a day) and are null roughly one day a month each; topocentric, upper limb, standard refraction.
    - `date` string, date, required
    - `utc_offset` string, required
    - `sunrise` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `sunset` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `solar_noon` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `day_length` integer, nullable — Seconds between sunrise and sunset. 86400 on midnight_sun days, 0 on polar_night days, null on polar transition days (no complete pair to measure).
    - `sun_status` 'normal' | 'midnight_sun' | 'polar_night', required
    - `civil_twilight_begin` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `civil_twilight_end` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `nautical_twilight_begin` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `nautical_twilight_end` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `astronomical_twilight_begin` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `astronomical_twilight_end` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `dawn` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `dusk` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `first_light` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `last_light` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `golden_hour` object
      - `morning` HourPair
        - `begin` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
          - string
          - integer
        - `end` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
          - string
          - integer
      - `evening` HourPair
        - `begin` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
          - string
          - integer
        - `end` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
          - string
          - integer
    - `blue_hour` object
      - `morning` HourPair
        - `begin` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
          - string
          - integer
        - `end` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
          - string
          - integer
      - `evening` HourPair
        - `begin` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
          - string
          - integer
        - `end` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
          - string
          - integer
    - `solar_position` object
      - `sunrise_azimuth` number, nullable — Degrees from north, clockwise.
      - `sunset_azimuth` number, nullable
      - `solar_noon_azimuth` number, nullable
      - `solar_noon_altitude` number, nullable — Degrees above the horizon.
    - `moonrise` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `moonset` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
      - string
      - integer
    - `moon_phase` 'New Moon' | 'Waxing Crescent' | 'First Quarter' | 'Waxing Gibbous' | 'Full Moon' | 'Waning Gibbous' | 'Last Quarter' | 'Waning Crescent' — Phase at local noon, by sun-moon elongation in 45-degree buckets.
    - `moon_illumination` number — Illuminated fraction at local noon, percent (0-100).
    - `tzid` string, required — Effective IANA timezone.
    - `lat` number, required
    - `lng` number, required
  - V2Range
    - `tzid` string, required
    - `lat` number, required
    - `lng` number, required
    - `days` V2DayCore[], required
      - `date` string, date, required
      - `utc_offset` string, required
      - `sunrise` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `sunset` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `solar_noon` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `day_length` integer, nullable — Seconds between sunrise and sunset. 86400 on midnight_sun days, 0 on polar_night days, null on polar transition days (no complete pair to measure).
      - `sun_status` 'normal' | 'midnight_sun' | 'polar_night', required
      - `civil_twilight_begin` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `civil_twilight_end` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `nautical_twilight_begin` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `nautical_twilight_end` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `astronomical_twilight_begin` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `astronomical_twilight_end` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `dawn` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `dusk` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `first_light` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `last_light` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `golden_hour` object
        - `morning` HourPair
          - `begin` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
            - string
            - integer
          - `end` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
            - string
            - integer
        - `evening` HourPair
          - `begin` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
            - string
            - integer
          - `end` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
            - string
            - integer
      - `blue_hour` object
        - `morning` HourPair
          - `begin` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
            - string
            - integer
          - `end` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
            - string
            - integer
        - `evening` HourPair
          - `begin` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
            - string
            - integer
          - `end` union, required — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
            - string
            - integer
      - `solar_position` object
        - `sunrise_azimuth` number, nullable — Degrees from north, clockwise.
        - `sunset_azimuth` number, nullable
        - `solar_noon_azimuth` number, nullable
        - `solar_noon_altitude` number, nullable — Degrees above the horizon.
      - `moonrise` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `moonset` union — Event time: ISO 8601 with offset in the effective timezone (default) or epoch seconds when time_format=unix. Null when the event does not occur that day -- all events are independently nullable (near the polar circles the sun can rise without setting on the same calendar day).
        - string
        - integer
      - `moon_phase` 'New Moon' | 'Waxing Crescent' | 'First Quarter' | 'Waxing Gibbous' | 'Full Moon' | 'Waning Gibbous' | 'Last Quarter' | 'Waning Crescent' — Phase at local noon, by sun-moon elongation in 45-degree buckets.
      - `moon_illumination` number — Illuminated fraction at local noon, percent (0-100).

## Other responses

- `400` — Invalid input.
- `429` — Rate limited. Wait `Retry-After` seconds, then retry with exponential backoff.

---

[API](https://skmtc.dev/sunrise-sunset/apis/sunrise-sunset-org-api.md) · [All operations](https://skmtc.dev/sunrise-sunset/apis/sunrise-sunset-org-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sunrise-sunset/sunrise-sunset-org-api/revisions/328b73a5fbe8/schema)