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

Example:

  • Shows the sunrise and sunset time over a period of one week:
    https://api.meteomatics.com/2024-04-12T00:00:00Z--2024-04-19T00: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:

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:

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:

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/2024-04-11T00:30:00Z--2024-04-12T00: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:

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:

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:

Example:
  • Solar Eclipse in North America on the 8th of April, 2024 plotted with MetX.
    Solar eclipse metx

Footnotes

  1. ISO-8601 date format: https://www.iso.org/standard/40874.html, http://en.wikipedia.org/wiki/ISO_8601