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

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/2025-02-21T00:00:00Z--2025-02-28T00: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/2025-02-20T00:00:00Z--2025-02-21T00: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/2025-02-21T00:00:00Z--2025-02-24T00: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/2025-02-21T00:00:00Z--2025-02-28T00: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/2025-02-21T00:00:00Z--2025-02-28T00: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/2025-02-21T00:00:00Z--2025-02-24T00:00:00Z:PT30M/uv:idx/30.039343,31.232346/html

The UV Index for Italy in summer (2020):

Current situation:
https://api.meteomatics.com/2025-02-21T12: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/2025-02-20T00:30:00Z--2025-02-21T00:00:00Z:PT30M/sun_azimuth:d/51.508021,-0.129410/html