NAME

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

DESCRIPTION

Given a position in longitude and latitude and date, returns an XML 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.

Changes from 1.1

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:

(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:

Example URLs

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:

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>

SCHEMA

Schema is available as https://api.met.no/weatherapi/sunrise/2.0/schema

TODO

Changelog

version 2.0 released: 2018-11-19

New v.2 XML format is finally ready for production (no changes from beta). Note that offset parameter now is of type +/-HH:MM to conform to ISO and XSD standards. Maximum days now set to 10.

Version 1.1 will expire 2019-02-15

version 2.0 beta: 2018-04-25

XML format trimmed, toned and beefed up, date and offset params are now mandatory. Expected to go into production in beginning of May.

version 2.0 beta: 2018-03-09

Rewrite using new backend; only simple request supported, with different interface and XML format

version 1.1: 2015-11-01

version 1.0 expires 2016-06-06

bugfix: publish 0, 1, or 2 moon rise / moon sets per date.

version 1.0: 2014-04-01

Added direct request to astronomical event library.

Uses JPL ephemerides DE405.

Output now agrees well with "Almanakk for Norge".

version 1.0: 2012-01-11

Maximum 30 days are accepted in from-to search

version 1.0: 2009-06-02

Better use of algorithm, should give more accurate data

New parameters from and to, returning all events in the range

Either date or from and to is now compulsory

Version 0.9 will expire 2009-06-24

version 0.9: 2008-09-10

Algorithm for the computation is updated. Should be more accurate.

Version 0.8 will expire 2008-10-01

version 0.8: 2008-06-24

New product, not in accordance with the Norwegian almanac.