- NAME
- DESCRIPTION
- USAGE
- NOTES
- Changelog
- Version 3.0 in production: 2023-06-15
- New version 3.0 beta: 2023-01-03
- Version 2.0 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
NAME
Sunrise - Calculate sun or moon events, as seen from a specific location on Earth
DESCRIPTION
Returns a GeoJSON document indicating time and direction to when the sun (or moon) 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 sun/moonrise and following sun/moonset (which may not be on the same date).
The lowest point in the cycle is also returned.
Note that any or all of these may be null.
The source code is available on GitHub, if you have a server it's usually more efficient to run it locally than to query the API.
USAGE
Methods
- /sun
-
Returns data about solar movement for a single day (local mean solar time)
- /moon
-
Returns data about lunar movements and phases for a single day (local mean solar time)
Parameters
The following parameters are supported:
- lat (latitude), in decimal degrees
- lon (longtitude), in decimal degrees
- date, given as YYYY-MM-DD
- offset (optional), timezone offset, on the format +HH:MM or -HH:MM
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.
Presently timezones for the offset parameter range from -12:00 to +15: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.
Example URLs
Sun (without DST):
- Blindern, Oslo
- New York
-
https://api.met.no/weatherapi/sunrise/3.0/sun?lat=40.7127&lon=-74.0059&date=2024-04-24&offset=-05:00
Moon (without DST):
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.
For more information, see the Sunrise data format and the GeoJSON documentation.
NOTES
Calculating the start and end time of the day
Due to Daylight Savings Time, sunsets near polar latitudes sometimes occur after midnight local time. In those cases, version 2 returned the previous sunset which came before sunrise on the same date.
To avoid this bug,
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 +/- approx 12 hours,
corresponding to the start and end of the mean solar day.
Since the day officially starts at midnight,
solarmidnight will always precede solarnoon,
even if it may be slightly outside the mean solar day.
For more information, see the Sunrise technical documentation.
Changelog
Version 3.0 in production: 2023-06-15
Version 2.x have been deprecated, and will be terminated on 2023-09-01
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
offsetparameter is now optional, with timestamps defaulting to UTC - The
daysparameter has been removed, output is now only 1 day to better optimize caching and response times - The
heightparameter has been removed, as sunrise times don't really change with altitude given flat terrain
Version 2.0 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
Bugfix: publish 0, 1, or 2 moon rise / moon sets per date. Version 1.0 expires 2016-06-06
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.