Sunrise

NAME

Sunrise - Calculate sun (eventually also moon) events, as seen from a specific location on Earth

DESCRIPTION

Returns a GeoJSON document indicating time and direction to when the sun is on its highest point on a given date (defaults to today) as seen from a specified point on Earth, as well as the preceding sunrise and following sunset (which may not be on the same date). The lowest point in the cycle is also returned.

Examples

Without DST:

Blindern, Oslo

https://api.met.no/weatherapi/sunrise/3.0/sun?lat=59.933333&lon=10.716667&date=2023-01-31&offset=+01:00

New York

https://api.met.no/weatherapi/sunrise/3.0/sun?lat=40.7127&lon=-74.0059&date=2023-01-31&offset=-05:00

Elevation and azimuth

In version 3 all angles are computed from the disc centre of the target. For sunrise/set (which nominally indicates when the upper limb crosses the horizon), the official definition is the moment when the center of the sun is 0.8333 degrees below the horizon. This is an approximation given the average apparent radius of the sun and average refraction (both which can vary slightly due to irregular planetary orbits and atmospheric conditions).

Date start/end times

In contrast to version 2 where the starting point of a given date was computed from the timezone offset, version 3 instead uses the longitude to compute the midday point (the time when the sun crosses the meridian). The date interval is then calculated as the midday point +/- 12 hours, corresponding to the start and end of the mean solar day.

The reason for this is to fix a bug in version 2, where sunset sometimes came before sunrise and actually referred to the previous day's sunset. Also, sometimes user were adding offset=+00:00 to get UTC timestamps, which resulted in the start and end times being computed incorrectly.

Polar regions

Due to Daylight Savings Time, sunsets near polar latitudes sometimes occur after midnight (this can also occur in places where the mean solar time differs greatly from the local time). By using the mean solar day as the time period, this is now reported correctly in version 3.

Polar regions also experience periods of midnight sun in summer, as well as polar nights in winter when the sun doesn't rise over the horizon. In these cases, the sunrise and/or sunset parameters will return null, and the solarmidnight and solarnoon parameters will show the visible attribute as true and false respectively.

Examples for Røst, Norway

(CEST in summer, CET in winter)

Sunset after midnight

https://api.met.no/weatherapi/sunrise/3.0/sun?lat=67.52&lon=12.1&date=2022-05-25&offset=+02:00

Start of midnight sun

https://api.met.no/weatherapi/sunrise/3.0/sun?lat=67.52&lon=12.1&date=2022-05-29&offset=+02:00

End of midnight sun

https://api.met.no/weatherapi/sunrise/3.0/sun?lat=67.52&lon=12.1&date=2022-07-14&offset=+02:00

Polar night

https://api.met.no/weatherapi/sunrise/3.0/sun?lat=67.52&lon=12.1&date=2023-12-21&offset=+01:00

Timezone offset

The optional offset parameter is the difference between local time and UTC, as defined in ISO 8601. This is used mainly for returning timestamps in local time, but is also used in some instances to calculate the correct date period.

If omitted, all times will be given in UTC.

Issues with the International Date Line

Sometimes the International Date Line doesn't follow the 180° meridian, so that places in the Western hemisphere have a positive timezone offset and vice versa. Examples include Tonga (which is on 175°W but uses UTC+13), and Attu (172.9°E and UTC-10, same as Hawaii). In these cases it is mandatory to add the offset parameter or you will get results for the wrong calendar day.

Nukuʻalofa, Tonga (UTC+13)

https://api.met.no/weatherapi/sunrise/3.0/sun?lat=-21.133333&lon=-175.2&date=2023-01-31&offset=+13:00

Attu (UTC-10)

https://api.met.no/weatherapi/sunrise/3.0/sun?lat=52.90&lon=172.91&date=2023-01-31&offset=-10:00

Hawaii (UTC-10)

https://api.met.no/weatherapi/sunrise/3.0/sun?lat=-19.57&lon=-155.5&date=2023-01-31&offset=-10:00

Changes from version 2

  • Version 3 now uses GeoJSON format instead of XML
  • 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
  • The offset parameter is now optional, with timestamps defaulting to UTC

USAGE

Methods

/sun

Returns data about sun movement for a single day

/moon (not yet available)

Returns data about moon movements and phases

Parameters

The following parameters are supported (items in italics are optional):

  • lat (latitude), in decimal degrees
  • lon (longtitude), in decimal degrees
  • date, given as YYYY-MM-DD
  • offset, timezone offset, on the format +HH:MM or -HH:MM

Output format

The response is in GeoJSON format, with temporal attributes as defined in JSON-FG. The format is very similar to the Textforecast product.

Oslo: https://api.met.no/weatherapi/sunrise/3.0?lat=59.933333&lon=10.716667&date=2022-12-18&offset=+01:00

    {
       "type" : "Feature",
       "copyright" : "MET Norway",
       "licenseURL" : "https://api.met.no/license_data.html",
       "geometry" : {
          "coordinates" : [
             10.716667,
             59.933333
          ],
          "type" : "Point"
       },
       "when" : {
          "interval" : [
             "2022-12-17T23:17:00Z",
             "2022-12-18T23:17:00Z"
          ]
       },
       "properties" : {
          "body" : "Sun",
          "solarmidnight" : {
             "disc_centre_elevation" : -53.47,
             "time" : "2022-12-19T00:13+01:00",
             "visible" : false
          },
          "solarnoon" : {
             "disc_centre_elevation" : 6.67,
             "time" : "2022-12-18T12:13+01:00",
             "visible" : true
          },
          "sunrise" : {
             "azimuth" : 140.12,
             "time" : "2022-12-18T09:16+01:00"
          },
          "sunset" : {
             "azimuth" : 219.87,
             "time" : "2022-12-18T15:10+01:00"
          }
       }
    }

Changelog

New Sunrise beta version 3.0: 2023-01-03

Total rewrite now using GeoJSON format.

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

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.

You can download a PDF document explaining the formulas in detail.

Sources

Sunrise 3 uses the Skyfield Python library for the calculations. If you have more advanced needs than is covered by this service we recommend downloading this or a similar library and do your calculations locally.