Get sun related statistics from different APIs

get_sun_stats() retrieves sun statistics using different models and data sources.

At the moment, none of the get_sun_stats() methods uses real-world data. All of them are based on models.

Each API have its peculiarities. We recommend checking the API documentation for a better understanding of the mechanisms behind them (see the Details section).

Usage

get_sun_stats(
  latitude,
  longitude,
  date = Sys.Date(),
  tz = "UTC",
  method = "suncalc"
)

Arguments

latitude: A number indicating the latitude of the desired location in decimal degrees.
longitude: A number indicating the longitude of the desired location in decimal degrees.
date: (optional) A Date value indicating the moment in time (default: Sys.Date()).
tz: (optional) A string indicating the time zone of the results. See timezones to learn more (default: "UTC").
method: (optional) A string indicating which method or API to use. Valid values are: "suncalc" and "sunrise-sunset.org". See the Details section to learn more (default: "suncalc").

Value

A list object with the following elements:

date: A Date vector with the same value of the date parameter.
latitude: A number with the same value of the latitude parameter.
longitude: A number with the same value of the longitude parameter.
tz: A string with the same value of the tz parameter.
sunrise_start: An hms value indicating the moment when the top edge of the sun appears on the horizon.
sunrise_end: An hms value indicating the moment when bottom edge of the sun touches the horizon.
golden_hour_end: An hms value indicating the moment when the morning golden hour (soft light, best time for photography) ends.
solar_noon: An hms value indicating the moment when sun is in the highest position.
golden_hour_start: An hms value indicating the moment when the evening golden hour (soft light, best time for photography) starts.
sunset_start: An hms value indicating the moment when the bottom edge of the sun touches the horizon.
sunset_end: An hms value indicating the moment when the sun disappears below the horizon. This is also the moment when the evening civil twilight starts.
dusk: An hms value indicating the moment when the dusk starts. This is also the moment when the evening nautical twilight starts.
nautical_dusk: An hms value indicating the moment when nautical dusk starts. This is also the moment when the evening astronomical twilight starts.
night_start: An hms value indicating the moment when the night starts (dark enough for astronomical observations).
nadir: An hms value indicating the darkest moment of the night, i.e., when the sun is in the lowest position.
night_end: An hms value indicating the moment when the night ends. This is also the moment when the morning astronomical twilight starts.
nautical_dawn: An hms value indicating the moment when nautical dawn starts. This is also the moment when the morning nautical twilight starts.
dawn: An hms value indicating the moment when the dawn starts. This is also the moment when the morning nautical twilight ends and the morning civil twilight starts.

Details

`methods` argument

At the moment, get_sun_stats() can access the results of two APIs, described below.

"suncalc": Use the sun statistics provided by the suncalc package.
"sunrise-sunset.org": Use the sun statistics provided by the Sunrise-Sunset API (requires an internet connection). Click here to learn more.

The "sunrise-sunset.org" method tends to give a close, but usually lower, result when compared with the "suncalc" method.

Please note that when using method = "sunrise-sunset.org" you need to show attribution with a link to https://sunrise-sunset.org. Also note that summer time adjustments are not included in the returned data when using this method.

Other statistics

The purpose of this function is to return basic statistics about the sun. If you need other related statistics, we recommend checking the following packages.

cptec: An Interface to the CPTEC/ INPE API.
nasapower: NASA POWER API Client.
rnoaa: NOAA Weather Data from R.

Examples

latitude <- -23.5489
longitude <- -46.6388
date <- Sys.Date()
tz <- "America/Sao_Paulo"

get_sun_stats(
  latitude = latitude,
  longitude = longitude,
  date = date,
  tz = tz,
  method = "suncalc"
)
#> $date
#> [1] "2025-06-05"
#> 
#> $latitude
#> [1] -23.5489
#> 
#> $longitude
#> [1] -46.6388
#> 
#> $tz
#> [1] "America/Sao_Paulo"
#> 
#> $sunrise_start
#> 06:44:16
#> 
#> $sunrise_end
#> 06:46:50
#> 
#> $golden_hour_end
#> 07:17:28
#> 
#> $solar_noon
#> 12:06:31
#> 
#> $golden_hour_start
#> 16:55:34
#> 
#> $sunset_start
#> 17:26:13
#> 
#> $sunset_end
#> 17:28:46
#> 
#> $dusk
#> 17:53:17
#> 
#> $nautical_dusk
#> 18:21:18
#> 
#> $night_start
#> 18:48:54
#> 
#> $nadir
#> 00:06:31
#> 
#> $night_end
#> 05:24:08
#> 
#> $nautical_dawn
#> 05:51:44
#> 
#> $dawn
#> 06:19:45
#> 

library(curl)

if (has_internet()) {
  get_sun_stats(
    latitude = latitude,
    longitude = longitude,
    date = date,
    tz = tz,
    method = "sunrise-sunset.org"
  )
}
#> $date
#> [1] "2025-06-05"
#> 
#> $latitude
#> [1] -23.5489
#> 
#> $longitude
#> [1] -46.6388
#> 
#> $tz
#> [1] "America/Sao_Paulo"
#> 
#> $sunrise_start
#> 06:35:16
#> 
#> $sunrise_end
#> NA
#> 
#> $golden_hour_end
#> NA
#> 
#> $solar_noon
#> 11:58:41
#> 
#> $golden_hour_start
#> NA
#> 
#> $sunset_start
#> NA
#> 
#> $sunset_end
#> 17:22:06
#> 
#> $dusk
#> 17:45:22
#> 
#> $nautical_dusk
#> 18:13:23
#> 
#> $night_start
#> 18:41:00
#> 
#> $nadir
#> NA
#> 
#> $night_end
#> 05:16:21
#> 
#> $nautical_dawn
#> 05:43:58
#> 
#> $dawn
#> 06:11:59
#>