Agnus
Agnus is Sunrise Sunset wrapped in an Elixir supervised GenServer.
- Self contained application when added as a dependency
- Simple configuration of lat, long and timezone of physical location of interest
- Caches the current day info to minimize calls to the API
- Returns a map of the data returned by the Sunrise Sunset API
Installation
Install the package by adding agnus
to your list of dependencies in mix.exs
:
def deps do
[
{:agnus, "~> 0.0.2"}
]
end
Configuration
# Defaults if not overridden by local configuration
config :agnus,
day_info: [
# should the GenServer init() and/or init args be logged?
log: [init: false, init_args: false],
# timezone of interest
tz: "America/New_York",
api: [
# url of the API (shouldn't need to be changed)
url: "https://api.sunrise-sunset.org",
# latitude in decimal degrees
lat: 40.2108,
# longitude in decimal degrees
lng: -74.011
]
Basic Usage
See Sunrise Sunset for details on the data available and what each key represents.
At first glance the date times can be confusing since they represent the beginning and end of the phase of the visibility of the sun and the light we see.
- For the time sun dims look at the
*_end
keys.- For the time when the sun shines look at the
*_begin
keys.This could be obvious to everyone however it took a moment of confusion for me to see the nuance.
## Examples
# retrieve all available data for today
iex> Agnus.sun_info(:all)
%{
astronomical_twilight_begin: #DateTime<2020-04-24 04:21:47-04:00 EDT America/New_York>,
astronomical_twilight_end: #DateTime<2020-04-24 21:26:10-04:00 EDT America/New_York>,
civil_twilight_begin: #DateTime<2020-04-24 05:34:11-04:00 EDT America/New_York>,
civil_twilight_end: #DateTime<2020-04-24 20:13:46-04:00 EDT America/New_York>,
day_length: 49311,
nautical_twilight_begin: #DateTime<2020-04-24 04:59:10-04:00 EDT America/New_York>,
nautical_twilight_end: #DateTime<2020-04-24 20:48:47-04:00 EDT America/New_York>,
solar_noon: #DateTime<2020-04-24 12:53:58-04:00 EDT America/New_York>,
sunrise: #DateTime<2020-04-24 06:03:03-04:00 EDT America/New_York>,
sunset: #DateTime<2020-04-24 19:44:54-04:00 EDT America/New_York>
}
# retrieve a list of specific keys
iex> Agnus.sun_info([:civil_twilight_end, :civil_twilight_begin])
%{
civil_twilight_begin: #DateTime<2020-04-24 05:34:11-04:00 EDT America/New_York>,
civil_twilight_end: #DateTime<2020-04-24 20:13:46-04:00 EDT America/New_York>
}
# retrieve a single key
iex> Agnus.sun_info(:civil_twilight_end)
%{
civil_twilight_end: #DateTime<2020-04-24 20:13:46-04:00 EDT America/New_York>}
}
# refresh data for today
iex> Agnus.trigger_sun_info_refresh()
:ok
Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/agnus.