Sun API Parameters
Sunrise & Sunset | Sunshine Duration | Relative Sunshine Duration | UV Index | Solar Azimuth Angle | Solar Elevation Angle | Day & Night | Solar Eclipse
Sunrise & Sunset
These parameters return the times of sunrise and sunset in UTC at a given location.
sunrise:<unit>
sunset:<unit>
Sunrise and sunset times are available in the following units: sql, dn, ux
sql
will return a time stamp according to the ISO-86011 format (YYYY-MM-DDThh:mm:ssZ
).dn
refers to the date number. The date number represents the whole and fractional number of days from 1-Jan-0000 to a specific date and is equivalent to the serial date number used in Matlab.
ux
refers to the Unix timestamp. It gives the total number of elapsed seconds since 00:00:00 UTC on the 1st of January 1970.
Note: Some special cases may occur, which give rise to the following outputs (no date/time outputs):
-777: The sun is not visible
-888: The sun is always visible
Note: When these variables are queried for a specific time, the last sunrise before the query’s time will be returned. The sunset that will be returned will be the one following the sunrise mentioned before. In general, the returned sunset will always be after the returned sunrise and the returned sunrise will be the last one before the query time.
Example:
- Shows the sunrise and sunset time over a period of one week:
https://api.meteomatics.com/2024-10-05T00:00:00Z--2024-10-12T00:00:00Z:P1D/sunrise:sql,sunset:sql/47.423336,9.377225/csvvaliddate;sunrise:sql;sunset:sql 2020-04-15T22:00:00Z;2020-04-15T04:33:00Z;2020-04-15T18:10:00Z 2020-04-16T22:00:00Z;2020-04-16T04:31:00Z;2020-04-16T18:12:00Z 2020-04-17T22:00:00Z;2020-04-17T04:29:00Z;2020-04-17T18:13:00Z 2020-04-18T22:00:00Z;2020-04-18T04:27:00Z;2020-04-18T18:14:00Z 2020-04-19T22:00:00Z;2020-04-19T04:25:00Z;2020-04-19T18:16:00Z 2020-04-20T22:00:00Z;2020-04-20T04:24:00Z;2020-04-20T18:17:00Z 2020-04-21T22:00:00Z;2020-04-21T04:22:00Z;2020-04-21T18:19:00Z 2020-04-22T22:00:00Z;2020-04-22T04:20:00Z;2020-04-22T18:20:00Z
Accumulated Sunshine duration
Gives the amount of time the sun was shining within the requested interval.
sunshine_duration_<interval>:<unit>
Available intervals: 1h, 3h, 6h, 12h, 24h
Available Units: h, min
Examples:
- Compute the sunshine duration within the last hour over the duration of one day:
https://api.meteomatics.com/2024-10-04T00:00:00Z--2024-10-05T00:00:00Z:PT1H/sunshine_duration_1h:h/47.423336,9.377225/html - Compute the sunshine duration within the last 12 hours:
https://api.meteomatics.com/2024-10-05T00:00:00Z--2024-10-08T00:00:00Z:PT12H/sunshine_duration_12h:min/47.423336,9.377225/html
Relative sunshine duration
The duration of sunshine divided by the amount of time the sun was above the horizon at the queried coordinate and time.
sunshine_duration_24h:p
Examples:
- Shows the relative sunshine duration over a period of ten days:
https://api.meteomatics.com/2024-10-05T00:00:00Z--2024-10-12T00:00:00Z:P1D/sunshine_duration_24h:min/47.423336,9.377225/html - The same as above just as a json output:
https://api.meteomatics.com/2024-10-05T00:00:00Z--2024-10-12T00:00:00Z:P1D/sunshine_duration_24h:min/47.423336,9.377225/json{ "version": "3.0", "user": "mr. example", "dateGenerated": "2021-02-16T07:28:02Z", "status": "OK", "data": [ { "parameter": "sunshine_duration_24h:min", "coordinates": [ { "lat": 47.423336, "lon": 9.377225, "dates": [ { "date": "2021-02-16T00:00:00Z", "value": 60 }, { "date": "2021-02-17T00:00:00Z", "value": 438.6 }, { "date": "2021-02-18T00:00:00Z", "value": 174.5 }, { "date": "2021-02-19T00:00:00Z", "value": 370.7 }, { "date": "2021-02-20T00:00:00Z", "value": 495.2 }, { "date": "2021-02-21T00:00:00Z", "value": 627.6 }, { "date": "2021-02-22T00:00:00Z", "value": 634.8 }, { "date": "2021-02-23T00:00:00Z", "value": 640 } ] } ] } ] }
UV Index
The UV Index is computed based on model outputs and downscaled with 90m-resolution topography data. Instantaneous values as well as maxima within certain time periods can be queried.uv:idx
uv_max_<interval>:idx
Available intervals: 1h, 2h, 3h, 6h, 12h, 24h
- The UV index for Cairo in June 2020:
Current situation:validdate;uv:idx 2020-06-15T06:00:00Z;4 2020-06-15T06:30:00Z;5 2020-06-15T07:00:00Z;7 2020-06-15T07:30:00Z;8 2020-06-15T08:00:00Z;9 2020-06-15T08:30:00Z;10 2020-06-15T09:00:00Z;11 2020-06-15T09:30:00Z;12 2020-06-15T10:00:00Z;12 2020-06-15T10:30:00Z;11 2020-06-15T11:00:00Z;10 2020-06-15T11:30:00Z;9 2020-06-15T12:00:00Z;8 2020-06-15T12:30:00Z;6 2020-06-15T13:00:00Z;5 2020-06-15T13:30:00Z;4 2020-06-15T14:00:00Z;2
https://api.meteomatics.com/2024-10-05T00:00:00Z--2024-10-08T00:00:00Z:PT30M/uv:idx/30.039343,31.232346/html - The UV Index for Italy in summer (2020):
https://api.meteomatics.com/2024-10-05T12:00:00Z/uv:idx/italy:0.02,0.02/html_map
Solar Azimuth Angle
The solar azimuth angle defines the sun's relative direction along the local horizon.
sun_azimuth:d
Example:
- The solar azimuth angle for London on Feb 11th, 2021:
Current situation:validdate;sun_azimuth:d 2021-02-10T00:30:00Z;4.7 2021-02-10T01:00:00Z;16.6 2021-02-10T01:30:00Z;27.8 2021-02-10T02:00:00Z;38.2 2021-02-10T02:30:00Z;47.6 2021-02-10T03:00:00Z;56.2 2021-02-10T03:30:00Z;63.9 2021-02-10T04:00:00Z;71.1 2021-02-10T04:30:00Z;77.7 2021-02-10T05:00:00Z;83.9 2021-02-10T05:30:00Z;89.9 ... 2021-02-10T18:30:00Z;263.8 2021-02-10T19:00:00Z;269.6 2021-02-10T19:30:00Z;275.6 2021-02-10T20:00:00Z;281.8 2021-02-10T20:30:00Z;288.4 2021-02-10T21:00:00Z;295.4 2021-02-10T21:30:00Z;303.1 2021-02-10T22:00:00Z;311.6 2021-02-10T22:30:00Z;321.0 2021-02-10T23:00:00Z;331.3 2021-02-10T23:30:00Z;342.4 2021-02-11T00:00:00Z;352.7
https://api.meteomatics.com/2024-10-04T00:30:00Z--2024-10-05T00:00:00Z:PT30M/sun_azimuth:d/51.508021,-0.129410/html
Solar Elevation Angle
The solar elevation angle (angle between the sun and the horizon) gives the position of the sun above the horizon.sun_elevation:d
Example:
- The solar elevation angle for Oslo on summer solstice:
Current situation:
https://api.meteomatics.com/2024-10-04T00:00:00Z--2024-10-05T00:00:00Z:PT1H/sun_elevation:d/59.914941,10.743319/html
Day & Night
These two parameters tell you whether the sun is below or above the horizon.
0: sun below the horizon, 1: sun above the horizon
is_day:idx
0: sun above the horizon, 1: sun below the horizon
is_night:idx
Example:
-
Day and night indices for today:
http://api.meteomatics.com/2024-10-04T00:00:00Z--2024-10-05T00:00:00Z:PT1H/is_day:idx,is_night:idx/47.4245,9.3767/html?source=mix
Solar Eclipse
Variable referring to the obscuration of the Sun's disk caused by the Moon. It depends on the position of the Sun and the Moon.
solar_eclipse:p
Example:
-
Solar Eclipse in North America on August 21st, 2017:
https://api.meteomatics.com/2017-08-21T16:00:00Z--2017-08-21T21:00:00Z:PT30M/solar_eclipse:p/37,-87.7/html
- Solar Eclipse in North America on the 8th of April, 2024 plotted with MetX.
Footnotes
- ISO-8601 date format: https://www.iso.org/standard/40874.html, http://en.wikipedia.org/wiki/ISO_8601