Most of the fields on the Sun/Moon Calculator main form and the Rise/Set Criteria form can be set when the program starts by passing parameters to the program. This can be useful if the calculator is started by a program that can automatically generate most of the parameters. For example, the calculator could be invoked from a program that determined the azimuth and altitude from a vantage point to a feature with which you want to align the Sun or Moon; from those values, the program could generate azimuth and altitude limits for the Sun or Moon, and pass them to the calculator, which could then find dates on which the Sun or Moon is near the feature. Although this would be easy to do, in practice, formulaic position limits would seem a poor substitute for a photographer’s aesthetic judgment.
Simple applications are also possible. For example, parameters could be used to have the calculator perform a certain function on startup, such as showing Sun and Moon rise and set times for the next week, or showing Sun and Moon positions for the current day. These and similar applications can usually be handled with fixed parameters, and the calculator can be started using a Web link, a program shortcut, or the like.
By default, fields corresponding to given parameters are set, but the
calculation is not performed. The calculation can also be performed
automatically when the calculator loads by using the
parameter; if the results are not what you were hoping for, some values
can be adjusted, and the calculation repeated.
Parameters are passed in a query string appended to the URL,
delimited by a question mark (“
?”); the URL
then takes the form
The query consists of a series of
=value pairs separated by ampersands
&”), with each
=value pair giving a parameter and its
value. The parameter list then takes the form
=value2 . . .
URLs cannot contain spaces, which are commonly encoded as
%20”; as an alternative, the Sun/Moon
Calculator converts instances of the underscore
_”) to spaces, so that a place name such as
New Orleans, LA may be given as
the need for encoding. The plus sign (“
not recognized as indicating a space, because it is used for
Search the built-in location database for a location matching
pattern; the first match, if any, is used. If no match is found,
calc parameter is ignored even if set to yes or
an equivalent value.
If Allow regular expressions in location
searches has been selected via the User Preferences
form (or by giving
plain text. Instances of the underscore (“
are converted to spaces, so that
san_fran can be given to
search for San Francisco. The syntax for pattern is described in
the section Search for.
yesand the location given by
searchLocis found, the location properties are copied into the “Specify:” area; the effect is the same as clicking the Copy Selected Location button, except that it is not necessary to first click the “Specify Properties” radio button. This parameter can be useful if you wish to view the properties of a location in the built-in database before doing a calculation; however, in most cases, that isn’t necessary because the properties are shown on the results page.
Look up the location using an online service, and fill in the
location properties if a match is found. If more than one location
matches the pattern, a list of matches is presented; clicking on a
location in that list selects that location. There may be a delay of
several seconds before a list of matches is presented or the results of
single match are entered. If the location is not found or not selected
from a list of matches, the
calc parameter is ignored.
The pattern syntax is different from that for searching the
built-in location database, and varies slightly among the different
online services. The syntax for each service is described under Automatic Fill-In in the entry
for that service. The
useRE parameter has no effect when
this parameter is given.
lookupLocparameter is given but this one is not, GeoNames Web Services are used. This parameter is ignored if the
lookupLocparameter is not given.
lookupLoc parameter is given, any Location
Properties described below are ignored; if the
parameter is given, the properties are entered but the
“Specify” area of the main form is inactive; there usually
is little point in doing this.
The name of the location (e.g.,
San Francisco, CA).
If daylight saving time is to be used, name should include either
, state or province”
for the US and Canada, or
elsewhere, so that the appropriate DST rules can be determined.
Instances of the underscore (“
_”) are converted
to spaces, so that
san_fran can be given to search for San
Francisco, avoiding the need to encode the spaces.
Latitude and longitude may be given either in decimal or in one of the
DMS formats described in the section DMS and HM Input. If
latlon is not given, any other location properties are
Elevation above sea level in meters or feet. If the optional unit is not given, meters are assumed. Non-integral values are rounded to the nearest meter or foot, depending on the calculator’s display mode. If no elevation is given, a value of zero (sea level) is used; this can have a slight effect on results because of the difference in air density.
The time zone is a value ranging from −12 to 12; a
non-integral time zone may be given as decimal or colon-delimited HM (e.g.,
tz=3:30). If no time zone is specified, or a specified
time zone does not correspond to one in the list of values on the main
form, the time zone is calculated from the longitude.
Indicates whether to use (
yes) or not use (
daylight saving time. If a location name is given, the calculator
attempts to determine the appropriate rules for that location; if no
location is given, or the calculator cannot determine the actual rules,
the US rules are used for north latitudes, and the inverse of US rules
are used for southern latitudes.
When the Sun/Moon Calculator is invoked with URL parameters, the Rise and Set Times section is active by default. Several parameters allow fields within this section to be set when the calculator starts.
Dates may be given in various formats, including
(ISO 8601), and
(ISO 8601 without hyphens).
Leading zeros for the month and day are required for the ISO format without hyphens but
are optional for the others.
commonly used in Europe is not recognized, and will
either be interpreted incorrectly if it could represent a valid date
beginning with mm
or generate an error message otherwise.
A date may also be given as
where month is either the full month name or its three-letter abbreviation.
Delimiters for values using month names may be spaces rather than
The optional unit for the date offset and date step can be one of
month is 30 days, and a
Month is 1/12 year.
If no units are given, the default unit of
used for the date offset, and the default unit of
used for the date step; non-integral values are rounded to the nearest
day. When searching for dates that meet specified rise/set criteria, a
date step of other than 1 day usually makes little sense. A space
between the offset and the unit symbol is optional, so that
2 y are equivalent. A space will, of
course, need to be encoded as
%20 in the URL, so it is best
The current date can be given as the start date as
a period (“
A single value examines only one day, and is usually not very useful when used with rise/set criteria.
These parameters set fields in the Rise/Set Criteria form. The following parameters are recognized:
||Sunrise azimuth range|
||Sunrise altitude range|
||Sunrise altitude type:
||Sunset azimuth range|
||Sunset altitude range|
||Sunset altitude type:
||Moonrise azimuth range|
||Moonrise altitude range|
||Moonrise altitude type:
||Moonrise phase range|
||Moon must be waxing at rise:
||Moon must be waning at rise:
||Moonrise semidiameter range|
||Moonrise–Sun event time-difference range|
||Moonrise Sun event:
||Moonset azimuth range|
||Moonset altitude range|
||Moonset altitude type:
||Moonset phase range|
||Moon must be waxing at set:
||Moon must be waning at set:
||Moonset semidiameter range|
||Moonset–Sun event time-difference range|
||Moonset Sun event:
Parameters other than xx
TdiffType take values of the form
A single value for azimuth or altitude can sometimes be useful, but
using single values for both will usually yield no dates.
Angular values for azimuth and altitude may be in decimal or
colon-delimited DMS (e.g.,
indicate whether the corresponding altitude criteria apply to the
body’s upper limb (
center) or its lower limb
bottom). If the relevant
parameter is not given, the body’s upper limb is used if the
average of the altitude range is zero, and the body’s center is
used otherwise. These parameters are ignored if the corresponding
altitude parameters are not also given.
Phase is the fraction of the Moon’s surface that is illuminated;
values range from zero (new moon) to one (full moon). Giving a single
value usually yields no dates.
The Moon cannot be waxing and waning at the same time, so the parameters
mrWaning (and similarly,
msWaning) are mutually exclusive;
if you give both, the last one given is the one that has effect.
Semidiameter is half the Moon’s angular diameter; values range
from 0.245° to 0.284°, but the extreme values are seldom
encountered. These values are inconvenient to remember; to facilitate
specification of the limits, a value less than the minimum is changed to
the minimum, and a value greater than the maximum is changed to the
maximum. Accordingly, the minimum value can be given as
and the maximum value can be given as
the time differences in minutes between specified Sun and Moon events
(e.g., between moonrise and sunset); allowable values are between
±1440 minutes (± 1 day), although values of more than an
hour or so are usually not useful. Non-integral values are rounded to
the nearest minute. A negative value indicates that the Moon event
precedes the Sun event, and an unsigned value indicates that the Moon
event follows the Sun event. For example,
indicates that moonrise must occur between 5 minutes before sunset and 10 minutes after sunset;
indicates that moonrise must occur between 10 and 20 minutes after sunset. If a nonzero altitude has been specified, moonrise refers to the time the Moon crosses that altitude, as discussed in the section Rise and Set Times.
The values for time difference can include appended units for minutes or hours, so that the values above could be given as
though in most cases there is little point in doing so. Recognized unit indicators are described in Calculation Times below.
The values for
be appended to the values of
msTdiff with an “at” sign
@”), so that
Giving a single value for the time difference usually yields no dates.
An exception is when Moon rise/set criteria are given in combination
with a Sun altitude range, in which case a time difference of zero
should normally be given (e.g.,
ssAlt=-5,-3); for a latitude and season
at which the end of civil twilight is 30 minutes after sunset,
these parameters would give approximately the same results as
mrTdiff=15,25. In general, give either a
time-difference range without a Sun altitude range, or a Sun
altitude range and a zero time difference.
Choosing between a Moon event–Sun event time-difference and a Sun
altitude range is discussed in more detail under Moon Rise/Set Time, Alternative: Sun Altitude
indicate the Sun event with which the Moon event is to be compared, and
each takes the value of
sunset. For example,
Parameters given as val[
are converted to min
,max values before error
checking is performed; if allowable limits are exceeded, the error
message complains about the resulting min
values rather than the val or tolerance that was given.
Values not given in the URL parameters are not used in the calculation (i.e., the corresponding boxes on the Rise/Set Criteria form are unchecked).
Several parameters allow setting the fields in the Sun and Moon Positions
area of the calculator, and the
calcType parameter can be
positions to make this area active.
Sometimes it may be useful to give parameters for Sun and Moon positions even when calculating Sun and Moon rise and set times. For example, if you are searching for dates on which moonrise meets certain criteria, and wish to examine any resulting dates by showing Sun and Moon positions at 1-minute intervals between 5 minutes before moonrise and 5 minutes after moonrise, you can set these values using URL parameters rather than having to set them manually. This can be especially helpful if the Sun/Moon Calculator is invoked from another program that automatically generates most of the parameters.
A start or end time may be given either as a specified time in the HM
format described in the section DMS and HM Input, or as an
offset in minutes to a Sun or Moon event given with the
endEvent parameter. Specified
times must be in 24-hour format; either the hours or minutes may be
omitted, but the colon is necessary to distinguish a specified time from
a time offset to an event. A decimal value is interpreted as an offset
to a Sun or Moon event; a negative time offset indicates a time before
the event; a positive offset indicates a time after the event.
The optional unit for the event offset, time offset, and time step can be one of
If no unit is given, the default unit of
minutes is used
for an event offset, and the default unit of
hours is used
for both a time offset and a time step. Non-integral values for event
and time offsets are rounded to the nearest minute; values for the time
step are limited to one of 1, 2, 5, 10, 15, 20, or 30 minutes, or 1
hour. If the time interval is given in hours, and the value is less
than 1 hour, it is rounded to the nearest integral minute; the rounded
value must be one of the allowed intervals. Units make no sense with
specified clock times, and are accordingly disallowed.
For example, giving the parameters
would show Sun and Moon positions from 5 minutes before moonrise
until 5 minutes after moonrise, at 1-minute intervals. Here the
m is required for the time step because the default
hours would show positions only at an hour before
moonrise and at an hour after moonrise, which probably is not what is
wanted. The default unit for an event offset is
times=-5m,5m,1m might add some visual clarity, it
would have the same
would give the same result. The time offset (
-5) for the
start time is an offset to an event, whereas the time offset
+10m is a time offset to the start time. A time
offset to an event for either start or end time is always a negative or
unsigned number; a time offset to the start time always begins with a
plus sign (“
+”). The default unit for a time
offset is hours, so here the appended
m is required.
startEvent=sr would show Sun and Moon positions from 5
minutes before sunrise until noon, at 5-minute intervals.
Values for the Sun and Moon events described below can be appended to
the calculation times with an “at” sign
@”), so that
-0.5h,0.5h,30m@sr,ss would display Sun and Moon positions
every half hour between a half hour before sunrise and a half hour after
0,0,30m@dn,dk might work to much the
same effect, except in some legal contexts—such as when a vehicle
can normally be operated without headlights. If only one value is
given, it is used for both the start and end events; if the start event
is empty (e.g.,
6:00,0.5h,30m@,ss), only the end event is
set. The specified start or end event is ignored if the corresponding
start or end time is a fixed time rather than an event offset (e.g.,
6:00,0.5h,30m@sr,ss, the start event
has no effect).
As with location names, event values may use underscores to represent
sun_transit) to avoid the need for encoding.
The specified start or end event is ignored if the corresponding start or end time is a fixed time rather than an event offset.
If set to
expressions are allowed in the pattern given with the
searchLoc parameter for lookup in the calculator’s
built-in location database; this parameter has no effect on
location lookup using an online service with the
searchLoc pattern uses regular expressions, you
should also give
useRE=yes to ensure that the regular
expressions are recognized; if you wish to ensure that certain
characters (e.g., parentheses) are not interpreted as regular
expressions, you should give
Determines whether the time is shown in 24-hour format (e.g., 0:25, 19:21),
AM or PM (e.g., 12:25 am, 7:21 pm), or universal time (UT).
Universal time is incompatible with daylight saving time; if both are
specified, the last parameter given takes precedence. For example
dstDisp=y displays universal time, and
timeDisp=ut displays DST in the default 24-hour
yes, all results are sent to separate windows, and the value of the Use separate tabs or windows for rise/set times and positions option on the User Preferences form has no effect.
By default, the calculation mode is set to Sun and Moon rise and set
times, equivalent to checking the “Rise and Set Times” radio
button. If desired, the
calcType parameter can be used to
set the calculation mode to Sun and Moon positions.
yes, reset all values on the main form to their defaults before setting other values; among other things, this will set the default location of San Francisco, CA, and clear the properties for a saved location. This can sometimes minimize the number of other parameters that must be given, but the safest approach is always to give all needed parameters.
If the value is other than
no, perform the
calculation after setting any values given with other parameters; the
disp are equivalent to
display. By default,
the calculation is not performed.
Giving the parameters
would show Sun and Moon rise and set times for the current date and two weeks thereafter, for the location saved from when the calculator was last used.
×=0,0,30m &startEvent=sr &endEvent=ss &calc=y
would show Sun and Moon positions every half hour between sunrise and sunset. This could be given more succinctly as
If you lived in or were visiting Durango, CO, a safer query for the dates would be
&srAz=68,75 &dates=1-1-2013,+1y &calc=y
could be used to find the dates in 2013 in Capitol Reef National Park on which the sunrise azimuth is between 68° and 75°; this could be useful if you wanted a particular feature directly illuminated at sunrise.
&mrAz=90.2+0.3 &mrAlt=6.9+0.3 &mrPhase=0.9,1 &mrWaxing=y &dates=1-1-1937,12-31-1942 &calc=y
could be used to help find the date of Ansel Adams’s Moonrise, Hernandez, New Mexico. These parameters result in four potential dates; other criteria (e.g., the position angle of the Moon’s bright limb) would then be needed to arrive at the accepted date of 1 November 1941.
© 2012, 2015 Jeff Conrad