# US Naval Observatory

> Astronomy data from the US Naval Observatory: sunrise, sunset, twilight and moon times for any place and day, moon phases, equinoxes and solstices, solar eclipses, sidereal time, Julian dates, Easter and other holy days, US daylight saving dates and celestial navigation. No account or API key required.

App · 14 actions. Web page: https://docs.lodol.com/docs/integrations/usno

## Actions

### Convert date to Julian date

Turn a calendar date and time into its Julian date, the day count astronomers use. Works from 4713 BC to AD 9999; dates before 15 October 1582 are read in the Julian calendar.

**Inputs**

- Date (`date_value`, date, required): The calendar date.
- Time (`time_of_day`, time): The time of day in UT1 (within a second of UTC). Defaults to midnight.
- Era (`era`, text): AD or BC. Defaults to AD. One of: `AD` (AD (CE)), `BC` (BC (BCE)).

**Outputs**

- `date` (text): The calendar date, YYYY-MM-DD (Julian calendar before 15 October 1582)
- `day` (number): Day of the month
- `era` (text): AD or BC
- `iso` (text): The moment as ISO 8601, for AD years 1 to 9999
- `julian_date` (number): The Julian date
- `month` (number): Month
- `summary` (text): One line describing the result
- `time` (text): Time of day (UT1)
- `year` (number): Year

**Example output**

```json
{
  "date": "2026-10-19",
  "day": 19,
  "era": "AD",
  "iso": "2026-10-19T14:30:15Z",
  "julian_date": 2461333.10434,
  "month": 10,
  "summary": "2026-10-19 AD 14:30:15.0 UT1 is Julian date 2461333.104340.",
  "time": "14:30:15.0",
  "year": 2026
}
```

### Convert Julian date to date

Turn a Julian date into its calendar date, time (UT1) and day of the week. Dates before 15 October 1582 come back in the Julian calendar.

**Inputs**

- Julian date (`julian_date`, number, required): The Julian date, 0 to 5373484.5, such as 2451545.0. From 0 to 5373484.5.

**Outputs**

- `date` (text): The calendar date, YYYY-MM-DD (Julian calendar before 15 October 1582)
- `day` (number): Day of the month
- `day_of_week` (text): Day of the week
- `era` (text): AD or BC
- `iso` (text): The moment as ISO 8601, for AD years 1 to 9999
- `julian_date` (number): The Julian date
- `month` (number): Month
- `summary` (text): One line describing the result
- `time` (text): Time of day (UT1)
- `year` (number): Year

**Example output**

```json
{
  "date": "2026-10-19",
  "day": 19,
  "day_of_week": "Monday",
  "era": "AD",
  "iso": "2026-10-19T14:30:15Z",
  "julian_date": 2461333.10434,
  "month": 10,
  "summary": "Julian date 2461333.104340 is Monday 2026-10-19 AD, 14:30:15.0 UT1.",
  "time": "14:30:15.0",
  "year": 2026
}
```

### Get a solar eclipse at a place

See how a solar eclipse looks from a place: whether it is visible, how much of the Sun is covered, how long it lasts, and when each stage happens with the Sun's position in the sky.

**Inputs**

- Eclipse date (`date_value`, date, required): The date of the eclipse (UTC), from 'List solar eclipses in a year'.
- Latitude (`latitude`, number, required): The place's latitude in degrees, -90 to 90 (north is positive). From -90 to 90.
- Longitude (`longitude`, number, required): The place's longitude in degrees, -180 to 180 (east is positive). From -180 to 180.
- Height (m) (`height_m`, number): The place's height above sea level in metres. Defaults to 0. From -90 to 10999.
- Time zone (`time_zone`, text): Also give times in this time zone, daylight saving included, such as America/New_York. Leave blank for UTC only.

**Outputs**

- `date` (text): The date asked about
- `delta_t_seconds` (number): Delta T used in the calculation, seconds
- `description` (text): What is seen, e.g. Sun in Partial Eclipse at this Location
- `duration` (text): How long the eclipse lasts here, e.g. 1h 39m 41.4s
- `duration_of_totality` (text): How long totality lasts here, where it is total
- `event` (text): The eclipse, e.g. Solar Eclipse of 2026 Aug. 12
- `magnitude` (number): Fraction of the Sun's diameter covered at greatest eclipse
- `obscuration_percent` (number): Percent of the Sun's area covered at greatest eclipse
- `stages` (list): Each stage of the eclipse, in order
- `summary` (text): One line describing the result
- `visible` (true/false): False when the eclipse cannot be seen from the place

**Example output**

```json
{
  "date": "2026-08-12",
  "delta_t_seconds": 74.0,
  "description": "Sun in Partial Eclipse at this Location",
  "duration": "1h 39m 41.4s",
  "duration_of_totality": null,
  "event": "Solar Eclipse of 2026 Aug. 12",
  "magnitude": 0.999,
  "obscuration_percent": 100.0,
  "stages": [
    {
      "iso_utc": "2026-08-12T18:32:18Z",
      "local_date": "2026-08-12",
      "local_iso": "2026-08-12T20:32:18+02:00",
      "local_time": "20:32",
      "position_angle_deg": null,
      "stage": "Maximum Eclipse",
      "sun_altitude_deg": 7.2,
      "sun_azimuth_deg": 283.3,
      "time_utc": "18:32:18.1",
      "vertex_angle_deg": null
    }
  ],
  "summary": "Partial solar eclipse seen from here on 2026-08-12: 100% of the Sun covered, greatest at 20:32.",
  "visible": true
}
```

### Get celestial navigation data

Get the almanac data for working out a position from sextant sights: for an assumed position and time, each body above the horizon with its declination, Greenwich hour angle, computed altitude and azimuth, and the altitude corrections.

**Inputs**

- Assumed latitude (`latitude`, number, required): The assumed position's latitude, -90 to 90 (north is positive). From -90 to 90.
- Assumed longitude (`longitude`, number, required): The assumed position's longitude, -180 to 180 (east is positive). From -180 to 180.
- Date and time (`moment`, date and time): The moment, in UTC. Defaults to now.

**Outputs**

- `aries_gha_deg` (number): Greenwich hour angle of the first point of Aries, for star sights, degrees
- `bodies` (list): The bodies above the horizon, as the almanac lists them
- `count` (number): How many are in this result
- `moon_illumination_percent` (number): How much of the Moon is lit, percent
- `moon_phase` (text): The Moon's phase
- `summary` (text): One line describing the result
- `time_ut1` (text): The moment used (UT1), YYYY-MM-DD HH:MM

**Example output**

```json
{
  "aries_gha_deg": 73.595179,
  "bodies": [
    {
      "azimuth_deg": 147.946171,
      "computed_altitude_deg": 27.215128,
      "corrections_apply": true,
      "declination_deg": -19.19974,
      "greenwich_hour_angle_deg": 45.305811,
      "name": "Moon",
      "navigational_star_number": null,
      "parallax_deg": 0.818153,
      "refraction_deg": -0.033525,
      "semidiameter_deg": 0.251254,
      "total_correction_deg": 1.035882
    }
  ],
  "count": 1,
  "moon_illumination_percent": 62.0,
  "moon_phase": "Waxing Gibbous",
  "summary": "27 bodies above the horizon at 2026-10-19 22:00 UT1; the Moon is waxing gibbous, 62% lit.",
  "time_ut1": "2026-10-19 22:00"
}
```

### Get equinoxes and solstices

Get the exact times of a year's equinoxes and solstices (the starts of the seasons) and of Earth's perihelion and aphelion (closest to and farthest from the Sun).

**Inputs**

- Year (`year`, number): 1700 to 2100. Defaults to this year. From 1700 to 2100.
- Time zone (`time_zone`, text): Also give times in this time zone, daylight saving included, such as America/New_York. Leave blank for UTC only.

**Outputs**

- `aphelion` (text): Aphelion: Earth farthest from the Sun
- `count` (number): How many are in this result
- `december_solstice` (text): The December solstice
- `events` (list): The six events, in order
- `june_solstice` (text): The June solstice
- `march_equinox` (text): The March equinox (local ISO 8601 with a time zone, else UTC)
- `perihelion` (text): Perihelion: Earth closest to the Sun
- `september_equinox` (text): The September equinox
- `summary` (text): One line describing the result
- `year` (number): The year asked about

**Example output**

```json
{
  "aphelion": "2026-07-06T13:30:00-04:00",
  "count": 1,
  "december_solstice": "2026-12-21T15:50:00-05:00",
  "events": [
    {
      "date": "2026-03-20",
      "event": "March equinox",
      "iso_utc": "2026-03-20T14:46:00Z",
      "local_date": "2026-03-20",
      "local_iso": "2026-03-20T10:46:00-04:00",
      "local_time": "10:46",
      "time_utc": "14:46"
    }
  ],
  "june_solstice": "2026-06-21T04:24:00-04:00",
  "march_equinox": "2026-03-20T10:46:00-04:00",
  "perihelion": "2026-01-03T12:15:00-05:00",
  "september_equinox": "2026-09-22T20:05:00-04:00",
  "summary": "6 events in 2026; the March equinox is on 2026-03-20.",
  "year": 2026
}
```

### Get sidereal time

Get the sidereal (star) time at Greenwich and at a place, mean and apparent, for a moment or a series of moments: what telescopes use to point at the sky.

**Inputs**

- Latitude (`latitude`, number, required): The place's latitude in degrees, -90 to 90 (north is positive). From -90 to 90.
- Longitude (`longitude`, number, required): The place's longitude in degrees, -180 to 180 (east is positive). From -180 to 180.
- Date and time (`moment`, date and time): The moment, in UTC, between 1800 and 2050. Defaults to now.
- How many times (`repetitions`, number): For a series, how many moments, 1 to 500. Defaults to 1. From 1 to 500.
- Every (`interval`, number): For a series, the gap between moments, with 'Interval unit'. From 1 to 9999.
- Interval unit (`interval_unit`, text): Minutes, hours or days. Defaults to hours. One of: `minutes`, `hours`, `days`.

**Outputs**

- `count` (number): How many are in this result
- `summary` (text): One line describing the result
- `times` (list): One row per moment
- `truncated` (true/false): True when USNO cut the series short at the end of its range

**Example output**

```json
{
  "count": 1,
  "summary": "At 2026-10-19 21:00:00.0 UT1: local mean sidereal time 17:45:16.0005, Greenwich 22:53:23.2005.",
  "times": [
    {
      "date": "2026-10-19",
      "equation_of_equinoxes_seconds": 0.504,
      "greenwich_apparent": "22:53:23.7045",
      "greenwich_mean": "22:53:23.2005",
      "greenwich_mean_hours": 22.889778,
      "local_apparent": "17:45:16.5045",
      "local_mean": "17:45:16.0005",
      "local_mean_hours": 17.754445,
      "ut1_time": "21:00:00.0"
    }
  ],
  "truncated": false
}
```

### Get sun and moon times

Get sunrise, sunset, solar noon, dawn and dusk (civil twilight), moonrise, moonset and the Moon's phase and illumination for one day at a place, in local time.

**Inputs**

- Date (`date_value`, date, required): The day, between 1700 and 2100.
- Latitude (`latitude`, number, required): The place's latitude in degrees, -90 to 90 (north is positive). From -90 to 90.
- Longitude (`longitude`, number, required): The place's longitude in degrees, -180 to 180 (east is positive). From -180 to 180.
- Time zone (`time_zone`, text): Give times in this time zone, daylight saving included, such as America/New_York. Leave blank for UTC.
- UTC offset (hours) (`utc_offset_hours`, number): Instead of a time zone, a fixed offset from UTC, -12 to 14 (e.g. -5 or 5.5). From -12 to 14.

**Outputs**

- `civil_twilight_begins` (text): Dawn: when civil twilight begins (HH:MM, local)
- `civil_twilight_ends` (text): Dusk: when civil twilight ends (HH:MM, local)
- `closest_primary_phase` (text): The nearest new, first quarter, full or last quarter moon
- `closest_primary_phase_date` (text): Its date
- `closest_primary_phase_time` (text): Its time (HH:MM, local)
- `date` (text): The date, YYYY-MM-DD
- `day_length` (text): Time between sunrise and sunset, e.g. 11h 02m
- `day_of_week` (text): Day of the week
- `is_daylight_saving` (true/false): True when the time zone given is on daylight saving time that day
- `moon_always_down` (true/false): True when the Moon never rises that day
- `moon_always_up` (true/false): True when the Moon never sets that day
- `moon_events` (list): Every lunar event of the day, in order
- `moon_illumination_percent` (number): How much of the Moon is lit at local noon, percent
- `moon_phase` (text): The Moon's phase, e.g. Waxing Gibbous
- `moon_transit` (text): When the Moon is highest (HH:MM, local)
- `moonrise` (text): Moonrise (HH:MM, local); empty if the Moon does not rise that day
- `moonset` (text): Moonset (HH:MM, local); empty if the Moon does not set that day
- `solar_noon` (text): When the Sun is highest (HH:MM, local)
- `summary` (text): One line describing the result
- `sun_always_down` (true/false): True when the Sun never rises that day (polar night)
- `sun_always_up` (true/false): True when the Sun never sets that day (polar day)
- `sun_events` (list): Every solar event of the day, in order
- `sunrise` (text): Sunrise (HH:MM, local)
- `sunset` (text): Sunset (HH:MM, local)
- `utc_offset` (text): The offset the times are in, e.g. -04:00

**Example output**

```json
{
  "civil_twilight_begins": "06:55",
  "civil_twilight_ends": "18:51",
  "closest_primary_phase": "First Quarter",
  "closest_primary_phase_date": "2026-10-18",
  "closest_primary_phase_time": "12:12",
  "date": "2026-10-19",
  "day_length": "11h 02m",
  "day_of_week": "Monday",
  "is_daylight_saving": true,
  "moon_always_down": false,
  "moon_always_up": false,
  "moon_events": [
    {
      "phenomenon": "Rise",
      "time": "15:09"
    }
  ],
  "moon_illumination_percent": 60.0,
  "moon_phase": "Waxing Gibbous",
  "moon_transit": "20:11",
  "moonrise": "15:09",
  "moonset": "00:17",
  "solar_noon": "12:53",
  "summary": "2026-10-19 (UTC-04:00): Sunrise 07:22, sunset 18:24; moon waxing gibbous (60% lit).",
  "sun_always_down": false,
  "sun_always_up": false,
  "sun_events": [
    {
      "phenomenon": "Rise",
      "time": "07:22"
    },
    {
      "phenomenon": "Set",
      "time": "18:24"
    }
  ],
  "sunrise": "07:22",
  "sunset": "18:24",
  "utc_offset": "-04:00"
}
```

### Get US daylight saving time dates

Get the dates US daylight saving time begins and ends in a year (1967 onwards).

**Inputs**

- Year (`year`, number): 1967 to 9999. Defaults to this year. From 1967 to 9999.

**Outputs**

- `ends` (text): The day it ends, YYYY-MM-DD
- `starts` (text): The day daylight saving time begins, YYYY-MM-DD
- `summary` (text): One line describing the result
- `year` (number): The year asked about

**Example output**

```json
{
  "ends": "2026-11-01",
  "starts": "2026-03-08",
  "summary": "US daylight saving time in 2026 runs from Sunday 2026-03-08 to Sunday 2026-11-01.",
  "year": 2026
}
```

### List Easter and Christian holy days

List the dates of Ash Wednesday, Palm Sunday, Good Friday, Easter, Ascension Day, Pentecost, Trinity Sunday and the First Sunday of Advent in a year (Western churches).

**Inputs**

- Year (`year`, number): 1583 to 9999. Defaults to this year. From 1583 to 9999.

**Outputs**

- `count` (number): How many are in this result
- `easter` (text): Easter Sunday, YYYY-MM-DD
- `observances` (list): The holy days, in date order
- `summary` (text): One line describing the result
- `year` (number): The year asked about

**Example output**

```json
{
  "count": 1,
  "easter": "2026-04-05",
  "observances": [
    {
      "date": "2026-04-05",
      "day_of_week": "Sunday",
      "observance": "Easter"
    }
  ],
  "summary": "Easter 2026 is on Sunday 2026-04-05.",
  "year": 2026
}
```

### List Islamic holy days

List the dates of the Islamic New Year and the first days of Ramadan and Shawwal that fall in a year, with each one's Islamic calendar year. These are calculated dates; local observance can differ by a day.

**Inputs**

- Year (`year`, number): 622 to 9999. Defaults to this year. From 622 to 9999.

**Outputs**

- `count` (number): How many are in this result
- `observances` (list): The holy days, in date order
- `summary` (text): One line describing the result
- `year` (number): The year asked about

**Example output**

```json
{
  "count": 1,
  "observances": [
    {
      "calendar_year": 1447,
      "date": "2026-02-18",
      "day_of_week": "Wednesday",
      "observance": "First Day of Ramadan"
    }
  ],
  "summary": "3 Islamic observances in 2026; Ramadan 1447 begins 2026-02-18.",
  "year": 2026
}
```

### List Jewish holy days

List the dates of Rosh Hashanah, Yom Kippur, the first day of Sukkot, Hanukkah, the first day of Passover and Shavuot that fall in a year, with each one's Hebrew calendar year. Holidays begin at sunset the evening before.

**Inputs**

- Year (`year`, number): 360 to 9999. Defaults to this year. From 360 to 9999.

**Outputs**

- `count` (number): How many are in this result
- `observances` (list): The holy days, in date order
- `summary` (text): One line describing the result
- `year` (number): The year asked about

**Example output**

```json
{
  "count": 1,
  "observances": [
    {
      "calendar_year": 5787,
      "date": "2026-09-12",
      "day_of_week": "Saturday",
      "observance": "Rosh Hashanah (Jewish New Year)"
    }
  ],
  "summary": "6 Jewish holy days in 2026; Rosh Hashanah 5787 begins 2026-09-12.",
  "year": 2026
}
```

### List moon phases for a year

List every new moon, first quarter, full moon and last quarter in a calendar year, with their exact times.

**Inputs**

- Year (`year`, number): 1700 to 2100. Defaults to this year. From 1700 to 2100.
- Time zone (`time_zone`, text): Also give times in this time zone, daylight saving included, such as America/New_York. Leave blank for UTC only.

**Outputs**

- `count` (number): How many are in this result
- `phases` (list): The phases, in order
- `summary` (text): One line describing the result
- `year` (number): The year asked about

**Example output**

```json
{
  "count": 1,
  "phases": [
    {
      "date": "2026-10-26",
      "iso_utc": "2026-10-26T04:12:00Z",
      "local_date": "2026-10-26",
      "local_iso": "2026-10-26T00:12:00-04:00",
      "local_time": "00:12",
      "phase": "Full Moon",
      "time_utc": "04:12"
    }
  ],
  "summary": "50 moon phases in 2026, including 13 full moons.",
  "year": 2026
}
```

### List solar eclipses in a year

List the solar eclipses of a year, with their dates and kinds (total, annular, hybrid or partial).

**Inputs**

- Year (`year`, number): 1800 to 2050. Defaults to this year. From 1800 to 2050.

**Outputs**

- `count` (number): How many are in this result
- `eclipses` (list): The eclipses, in date order
- `summary` (text): One line describing the result
- `year` (number): The year asked about

**Example output**

```json
{
  "count": 1,
  "eclipses": [
    {
      "date": "2026-08-12",
      "day_of_week": "Wednesday",
      "event": "Total Solar Eclipse of 12 August 2026",
      "kind": "total"
    }
  ],
  "summary": "1 solar eclipse in 2026: Total Solar Eclipse of 12 August 2026.",
  "year": 2026
}
```

### List upcoming moon phases

List the next new moons, first quarters, full moons and last quarters from a date, with their exact times.

**Inputs**

- From (`start_date`, date): The first day to look from. Defaults to today.
- How many (`count`, number): How many phases to list, 1 to 99. Defaults to 4 (one cycle). From 1 to 99.
- Time zone (`time_zone`, text): Also give times in this time zone, daylight saving included, such as America/New_York. Leave blank for UTC only.

**Outputs**

- `count` (number): How many are in this result
- `phases` (list): The phases, in order
- `summary` (text): One line describing the result

**Example output**

```json
{
  "count": 1,
  "phases": [
    {
      "date": "2026-10-26",
      "iso_utc": "2026-10-26T04:12:00Z",
      "local_date": "2026-10-26",
      "local_iso": "2026-10-26T00:12:00-04:00",
      "local_time": "00:12",
      "phase": "Full Moon",
      "time_utc": "04:12"
    }
  ],
  "summary": "1 moon phase; next: Full Moon on 2026-10-26 at 04:12 UTC."
}
```
