Get sun related statistics from different APIs

get_sun_stats() allows you to get sun statistics using different APIs.

At the moment, none of the get_sun_stats() methods use 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.

get_sun_stats(lat, lon, date = Sys.Date(), tz = "UTC", method = "suncalc")

Arguments

lat: A number indicating the latitude, in decimal degrees, of the desired location.
lon: A number indicating the longitude, in decimal degrees, of the desired location.
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 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 object with the same value of the date parameter.
lat: A number with the same value of the lat parameter.
lon: A number with the same value of the lon 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 moment 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

Requirements

When method = "suncalc", get_sun_stats() will require the suncalc package.

When method = "sunrise-sunset.org", get_sun_stats() will require an internet connection and the curl and jsonlite packages.

If you don't have any or one of the packages mentioned above, you can install them with install.packages("curl", "jsonlite", "suncalc").

`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 https://sunrise-sunset.org/ API (requires an internet connection). See https://sunrise-sunset.org/api 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

lat <- -23.5489
lon <- -46.6388
date <- Sys.Date()
tz = "America/Sao_Paulo"

if (requireNamespace("suncalc", quietly = TRUE)) {
    get_sun_stats(lat = lat, lon, date, tz, method = "suncalc")
}
#> $date
#> [1] "2023-09-26"
#> 
#> $lat
#> [1] -23.5489
#> 
#> $lon
#> [1] -46.6388
#> 
#> $tz
#> [1] "America/Sao_Paulo"
#> 
#> $sunrise_start
#> 05:53:40
#> 
#> $sunrise_end
#> 05:55:59
#> 
#> $golden_hour_end
#> 06:23:29
#> 
#> $solar_noon
#> 11:59:18
#> 
#> $golden_hour_start
#> 17:35:06
#> 
#> $sunset_start
#> 18:02:36
#> 
#> $sunset_end
#> 18:04:55
#> 
#> $dusk
#> 18:27:30
#> 
#> $nautical_dusk
#> 18:53:47
#> 
#> $night_start
#> 19:20:14
#> 
#> $nadir
#> 23:59:18
#> 
#> $night_end
#> 04:38:21
#> 
#> $nautical_dawn
#> 05:04:48
#> 
#> $dawn
#> 05:31:05
#> 

if (requireNamespace("curl", quietly = TRUE) &&
    requireNamespace("jsonlite", quietly = TRUE)) {
    if (curl::has_internet()) {
        get_sun_stats(
            lat = lat, lon, date, tz, method = "sunrise-sunset.org"
            )
    }
}
#> $date
#> [1] "2023-09-26"
#> 
#> $lat
#> [1] -23.5489
#> 
#> $lon
#> [1] -46.6388
#> 
#> $tz
#> [1] "America/Sao_Paulo"
#> 
#> $sunrise_start
#> 05:44:22
#> 
#> $sunrise_end
#> NA
#> 
#> $golden_hour_end
#> NA
#> 
#> $solar_noon
#> 11:51:27
#> 
#> $golden_hour_start
#> NA
#> 
#> $sunset_start
#> NA
#> 
#> $sunset_end
#> 17:58:31
#> 
#> $dusk
#> 18:19:56
#> 
#> $nautical_dusk
#> 18:46:14
#> 
#> $night_start
#> 19:12:41
#> 
#> $nadir
#> NA
#> 
#> $night_end
#> 04:30:12
#> 
#> $nautical_dawn
#> 04:56:40
#> 
#> $dawn
#> 05:22:58
#>