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

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:

(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.)



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

See also 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.



      <meta licenseurl=""/>
      <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)"/>


Schema is available as

(Note that the Schema URL specified in noNamespaceSchemaLocation is currently not working.)


  • Add expires headers
  • Add mocking to unit tests


New version 3.0 beta: 2023-01-03

  • Total rewrite now using GeoJSON format instead of XML
  • Sun and moon events are now separate requests, instead of in the same document
  • Date is now calculated as the local mean solar day, instead of calendar date as before. This ensures sunrise always comes before sunset
  • The offset parameter is now optional, with timestamps defaulting to UTC
  • The days parameter has been removed, output is now only 1 day to better optimize caching and response times
  • The height parameter has been removed, as sunrise times don't really change with altitude given flat terrain

Height parameter fixed: 2020-01-03

Due to an error the height parameter was accidentally called alt in the interface (but not in the documentation). This has now been fixed.

More data for version 2.0: 2019-03-14

moonposition is now repeated for every day in the interval, not just the first day. We have also added a phase attribute to moonposition to show the moon phase for each day, not just the first. Max days is now set to 15.

Since there are only additions to the existing format we assume keeping the existing version is more convenient than bumping so that everyone will have to modify their existing clients.

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.



Other versions

More information