- New version 3.0 beta: 2023-01-03
- Height parameter fixed: 2020-01-03
- More data for version 2.0: 2019-03-14
- version 2.0 released: 2018-11-19
- version 2.0 beta: 2018-04-25
- version 2.0 beta: 2018-03-09
- version 1.1: 2015-11-01
- version 1.0: 2014-04-01
- version 1.0: 2012-01-11
- version 1.0: 2009-06-02
- version 0.9: 2008-09-10
- version 0.8: 2008-06-24
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.
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
solarmidnight elements. Similarly, the
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.
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.)
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)
https://api.met.no/weatherapi/sunrise/2.0/.json?lat=40.7127&lon=-74.0059&date=2023-06-07&offset=-05:00(New York, as JSON)
https://api.met.no/weatherapi/sunrise/2.0/?lat=59.933333&lon=10.716667&date=2023-06-07&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
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:
- 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)
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.
<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 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
offsetparameter is now optional, with timestamps defaulting to UTC
daysparameter has been removed, output is now only 1 day to better optimize caching and response times
heightparameter 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.