Sun/Moon Calculator
URL Parameter Reference

Contents

Introduction
Parameter Format
Location Parameters
Location Lookup—Built-In Database Location Lookup—Online Service Location Properties
Parameters for Sun and Moon Rise and Set Times
Calculation Dates Sun and Moon Parameters
Parameters for Sun and Moon Positions
Date for Positions Calculation Calculation Times Sun and Moon Events
User Preferences
Use Regular Expressions Time Display DST Display Azimuth Display Twilight Display Window Behavior
Other Parameters
Calculation Type Reset on Load Calculate on Load User Preferences
Examples

Introduction

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 calc parameter; if the results are not what you were hoping for, some values can be adjusted, and the calculation repeated.

Parameter Format

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

name1=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.

Location Parameters

Several parameters can be used to set the location—by searching the calculator’s built-in location database, by using the GeoNames WebServices to find the location, or by specifying location properties.

Location Lookup—Built-In Database

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
If set to 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.

Location Lookup—Online Service

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
Use the GeoNames Web Services, the USGS GNIS XML Service, or the service provided by the USGS Texas Water Science Center, respectively, for location lookup; if the 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.

Location Properties

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]
Height above the horizon 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. This value cannot be greater than the location’s elevation, and in most cases, it is considerably less. It can sometimes be difficult to give an accurate value for this parameter because both the observer’s elevation and the elevation of the visible horizon must be known.

Parameters for Sun and Moon Rise and Set Times

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.

Calculation Dates

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 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 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 rise/set criteria.

Sun and Moon Parameters

These parameters set fields in the Rise/Set 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
would succinctly indicate moonrise between 5 minutes before and 10 minutes after sunset.

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&mrTdiff=0); 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
indicates that the time difference is between moonset and sunset, and may be appropriate for planning an observation or photograph of a new moon.

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 Rise/Set Criteria form are unchecked).

Parameters for Sun and Moon Positions

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.

Date for Positions Calculation

posDate=date
This sets the date on which to calculate Sun and Moon positions; the format is the same as that described in Calculation Dates above.

Calculation Times

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).

Sun and Moon Events

startEvent=event
endEvent=event
These parameters give the Sun or Moon events to which time offsets apply. Allowable values for event are
dn or dawn
sr or sunrise
st, suntransit, or sun transit
ss or sunset
dk or dusk
mr or moonrise
mt, moontransit, or moon transit
ms 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.

User Preferences

Some of the options on the User Preferences form can be set with parameters. Giving one of these parameters is equivalent to checking the corresponding option on the User Preferences form. The setting is retained across sessions; accordingly, to ensure a desired value when invoking the calculator with URL parameters, give the appropriate parameter with that value to override the retained value.

Use Regular Expressions

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.

Time Display

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 last parameter given takes precedence. For example dstDisp=y&timeDisp=ut displays universal time, and timeDisp=ut&dstDisp=y displays DST in the default 24-hour format.

DST Display

dstDisp=n|no|y|yes
Determines whether times will be displayed as daylight saving time if the location uses daylight saving time and DST is in effect. As indicated above, DST is incompatible with universal time if both are specified, the last parameter given takes precedence.

Azimuth Display

azDisp=24|t|true|m|mag|magnetic
Determines whether azimuths are shown relative to true north or magnetic north. This parameter also causes azimuths specified on the Rise/Set Criteria form to be interpreted relative to magnetic north.

Twilight Display

tw=c|civil|a|all
twilight=c|civil|a|all
Determines whether times are shown for astronomical, nautical, and civil twilight, or only for civil twilight.

Window Behavior

sepWin=y|yes|n|no
Determines whether each result is shown in a separate tab or window, or each result replaces a previous result. If this parameter is given with a value of 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.

Other Parameters

Calculation Type

calcType=times|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 on Load

reset=n|no|y|yes
If the value is 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.

Calculate on Load

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.

Examples

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&times=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&times=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.