Subsections of Data

Data Substitutions

Suntimes supports limited %substitutions, a set of tags that are replaced with values from the data set.

Substitutions may be used within widget titles, alarm notes, or within action data or extras.

widget title widget title action data action data

Examples

%loc, %M, or %t can be used to include the location name, event name, or time zone as part of a widget’s title.

%dm and %em@<event> can be used to pass time (milliseconds) as part of an action; e.g. URI content://com.android.calendar/time/%dm opens the calendar app.

%lat and %lon can be used to pass the location as part of an action; e.g. URI geo:%lat,%lon opens the map app.

Subsections of Data Substitutions

Available Substitutions

Date/Time:

  • %t for time zone (id) (e.g. US/Arizona)
  • %d for formatted date (e.g. February 12)
  • %dd for day (short) (e.g. Mon)
  • %dD for day (long) (e.g. Monday)
  • %dY for year (e.g. 2018)
  • %dt for formatted time (of last update)
  • %dT for formatted time with seconds (of last update)
  • %dm for time in milliseconds (of last update)
  • %eot for formatted ’equation of time’ (of last update)
  • %eot_m for ’equation of time’ milliseconds (of last update)

Location:

  • %loc for label (e.g. Phoenix)
  • %lat for latitude
  • %lon for longitude
  • %lel for elevation (e.g. 385 meters)

Misc:

  • %s for data source (e.g. sunrisesunsetlib)
  • %id for appWidgetID

Sun Widgets:

  • %m for mode (short) (e.g. Civil)
  • %M for mode (long) (e.g. Civil Twilight)
  • %o for order (e.g. Last/Next, Today)
  • %em@<event> event milliseconds
  • %et@<event> event formatted time
  • %eT@<event> event formatted time (with seconds)
  • %eA@<event> event altitude
  • %eZ@<event> event azimuth
  • %eD@<event> event declination
  • %eR@<event> event right ascension

where <event> is:

Sun WidgetsSun Position Widgets
<event>
rising sr
setting ss
noon sn
rising setting
civil twilight cr cs
nautical twilight nr ns
astronomical twilight ar as
blue hour 4deg b4r b4s
blue hour 8deg b8r b8s
golden hour gr gs

Moon Widgets:

  • %i for moon illumination (e.g. 25%)
  • %M for moon phase (e.g. Waxing Crescent)
  • %o for order (e.g. Last/Next, Today)

Solstice Widgets:

  • %m for mode (short) (e.g. Solstice)
  • %M for mode (long) (e.g. Winter Solstice)
  • %o for order (e.g. Closest Event, Upcoming Event)

Data Sources

Suntimes uses third-party libraries to perform astronomical calculations.

The data source settings allow for choosing between different libraries (or choosing between different algorithms offered by those libraries).

Suntimes -> Settings -> General -> Advanced

Data source settings Data source settings

These are advanced settings that affect the speed and accuracy of calculations, and may limit which features are available.

Subsections of Data Sources

Available Data Sources

Library Description
sunrisesunsetlib Not Recommended Somewhat inaccurate and sometimes buggy. Does not support altitude, seconds-based calculation, solstice, equinox, or sun position. Based on “Almanac for Computers” by the USNO. github.com/mikereedell/sunrisesunsetlib-java
ca.rmen.sunrisesunset Partially Recommended Similar to sunrisesunsetlib but with reasonable precision. Does not support altitude, solstice, equinox, or sun position. Based on the algorithms published by NOAA. github.com/caarmen/SunriseSunset
time4a-simple Not Recommended Somewhat inaccurate. Does not support altitude. Based on “Almanac for Computers” by the USNO.
time4a-noaa Partially Recommended Same algorithm used by ca.rmen.sunrisesunset with reasonable precision. Does not support altitude. Based on the algorithms published by NOAA.
time4a-cc Recommended Good precision taking the altitude of locations into account. Based on “Calendrical Calculations” by Dershowitz/Reingold. Supports all features.
time4a-time4j Recommended Default Best precision taking the altitude of locations, the elliptic shape of the earth and typical weather conditions into account. Based on “Astronomical Algorithm” by Jean Meeus. Supports all features. github.com/MenoData/Time4A

A few important details:

  • Do not expect precision better than minutes. The app hides seconds by default (but this can be enabled).
  • The precision of the USNO and NOAA algorithms tends to be very inaccurate in polar regions.
  • The time4j and cc algorithms may differ substantially (up to 10 minutes) from algorithms that do not account for altitude.
  • One difference between the time4j and cc algorithms is that cc only assumes the altitude of the observer by an approximated geodetic model, while time4j does it using a spheroid (WGS84) and the assumption of a standard atmosphere (for refraction).
  • None of these algorithms are able to account for local topology (a mountain directly in front of you), or deviating local weather conditions.

Adding Data Sources

The app can be extended to add additional data sources by implementing the Suntimes Calculator interface.

Data Provider

Suntimes can provide data to plugins or add-on apps through a content-provider.