Sun API Parameters

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-8601¹ 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 1^st 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

Example:

Shows the sunrise and sunset time over a period of one week:
https://api.meteomatics.com/2023-12-07T00:00:00Z--2023-12-14T00:00:00Z:P1D/sunrise:sql,sunset:sql/47.423336,9.377225/csv

validdate;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/2023-12-06T00:00:00Z--2023-12-07T00: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/2023-12-07T00:00:00Z--2023-12-10T00: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/2023-12-07T00:00:00Z--2023-12-14T00: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/2023-12-07T00:00:00Z--2023-12-14T00: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

Example:

The UV index for Cairo in June 2020:

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

Current situation:
https://api.meteomatics.com/2023-12-07T00:00:00Z--2023-12-10T00:00:00Z:PT30M/uv:idx/30.039343,31.232346/html

The UV Index for Italy in summer (2020):

Current situation:
https://api.meteomatics.com/2023-12-07T12: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:

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

Current situation:
https://api.meteomatics.com/2023-12-06T00:30:00Z--2023-12-07T00: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/2023-12-06T00:00:00Z--2023-12-07T00: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/2023-12-06T00:00:00Z--2023-12-07T00:00:00Z:PT1H/is_day:idx,is_night:idx/47.4245,9.3767/html?model=mix