Most of the fields on the Sun/Moon Calculator main form and the Sun/Moon Search 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 calc
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
http://www.largeformatphotography.info/sunmooncalc/?query
The query consists of a series of
name=value pairs separated by ampersands
(“&”), with each
name=value pair giving a parameter and its
value. The parameter list then takes the form
=value1&name2=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 New_Orleans,_LA, avoiding
the need for encoding. The plus sign (“+”) is
not recognized as indicating a space, because it is used for
other purposes.
searchLoc=pattern
Search the built-in location database for a location matching
pattern; the first match, if any, is used. If no match is found,
the 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 useRE=yes), pattern
may include JavaScript regular expressions; otherwise, pattern is
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.
copyLoc=y|yes|n|no
y or yes and the location given by
searchLoc is 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.
lookupLoc=pattern
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.
lookupLocSvc=GeoNames|USGS_XML|USGS_TX
lookupLoc parameter is given but
this one is not, GeoNames Web Services are used. This parameter is
ignored if the lookupLoc parameter is not given.
If the lookupLoc parameter is given, any Location
Properties described below are ignored; if the searchLoc
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.
loc=name
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
“, country”
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.
latlon=latitude,longitude
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
ignored.
elev=elevation[m|ft]
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.
tz=time zone
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.5 or
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.
dst=y|yes|n|no
Indicates whether to use (yes) or not use (no)
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.
ht=height[m|ft]
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=start[,end[,step[unit]]]dates=start[,+offset[unit][,step[unit]]]
Dates may be given in various formats, including
mm-dd-yyyy,
mm/dd/yyyy,
yyyy-mm-dd,
(ISO 8601), and
yyyymmdd
(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.
The format
dd-mm-yyyy
commonly used in Europe is not recognized, and will
either be interpreted incorrectly if it could represent a valid date
beginning with mm-dd,
or generate an error message otherwise.
A date may also be given as
dd-month-yyyy,
month-dd-yyyy,
or
yyyy-month-dd,
where month is either the full month name or its three-letter abbreviation.
Delimiters for values using month names may be spaces rather than
hyphens.
The optional unit for the date offset and date step can be one of
d,
w,
m,
M,
y,
day[s],
week[s],
month[s],
Month[s], or
year[s].
A month is 30 days, and a Month is 1/12 year.
If no units are given, the default unit of years is
used for the date offset, and the default unit of days is
used for the date step; non-integral values are rounded to the nearest
day. When searching for dates that meet specified search 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
2y and 2 y are equivalent. A space will, of
course, need to be encoded as %20 in the URL, so it is best
avoided.
The current date can be given as the start date as today or
a period (“.”) (e.g., today+1year
or .+1year).
A single value examines only one day, and is usually not very useful when used with search criteria.
These parameters set fields in the Sun/Moon Search Criteria form. The following parameters are recognized:
srAz |
Sunrise azimuth range |
srAlt |
Sunrise altitude range |
srAltType |
Sunrise altitude type:
t|top|c|ctr|center|b|btm|bottom
|
ssAz |
Sunset azimuth range |
ssAlt |
Sunset altitude range |
ssAltType |
Sunset altitude type:
t|top|c|ctr|center|b|btm|bottom
|
mrAz |
Moonrise azimuth range |
mrAlt |
Moonrise altitude range |
mrAltType |
Moonrise altitude type:
t|top|c|ctr|center|b|btm|bottom
|
mrPhase |
Moonrise phase range |
mrWaxing |
Moon must be waxing at rise:
y|yes|n|no
|
mrWaning |
Moon must be waning at rise:
y|yes|n|no
|
mrSD |
Moonrise semidiameter range |
mrTdiff |
Moonrise–Sun event time-difference range |
mrTdiffType |
Moonrise Sun event:
sr|sunrise or
ss|sunset |
msAz |
Moonset azimuth range |
msAlt |
Moonset altitude range |
msAltType |
Moonset altitude type:
t|top|c|ctr|center|b|btm|bottom
|
msPhase |
Moonset phase range |
msWaxing |
Moon must be waxing at set:
y|yes|n|no
|
msWaning |
Moon must be waning at set:
y|yes|n|no
|
msSD |
Moonset semidiameter range |
msTdiff |
Moonset–Sun event time-difference range |
msTdiffType |
Moonset Sun event:
sr|sunrise or
ss|sunset |
Parameters other than xxAltType and
xxTdiffType take values of the form
min,max or
val[+tolerance].
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., 2:30).
The parameters srAltType, ssAltType,
mrAltType, and msAltType
indicate whether the corresponding altitude criteria apply to the
body’s upper limb (t|top), its
center (c|ctr|center) or its lower limb
(b|btm|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
mrWaxing and mrWaning (and similarly,
msWaxing and 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 0
and the maximum value can be given as 1.
The parameters mrTdiff and msTdiff indicate
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,
mrTdiff=-5,10&mrTdiffType=sunset
indicates that moonrise must occur between 5 minutes before sunset and 10 minutes after sunset;
mrTdiff=10,20&mrTdiffType=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
mrTdiff=10m,20m&mrTdiffType=sunset
though in most cases there is little point in doing so. Recognized unit indicators are described in Calculation Times below.
The values for mrTdiffType and msTdiffType can
be appended to the values of mrTdiff and
msTdiff with an “at” sign
(“@”), so that
mrTdiff=-5,10@ss
Giving a single value for the time difference usually yields no dates.
An exception is when Moon search 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
Range.
The parameters mrTdiffType and msTdiffType
indicate the Sun event with which the Moon event is to be compared, and
each takes the value of sr|sunrise or
ss|sunset. For example,
msTdiffType=ss
Parameters given as val[+tolerance].
are converted to min,max values before error
checking is performed; if allowable limits are exceeded, the error
message complains about the resulting min,max
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 Sun/Moon Search 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
set to 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.
posDate=date
times=start[unit][,end[unit][,step[unit]]]times=start[unit][,+offset[unit][,step[unit]]]
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
startEvent or 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
h,
hr,
hour[s],
m,
min,
or
minute[s].
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 times=-5,5,1m,
startEvent=moonrise, and endEvent=moonrise
would show Sun and Moon positions from 5 minutes before moonrise
until 5 minutes after moonrise, at 1-minute intervals. Here the
unit m is required for the time step because the default
value of 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 minutes,
so giving times=-5m,5m,1m might add some visual clarity, it
would have the same times=-5,5,1m.
The parameters times=-5,+10m,1m,
startEvent=moonrise, and endEvent=moonrise
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.
The parameters times=-5,12:00,5m and
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
sunset; technically, 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.,
with 6:00,0.5h,30m@sr,ss, the start event sr
has no effect).
startEvent=event
endEvent=event
dn or dawnsr or sunrisest, suntransit, or sun transitss or sunsetdk or duskmr or moonrisemt, moontransit, or moon transitms or moonset
As with location names, event values may use underscores to represent
spaces (e.g., 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.
useRE=y|yes|n|no
If set to y or yes, JavaScript regular
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 lookupLoc
parameter.
If 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 useRE=no.
timeDisp=24|am|ut
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 DST parameter is ignored.
dstDisp=n|no|y|yes
azDisp=24|t|true|m|mag|magnetic
tw=c|civil|a|alltwilight=c|civil|a|all
sepWin=y|yes|n|no
y or 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.
searchPos=y|yes|n|no
calcType=t|times|p|pos|positions
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.
reset=n|no|y|yes
y|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.
calc=n|no|y|yes|disp|display|print
If the value is other than n|no, perform the
calculation after setting any values given with other parameters; the
value display or print has the same effect as
clicking the Display or Print button. The values yes and
disp are equivalent to display. By default,
the calculation is not performed.
Giving the parameters
dates=.,+2w&calc=y
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.
calcType=pos×=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
calcType=pos×=0,0,30m@sr,ss&calc=y
If you lived in or were visiting Durango, CO, a safer query for the dates would be
searchLoc=durango&dates=.,+2w&calc=y
The parameters
searchLoc=capitol_reef&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.
The parameters
searchLoc=hernandez&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–2019 Jeff Conrad