URL Options for the WWW Tide Predictor

Time for a brief side-note. If you are not familiar with writing HTML (the markup language used in WWW documents) and you don't know what a URL (Universal Resource Locator) is, I will not be giving you a tutorial on those things. Please search the Web or consult your local web gurus for information on that first.

Now, assuming you're comfortable with HTML and URLs, you can construct a URL that links directly to the WWW Tide program (tideshow.cgi). It can preselect a site (and also preselect one or more of the customizing selections from the estimate form page). Below is a list of all the available settings (more or less in the order they appear on the form page). The most frequently used would be the site= setting (after which the user who gets the prediction is certainly free to customize subsequent predictions as he or she sees fit).

NOTE: as of April 2002, there is an option on the predictions page that you can check off to view a URL that will do most of the work for you ("Show the URL that would recreate this prediction"). Use that as a base and edit it as you wish, based on this document.

The URL can be inserted as part of a web page (in other words, it can be a link on a web page). Alternately, you can type it directly into the web-address blank in your browser, visit the page, and then save it as a bookmark/favorite. If you do that, then you'd type in only the actual URL, excluding the surrounding HTML tagging (<a href=" and ">...) that is shown in the examples below.

Sample link text within a page of HTML could be:

Note: <a href="http://tbone.biol.sc.edu/tide/tideshow.cgi?site=Friday+Harbor%2C+San+Juan+Island%2C+Washington"> Check local tides</a> before fishing.

That would result in the following on a web page:

Note: Check local tides before fishing.

To force a graph instead of the standard text (though it takes longer to display):

Note: <a href="http://tbone.biol.sc.edu/tide/tideshow.cgi?site=Friday+Harbor%2C+San+Juan+Island%2C+Washington&type=graph"> Check graph of local tides</a> before fishing.

That would result in:

Note: Check graph of local tides before fishing.

Get the idea?

You always give the root URL for the program: href="http://tbone.biol.sc.edu/tide/tideshow.cgi
followed by a question mark. That is then followed by one or more form settings, separated by an ampersand (the & character), and finally terminated with a double-quote. Each of the settings is of the form key=value, where the keys and permissible values are listed below. If you only use one key=value pair (as in the first example above), you don't need any separating ampersands.

Listen up now (this is important): No spaces are allowed anywhere in the URL. The only place you might be tempted to use a space is in the site name. Replace any space with a '+' sign. You must also replace punctuation marks using the hexadecimal escape method mandated for URLs (see HTML references on the WWW, and good luck). Note that you can cheat by using your browser to view the source text of the link I use via the site selection page to see how the names are encoded there. I encourage you to do that.

Listen up again (this is also important): Our machine here is used for a variety of research purposes aside from calculating the tides. We are quite happy to provide a reasonable service. We will become unhappy quickly if someone sets up a site with hard coded URLs that fetch a 1000x500 bitmaped graph and three monthly calendars and hits us 300 times a day. Please be reasonable. I'd guess that 99% of the time, the standard short text summary is just fine. Unless you've got special needs, start with that and let the user decide if he or she really needs (and wants to wait for) a graph or a calendar. Thanks - we appreciate your consideration!

In case you're wondering, the underpinnings for the WWW Tide Predictor are provided by the excellent CGI.pm package for writing CGI programs in Perl. It is by Lincoln D. Stein at the Cold Spring Harbor Laboratory. .

If you have questions/comments/problems/answers, please let me know. I'm Dean Pentcheff at tide@crustacea.nhm.org .

site=Name+of+site

Site for which to calculate tide or current.
The site name must be from the list of site names recognized by the XTide program (check the main site selection page for a list). The name must match one of the site names in the database exactly. All spaces in the site name must be replaced with '+' signs and all punctuation (periods, commas, parantheses, etc.) must be replaced using the standard URL hexadecimal escapes (see remarks above).

type=displaytype

Type of display to generate.
The displaytype must be one of:

• table (for the standard tabular list - this is the default).
• graph (for a graphic plot).
• grapht (for a text plot).
• calen (for a one-month calendar).
• stats (for max/min in a time period).
• mrare (for strict interval output).

tplotdir=direction

Direction for text plots (ignored for other types).
The direction must be one of:

• horiz (for horizontal text plots - this is the default).
• vert (for vertical text plots).

gx=xpixels

X axis size (in pixels) for graphic plots (ignored for other types).
The xpixels value should be a number (keep it below about 2000 or your plot may not work). The default size is 640.

gy=ypixels

Y axis size (in pixels) for graphic plots (ignored for other types).
The ypixels value should be a number (keep it below about 700 or your plot may not work). The default size is 240.

caltype=calendartype

Select text or HTML table for monthly calendar (ignored for other types).
Monthly calendars can be output in straight ASCII text (right out of the XTide program), or formatted as HTML tables (for browsers that support tables). The calendartype must be one of:

• ndp (for the compact HTML table version - this is the default).
• new (for the slightly-wider HTML version).
• www (for the true-calendar HTML version).
• text (for the standard text version).

interval=interval

Set interval for mrare (interval) style output.
Format is: HH:MM to set interval in hours and minutes.

glen=days

Number of days to display (ignored for calendars, which are always one month long).
The days value can be a decimal number, generally somewhere between 0.5 and 7. The name glen is an artifact from the days when this controlled only the graph time. The default number of days is 2.

units=unit

Units to use for the results.
The value for day must be one of:

• feet or f (for results in feet).
• meters or m (for results in meters).
• default (for results in the default units for that site in our database).

fontsize=+/-sizechange

Font size increment (positive or negative) for display text.
For browsers that support changes of font sizes, this will cause the font for the display to be increased (numbers preceeded by '+' signs) or decreased (numbers preceeded by '-' signs). The value should be one of the following:
-2 -1 +0 +1 +2 +3
The default is '+0' (no change from standard size).

cleanout=1

Suppress printing the form under the prediction.
Setting this to 1 suppresses the form, to lead to a cleaner output for sites that already have preselected prediction options. If absent, the whole "Options" form will appear - this is the default.

suppressing the credits and warnings

Some way to suppress the standard warnings at the top.
I have deliberately not made this an available option. I want the cautions to be visible to everyone, and I want David Flater to receive credit for doing the real work on this program.

killsun=1

Suppress sunrise/sunset and lunar information.
If present, and set to a non-zero value, causes sunrise/sunset times and lunar phase information to be omitted from the output. If absent, solar and lunar information are shown - this is the default.

comment=1

View site comment from database.
If present, and set to a non-zero value, causes the comment from the harmonics database to be displayed along with the estimates. If absent, no comment is shown - this is the default.

tzone=zonetype

Select time zone with which to label display.
The zonetype must be one of:

• local (use the time zone local to the chosen site, attempting automatic daylight saving correction - this is the default).
• utc (use UTC with no offset).

ampm24=timeformat

Select 24-hour or am/pm time formatting.
The timeformat must be one of:

• 24 (use 24-hour time - this is the default).
• ampm (use AM/PM time).

If absent, times are in 24-hour format - this is the default.

weekday=1

Add the three-letter abbreviation for the day of the week to time displays.
If present, and set to a non-zero value, causes time displays to include the three-letter day of the week (Mon, Tue, etc.). If absent, no weekday name is shown - this is the default.

year=year
month=month
day=day
hour=hour
min=minute

Starting time for calculation.
If not set, calculations start right after the nearest preceeding midnight (or the beginning of the current month for calendars). Therefore the default behavior is for all of these to be omitted.

• The year should be a four-digit value between 1970 and 2025 (inclusive). For dates outside those limits, see the d_year, d_month, etc. fields below.
  
• The month should be a two-digit month with January being 01 through December being 12.
  
• The day should be a numerical day of the month.
  
• The hour should be a numerical hour of the day (in 24-hour time).
  
• The minute should be a numerical minute value (between 0 and 59, with no decimal allowed).

d_year=year
d_month=month
d_day=day
d_hour=hour
d_min=minute

For "distant dates" (earlier than 1970 or later than 2025), starting time for calculation.
For technical reasons, there are two different programs that do the predictions in the "distant" and "near" timeframes. The "distant" calculations will only use the UTC time zone. Putting a non-empty value in the d_year field forces the use of the "distant"-time program.

• The d_year should be a four-digit value between 1700 and 2100 (inclusive). Using the d_year field (instead of year) forces the use of the "distant"-time calculation program. Note that if your date is within 1970-2025, you are better off ignoring the "d_..." date/time fields, and you should use the plain "year", "month", etc. fields.
  
• The d_month should be a two-digit month with January being 01 through December being 12.
  
• The day should be a numerical day of the month.
  
• The d_hour should be a numerical hour of the day (in 24-hour time).
  
• The d_minute should be a numerical minute value (between 0 and 59, with no decimal allowed).

colortext=color
colordatum=color
colormsl=color
colortics=color
colorday=color
colornight=color
colorebb=color
colorflood=color

Colors for various parts of a graphical plot.
See the form page for what each of these colors. The color specifications must be one of: black white yellow red skyblue seagreen blue or deep-<br>skyblue (no that is not a typo - those brackets and things are needed within that skyblue color).

nofill=1

For color graph, don't fill under water level.
If present, and set to a non-zero value, causes the color graph to have the tide level drawn as a line. This is not the default.

nodlines=1

For color graph, don't put in datum and msl lines.
If present, and set to a non-zero value, causes the color graph to omit the datum and msl lines, which are present by default.

notimes=1

For color graph, omit the high/low tide times.
If present, and set to a non-zero value, causes the high and low tide times to be omitted. This is useful for long-term graphs, where the times otherwise overlap. This is not the default.

bwgraph=1

For color graph, make it all black and white.
If present, and set to a non-zero value, causes the color graph to be put out in all black and white - useful for printing. This is not the default.

tablelen=
obsolete, replaced by glen=

This used to specify the length of textual output in lines; now everything is controlled by the length of time (glen).

tinc=hours
obsolete, no longer adjustable.

Number of hours between time labels for graphic plot
XTide 2 no longer allows you to tweak this, but is much better at doing it itself.

skinny=1
obsolete, more or less replaced with notimes.

Skinnier time labels if possible
Now, instead of skinny-ifying time labels in the graphs, just rip them out altogether using the notimes option.

dst=1
obsolete
tzoff=hours
obsolete

Force 1 hour daylight saving, or set an absolute offset from UTC.
No one ever used these and they made the code much more complex. Gone.