Sunrise

NAME

Sunrise - Calculate sun/moon rise/set for a given place

Given a position in longitude and latitude and date, returns an XML or JSON document indicating when the sun and the moon rise and set. The elevation angle of the sun at solar noon is also given, as well as the starting/endpoint of the polar day/night if occuring in the given interval.

The times are all in local timezone, computed from the offset parameter. Coordinates are given with east and north as positive values. Make sure that the offset is correct with regards to the coordinates, as this is also used to determine the correct date transition in addition to converting to local time.

Note that some days may lack sunrise/sunset, this indicates that either polar night or polar day is in effect (you can determine which by checking if the solarnoon elevation is negative or positive). There may also be from 0 to 2 moonrises/sets per day.

Timezone offset

The offset parameter is the difference from UTC, as defined in ISO 8601. This is used to calculate the period start as follows:

  <date> + "T00:00:00" + <offset>

It is then converted to UTC, and the period end computed by adding the relevant number of days. The UTC times returned from the backend library are then converted back to the local timezone again using the offset parameter. This ensures that the events requested will actually fall inside the period specified.

This is also the reason that you should never use GMT for locations outside this timezone, since for e.g. Hawaii you would get events for the period 2018-05-10T14:00 to 2018-05-11T14:00 local time, instead of 2018-05-11T00:00 to 2018-05-12T00:00, so the sunset would actually be for the previous day.

Presently timezones for the offset parameter range from -12:00 to +14:00, although this may change in the future. For GMT, only +00:00 is allowed. You can see a list of all current timezones on https://en.wikipedia.org/wiki/List_of_UTC_time_offsets.

The algorithm is based on JPL ephemerides 405, and the accuracy should be comparable to other services using this data, typically +-1 minute.

Calculating the sun and moon elevations

As the sun elevation describes an almost perfect sine curve on the sky, the position at a given time can be calculated from the four fixed points given in the sunrise, solarnoon, sunset and solarmidnight elements. Similarly, the moonrise, high_moon, moonset and low_moon elements can be used to calculate moon elevation. If any of the elements are missing, it means the object is not visible or does not go below the horizon.

The formula is described in a paper which can be downloaded in PDF format.

Changes from 1.1

a new XML format, including enough data that most users will need, in an easier to parse format
a "days" parameter to indicate period (instead of from/to)
all timestamps in local timezone instead of UTC
a new "offset" parameter to indicate timezone (format "+HH::MM" or "-HH:MM")
"advanced requests" are no longer supported (see below)

The previous versions also had a bug where the timezone was guessed from the given coordinates, so the calculated UTC date sometimes ended up on the wrong side of the International Date Line.

Discontinuation of the "advanced request" interface

In addition to the "simple" interface which have been upgraded, the previous versions also included the ability to call the underlying C/FORTRAN library directly. In practice this was hard to use, document and understand, and only implemented by a handful of users. We have therefore decided to drop this feature in 2.0, instead including all relevant data which most users will be needing.

However, for those of you who would like to continue using the underlying astro library, there are several alternatives available. As it is a pure mathematical calculation without any reliance on online data, the most practical solution is to run it yourself locally. Here are the current options:

download and compile the code yourself from https://github.com/FrankThomasTveter/astro-api
download a Docker image as described on https://github.com/FrankThomasTveter/astro-api/wiki
use our demo site at http://astro.met.no/astro

(Note that the latter is currently not setup for production with load balancing, redundancy etc., and should not be used in production environments until further notice.)

USAGE

Parameters

The following parameters are supported:

lat (latitude), in decimal degrees, mandatory
lon (longtitude), in decimal degrees, mandatory
height altitude above ellipsoide, in km (default 0). (Note that the XML schema requires an int, but the API accepts float. This is a bug.)
date, given as YYYY-MM-DD, mandatory
offset, timezone offset, on the format +HH:MM or -HH:MM mandatory
days, number of days forward to include (default 1, max 15)

Example URLs

https://api.met.no/weatherapi/sunrise/2.0/.json?lat=40.7127&lon=-74.0059&date=2023-03-28&offset=-05:00 (New York, as JSON)
https://api.met.no/weatherapi/sunrise/2.0/?lat=59.933333&lon=10.716667&date=2023-03-28&offset=+01:00 (Blindern, Oslo without DST)
https://api.met.no/weatherapi/sunrise/2.0/?lat=74&lon=56&date=2018-06-24&offset=+03:00&days=3 (polar midsummer in Novaya Zemlya)
https://api.met.no/weatherapi/sunrise/2.0/?lat=76.51&lon=25.01&date=2018-11-01&offset=+02:00 (start of polar night in Hopen, Svalbard)
https://api.met.no/weatherapi/sunrise/2.0/?date=2020-01-03&height=2.2&lat=71.076667&lon=-8.164444&offset=%2B01%3A00 (sunrise on top of Beerenberg volcany, Jan Mayen)

See also https://github.com/FrankThomasTveter/astro-api/wiki/event for more info on returned values

Output format

In contrast to previous versions, the new XML format only contains event that actually are occuring. This means that sunrise/sunset may not occur in polar regions, and there may be 0, 1 or 2 moonrise/moonsets.

The data are sorted per location and time. For each date, 0..n of the following elements may be included (attributes given in parens), sorted chronologically:

sunrise (time)
sunset (time)
solarnoon (time, elevation)
solarmidnight (time, elevation)
moonphase (time, value), value representing:

0..25: "waxing crescent"

25..50: "waxing gibbous"

50..75: "waning gibbous"

75..100: "waning crescent"
moonshadow (time, elevation, azimuth)
moonposition (time, elevation, azimuth, range)
moonrise (time)
moonset (time)
high_moon (time, elevation)
low_moon (time, elevation)
polardayend (time)
polardaystart (time)
polarnightend (time)
polarnightstart (time)

A desc attribute may also be present to explain the correct scientific term for the event. This should not be used for computational purposes as it may change without warning.

Example

Oslo: https://api.met.no/weatherapi/sunrise/2.0?lat=59.933333&lon=10.716667&date=2018-05-11&offset=+01:00

    <astrodata>
      <meta licenseurl="https://api.met.no/license_data.html"/>
      <location latitude="59.933333" longitude="10.716667" height="0">
        <time date="2018-05-11">
          <moonphase time="2018-05-11T00:00:00+01:00" value="83.993572055"
            desc="LOCAL MOON STATE * MOON PHASE= 84.0 (waning crescent)"/>
          <moonshadow time="2018-05-11T00:00:00+01:00" elevation="-32.253039217" azimuth="271.265661838"
            desc="LOCAL MOON STATE * SHADOW ANGLES (azi=271.3,ele=-32.3)"/>
          <moonposition time="2018-05-11T00:00:00+01:00" elevation="-25.267017305" azimuth="56.467253658" range="392860.059469108"
            desc="LOCAL MOON POSITION Elv: -25.267 deg, Azi: 56.467, Rng: 392860.1 km"/>
          <solarmidnight time="2018-05-11T00:13:10+01:00" elevation="-12.268744841"
            desc="LOCAL DIURNAL MINIMUM SOLAR ELEVATION (Min= -12.26874)"/>
          <moonrise time="2018-05-11T03:26:15+01:00"
            desc="LOCAL DIURNAL MOON RISE"/>
          <sunrise time="2018-05-11T03:49:59+01:00"
            desc="LOCAL DIURNAL SUN RISE"/>
          <high_moon time="2018-05-11T09:02:58+01:00" elevation="25.034235521"
            desc="LOCAL DIURNAL MAXIMUM MOON ELEVATION (Max= 25.03424)"/>
          <solarnoon time="2018-05-11T12:13:43+01:00" elevation="47.993878848"
            desc="LOCAL DIURNAL MAXIMUM SOLAR ELEVATION (Max= 47.99388)"/>
          <moonset time="2018-05-11T14:43:59+01:00"
            desc="LOCAL DIURNAL MOON SET"/>
          <sunset time="2018-05-11T20:38:41+01:00"
            desc="LOCAL DIURNAL SUN SET"/>
          <low_moon time="2018-05-11T21:15:27+01:00" elevation="-32.732948918"
            desc="LOCAL DIURNAL MINIMUM MOON ELEVATION (Min= -32.73295)"/>
        </time>
      </location>
    </astrodata>