geotoad.1

.TH "GEOTOAD" "1" "23 Mar 2024" "steve8x8@googlemail.com" "Geocaching Query Tool"

.SH "NAME"

geotoad \- geocaching query tool

.SH "SYNOPSIS"
.TP
\fBgeotoad\fR
(without any parameters) will invoke the text user interface (TUI)
.TP
\fBgeotoad\fR \fI[options]\fR \fB[\-\-]\fR \fI<search>\fR
(command-line version)

.SH "NOTE"
.PP
If GeoToad was not installed from a (distribution-specific) package
(like .rpm for RedHat, OpenSuse, CentOS and derivatives; .deb for Debian
and Ubuntu, etc.), it may be necessary to invoke GeoToad with the
\fB.rb\fR
suffix, as in \fBgeotoad.rb\fR, \fB./geotoad.rb\fR, \fBruby geotoad.rb\fR
or even \fBruby2.1.5 geotoad.rb\fR
(if the \fBruby\fR in your PATH is not the one you want to use).

.SH "DESCRIPTION"
.PP
GeoToad is software to help speed up the boring part of geocaching:
choosing the cache(s) to target, and collecting the available data.
.PP
GeoToad lets you perform queries against the Geocaching website,
and export the matching geocaches to numerous devices and over 20 file formats.
.PP
If run without any parameters,
\fBgeotoad\fR
will launch the interactive mode ("text user interface", "TUI").
It can also be used in command-line mode for specific queries.

.SH "DISCLAIMER"
.PP
GeoToad uses the public web pages created by GroundSpeak, to gather information
about geocaches. It does not use the official API. Therefore, GeoToad's way
of accessing information can be interpreted as "spidering" which is forbidden
by GS's Terms of Use.
,BR
Strictly speaking, using GeoToad may harm your GeoCaching account and possibly more!
.PP
The authors have taken a few measures to reduce the impact of the website access,
including a progressive slowdown for bigger queries, but there is no safe limit.
.PP
The software is provided as-is, also in source form, for educational purposes.
By using it to gather actual geocache descriptions and related information,
you accept all liability for possible damages.

.SH "OPTION SYNTAX"

.SS "Toggled options:"
\fB"No-argument"\fR options, with the exception of \fB\-\-verbose\fR which
implements multiple levels, are \fB"toggles"\fR, i.e. they can be switched
on by the first usage on the command line, switched off by the second, etc.

.SS "(MULTI) options:"
Where \fBmultiple entries\fR are possible (e.g. for cache sizes, owners, etc.,
marked by \fB(MULTI)\fR below),
they can be delimited by a pipe symbol (\fB|\fR) or a colon (\fB:\fR),
or you can define your own delimiter(s).
Make sure the pipe symbols are properly escaped from the command shell!
.PP
The TUI internally uses the pipe symbol \fB|\fR.

.SS "(USERFILE) options:"
If the user name is followed by an "equal" sign and a filename
(as in \fIusername\fR\fB=\fR\fIfilename\fR),
instead of querying the server the first column of the file is interpreted as
GCxxxxx cache IDs.
.PP
\fBWarning:\fR Since colons are used as default \fB(MULTI)\fR delimiters,
if you want to use a file from another (Windows) drive, or with a filename
containing a colon for another reason, you will have to define your own
delimiter (set) - see the \fB\-m\fR (\fB\-\-delimiter\fR) option for that.

.SH "OPTIONS"

.SS "Unambiguous abbreviations:"
Option keywords are case-sensitive, and may be separated from values by whitespace
or an equal sign \fB=\fR.
.PP
Options can be unambiguously abbreviated, for example, \fB\-\-password\fR may be written
as \fB\-\-pas\fR (but not \fB\-\-p\fR).

.SS "Help and verbosity:"
.TP
\fB\-h\fR|\fB\-\-help\fR
get a short command-line option summary
.TP
\fB\-v\fR|\fB\-\-verbose\fR|\fB\-\-debug\fR
enable debugging output - very helpful in case of malfunctions.
.PP
Multiple (currently up to 3) \fB\-v\fR options raise the debug level, resulting in copious output.
.TP
\fB\-\-stderr\fR|\fB\-\-errors\fR
send warnings and errors to \fIstderr\fR too, send debug messages to \fIstderr\fR \fBonly\fR
(since 3.34.1)

.SS "User credentials:"
.TP
\fB\-u\fR|\fB\-\-username\fR \fIusername\fR
geocaching.com username (required)
.TP
\fB\-p\fR|\fB\-\-password\fR \fIpassword\fR
geocaching.com password (required)
.TP
\fB\-P\fR|\fB\-\-proxy\fR \fIproxy\fR
HTTP proxy server, http://username@password@host:port/

.SS "Query type:"
.TP
\fB\-q\fR|\fB\-\-queryType\fR \fItype\fR
query type (default: \fBlocation\fR), choose from
.nf
 \fB[location|coord|user|owner|country|state|keyword|wid|guid|bookmark]\fR
.fi
.PP
Use \fBcoord\fR if you already have coordinates.
Coordinates may be given in the usual representations:
  dd.ddddd
  dd mm.mmm
  dd mm ss[.sss]
 \- possibly containing a degree symbol and a prefixed sign or letter (NSEW).
.PP
Both latitude and longitude must use the same representation.
.PP
\fBlocation\fR will use the OpenStreetMap Nominatim API
(Data © OpenStreetMap contributors, ODbL 1.0, https://osm.org/copyright)
to translate into coordinates.
This should also work with zip codes.
.PP
\fBcountry\fR and \fBstate\fR queries by command-line require a \fInumerical id\fR which the TUI can tell you.
Do not confuse the index numbers provided with the sorted lists with the country or state \fIid\fR!
.PP
\fBbookmark\fR allows to parse bookmark lists, given by GUID (old) or BMXXXXX tag.\fI(Not working!)\fR

.SS "Output control:"
.TP
\fB\-o\fR|\fB\-\-output\fR \fIfilename\fR
(first) output file name (default: created from query argument(s) and options)
.PP
In case of multiple output formats, subsequent file names are derived from this one
by substituting filename extensions.
.TP
\fB\-x\fR|\fB\-\-format\fR \fIformat\fR  \fB(MULTI)\fR
output format type(s) (default: gpx)
.PP
Any entry can be of the form format=extension in which case the default extension
specified in the template will be overwritten. For the first output file, a specified
output file name takes precedence.
.PP
See the \fBOUTPUT FORMATS\fR section below for the list of supported formats.
.TP
\fB\-w\fR|\fB\-\-waypointLength\fR \fIlength\fR
set EasyName waypoint id length. (default: 0=use WID)
.PP
.I Note:
negative values are no longer allowed.
.TP
\fB\-l\fR|\fB\-\-logCount\fR \fIcount\fR
limit number of log entries (default: 10)
.PP
Currently, there seems to be a maximum of 99 imposed by GC's interface;
specifying 100 or more will result in only \fB10\fR logs to be returned.

.SS "Limit queries:"
.TP
\fB\-y\fR|\fB\-\-distanceMax\fR|\fB\-\-radius\fR \fI0.01\-500[km]\fR
distance maximum in miles or km (default: 10mi)
.PP
Applies to \fBlocation\fR and \fBcoord\fR queries only.
.TP
\fB\-L\fR|\fB\-\-limitSearchPages\fR \fIcount\fR
limit number of search pages (default: 0=unlimited)

.SS "File caching:"
.TP
\fB\-Y\fR|\fB\-\-noCacheDescriptions\fR
do not fetch nor parse cache descriptions, search only
.PP
This will reduce the amount of server requests, but provides no means
to determine (and use for filtering) cache coordinates, dates, hints, attributes, or descriptions.
.TP
\fB\-Z\fR|\fB\-\-preserveCache\fR|\fB\-\-keepOld\fR
do not overwrite existing cache description files in file cache

.SS "Filtering options:"
.TP
\fB\-c\fR|\fB\-\-cacheType\fR|\fB\-\-type\fR \fItype\fR  \fB(MULTI)\fR
set cache type(s), select from
 \fB[traditional|multicache|virtual|letterbox|\fR
 \fI event+|\fR
  \fB event|cito|mega[event]|giga[event]|\fR
  \fB communceleb|gchqceleb|block|\fR
 \fI unknown+|\fR
  \fB unknown|\fR
  \fB gchq|ape|\fR
 \fB webcam|earthcache|gps|wherigo]\fR
.PP
\fBgchq\fR (ex \fBgshq\fR) denotes a single cache located at Geocaching Headquarters.
.PP
\fBgchqceleb\fR (ex \fBlfceleb\fR, \fBhqceleb\fR) is used for \fIGeocaching HQ Celebration\fR (formerly
\fIGroundspeak Lost and Found Celebration\fR, renamed in June 2019).
.PP
\fBcommunceleb\fR (ex \fBlost+found\fR, \fBcommceleb\fR) denotes a \fICommunity Celebration Event\fR (called
\fILost and Found Event Cache\fR until June 2019).
.PP
\fBlocationlass\fR (aka \fBreverse\fR) caches are no longer supported it seems (May 2023).
.PP
.I Caveat:
\fBMultiple cache types\fR will result in a \fIfull search\fR and subsequent filtering!
If \fBonly one type\fR is selected, search will be sped up considerably
by reducing the number of queries sent to the server.
.PP
.I Another caveat:
Some of the renamed (but also less abundant) cache types need more testing.
There are indications that \fIevent+\fR (\fIall_event\fR in the TUI) and \fIunknown+\fR (\fIall_unknown\fR)
queries may \fIreturn nonsense\fR when more than one page is retrieved, this needs to be investigated.
.PP
By suffixing one or more cacheType(s) with a minus sign (dash) "\-",
you may invert the filter,
i.e. \fBunknown\-\fR will return only non-mystery caches.
(This doesn't work with \fIall_*\fR / \fI*+\fR!)
.PP
Inverse filters are applied before, and therefore supersede, forward filters!
(This means, \fBtype:type\-\fR will exclude \fBtype\fR.)
.PP
\fBevent\fR and \fBunknown\fR do not include "special" types.
To search for "all event" (including cito, mega, and giga, and some 
rare other events) or "all unknown" (including GroundSpeak HQ) types,
use
\fBall_event\fR (\fBevent+\fR), or \fBall_unknown\fR (\fBunknown+\fR) respectively,
can be used \fBas the only cache type\fR (otherwise,
filtering won't work - you've been warned).
Also, inverted filtering for these types does \fBnot\fR work!
These types may not be supported by the TUI.
.TP
\fB\-d\fR|\fB\-\-difficultyMin\fR|\fB\-\-minDiff\fR \fI1.0\-5.0\fR
set minimum difficulty
.TP
\fB\-D\fR|\fB\-\-difficultyMax\fR|\fB\-\-maxDiff\fR \fI1.0\-5.0\fR
set maximum difficulty
.TP
\fB\-t\fR|\fB\-\-terrainMin\fR|\fB\-\-minTerrain\fR \fI1.0\-5.0\fR
set minimum terrain
.TP
\fB\-T\fR|\fB\-\-terrainMax\fR|\fB\-\-maxTerrain\fR \fI1.0\-5.0\fR
set maximum terrain
.TP
\fB\-s\fR|\fB\-\-sizeMin\fR|\fB\-\-minSize\fR \fIsize\fR
set minimum cache size, select from
 \fB[virtual|not_chosen|other|micro|small|regular|large]\fR
 (\fBnot_chosen\fR is equivalent to \fBvirtual\fR)
.TP
\fB\-S\fR|\fB\-\-sizeMax\fR|\fB\-\-maxSize\fR \fIsize\fR
set maximum cache size
.TP
\fB\-g\fR|\fB\-\-favFactorMin\fR|\fB\-minFav\fR \fI0.0\-5.0\fR
set minimum fav factor
.TP
\fB\-G\fR|\fB\-\-favFactorMax\fR|\fB\-maxFav\fR \fI0.0\-5.0\fR
set maximum fav factor
.TP
\fB\-k\fR|\fB\-\-titleKeyword\fR \fIkeyword\fR  \fB(MULTI)\fR
title keyword search, exclude if prefixed with \fB!\fR
.TP
\fB\-K\fR|\fB\-\-descKeyword \fR \fIkeyword\fR  \fB(MULTI)\fR
description keyword search (slow), exclude if prefixed with \fB!\fR
.TP
\fB\-i\fR|\fB\-\-ownerInclude\fR|\fB\-\-by\fR \fIusername\fR  \fB(MULTI)\fR
select caches owned by this person
.TP
\fB\-I\fR|\fB\-\-ownerExclude\fR|\fB\-\-notby\fR \fIusername\fR  \fB(MULTI)\fR \fB(USERFILE)\fR
exclude caches owned by this person
.TP
\fB\-e\fR|\fB\-\-userInclude\fR|\fB\-\-doneBy\fR \fIusername\fR  \fB(MULTI)\fR
select caches found by this person
.TP
\fB\-E\fR|\fB\-\-userExclude\fR|\fB\-\-notdoneBy\fR \fIusername\fR  \fB(MULTI)\fR \fB(USERFILE)\fR
exclude caches found by this person
.TP
\fB\-j\fR|\fB\-\-placeDateInclude\fR|\fB\-\-since\fR \fIX\fR
select caches placed in the last \fIX\fR days
.TP
\fB\-J\fR|\fB\-\-placeDateExclude\fR|\fB\-\-until\fR \fIX\fR
exclude caches placed in the last \fIX\fR days
.TP
\fB\-r\fR|\fB\-\-foundDateInclude\fR \fIX\fR
select caches found in the last \fIX\fR days
.TP
\fB\-R\fR|\fB\-\-foundDateExclude\fR \fIX\fR
exclude caches found in the last \fIX\fR days
.TP
\fB\-a\fR|\fB\-\-attributeInclude\fR \fIid[\-]\fR  \fB(MULTI)\fR
select caches with attribute ID \fIid\fR set to "yes", or to "no" if \fB\-\fR suffix
.TP
\fB\-A\fR|\fB\-\-attributeExclude\fR \fIid[\-]\fR  \fB(MULTI)\fR
exclude caches with attribute ID \fIid\fR set to "yes", or to "no" if \fB\-\fR suffix
.TP
\fB\-z\fR|\fB\-\-includeDisabled\fR|\fB\-\-bad\fR
include disabled caches
.I Note:
For \fBevent\fR caches of any type, event dates in the past will result in the cache
being disabled (even if the "disabled" flag hasn't been set yet) -
but only after reading the individual cache page.
.TP
\fB\-\-includeArchived\fR|\fB\-\-gone\fR
include archived caches
.PP
This will only have an effect for queries which return archived caches as well:
\fBuser\fR and \fBowner\fR queries. Normally, archived caches are suppressed.
.TP
\fB\-n\fR|\fB\-\-notFound\fR|\fB\-\-virgin\fR
select only caches not found yet
.TP
\fB\-N\fR|\fB\-\-notFoundByMe\fR|\fB\-\-notme\fR
select only caches not yet found by login user
.TP
\fB\-b\fR|\fB\-\-travelBug\fR|\fB\-\-trackable\fR
select only caches with travelbugs/trackables
.TP
\fB\-O\fR|\fB\-\-noPMO\fR|\fB\-\-nopmo\fR
exclude Premium Member Only caches
.TP
\fB\-Q\fR|\fB\-\-onlyPMO\fR|\fB\-\-pmo\fR
select only Premium Member Only caches (will not work for some query types!)
.PP
.I Note:
\fB\-O\fR and \fB\-Q\fR are mutually exclusive!

.SS "Lat/lon grid limits:"
The following 4 options have no one-letter version, and are used for limiting the search area.
Note that this filter is applied \fBafter\fR fetching all cache details (as coordinates aren't available before).
Use numeric values only!
.\" (TBD: same representations as in a \fBcoord\fR search)
.TP
\fB\-\-minLongitude\fR|\fB\-\-longMin\fR \fI...\fR
set minimum longitude (West filter limit)
.TP
\fB\-\-maxLongitude\fR|\fB\-\-longMax\fR \fI...\fR
set maximum longitude (East filter limit)
.TP
\fB\-\-minLatitude\fR|\fB\-\-latMin\fR \fI...\fR
set minimum latitude (South filter limit)
.TP
\fB\-\-maxLatitude\fR|\fB\-\-latMax\fR \fI...\fR
set maximum latitude (North filter limit)

.SS "Additional options:"
.TP
\fB\-m\fR|\fB\-\-delimiter\fR \fIdelimiter(s)\fR
delimiter(s) to be used for \fB(MULTI)\fR input, default "\fB|:\fR"
.PP
The TUI uses "\fB|\fR".
You may try "\fB^\fR" to avoid delimiters that have to be "escaped" ("quoted").
.TP
\fB\-V\fR|\fB\-\-version\fR
show version information only, then exit
.TP
\fB\-C\fR|\fB\-\-clearCache\fR|\fB\-\-cleanup\fR
selectively clear browser cache, then exit
.PP
You are advised to remove the outdated remnants of old queries every now and then.
Cache descriptions will never be removed!
.TP
\fB\-M\fR|\fB\-\-myLogs\fR|\fB\-\-getlogs\fR
retrieve "my logs" page containing links to all (cache) logs, and store in cache
.TP
\fB\-W\fR|\fB\-\-myTrackables\fR|\fB\-\-gettrks\fR
retrieve "my trackable logs" page, and store in cache
.PP
Options \fB\-V\fR, \fB\-C\fR, \fB\-M\fR and \fB\-W\fR may be used without a real query.
.TP
\fB\-X\fR|\fB\-\-disableEarlyFilter\fR
emergency switch to disable early (cache\-list based) filtering by difficulty/terrain/size/PMO
.PP
This may be required should the representation of those values change again,
after 2010 and 2012 - or if you want to apply filters to the result of an exotic
query (like \fBbookmark\fR).
Normally you don't want to use this!
.TP
\fB\-U\fR|\fB\-\-unbufferedOutput\fR
switch output to unbuffered (useful for wrappers)

.SS "Options yet experimental and/or undocumented:"
.I Caveat: Here be dragons.

These are experimental additions which need testing and documentation.
Volunteers wanted!
.TP
\fB\-\-conditionWP\fR \fI condition \fR
conditionally output caches, similar to the setting of the same name in templates (e.g. \fBwherigo\fR)
Example, to output only if this isn't a member-only mystery cache:

 \fB\-\-conditionWP="(not( (<%wp.membersonly%>) and
                        (\\"<%wp.type%>\\"==\\"unknown\\") ))"\fR

To select only caches in a state (region) after a radius search around a location
or coord:

 \fB\-\-conditionWP="('<%wp.state%>'=='Berlin')"\fR

Use plenty of parentheses! Conditions which result in syntax errors are ignored
(so you may sort things out later, without losing your search result completely).

 \fIRecommendation: Add condition to a template instead.\fR
 \fISee \fR\fBtwitter.tm\fR\fI and \fR\fBwherigo.tm\fR\fI for examples.\fR

.SH "SEARCH ARGUMENT"

\fIsearch\fR can be of the \fB(MULTI)\fR type.
This, for example, allows you to combine multiple circular search spots
into a single search - the query results will be merged.
(Be warned that some output fields, like distances and directions, may become ambiguous!)

.SH "SPECIAL CASES"

.SS "Minus signs:"
If your \fIsearch\fR item(s)
(according to the \fBqueryType\fR)
start with a dash (minus sign),
it has to be "hidden" from the option parser.
This, in Unix tradition, is done by inserting a "double dash" \fB\-\-\fR
between the last option and the search argument(s).

.SS "Special characters"
Characters like \fB!\fR and \fB|\fR may have to be "escaped" from the shell,
usually by enclosing them, or the whole string, in quotes.

.SS "Non-ASCII characters in names:"
If \fBuser\fR or \fBowner\fR names contain special (non-ASCII) characters,
and you are using Windows, you may not be able to login or run a "user" query.
In those cases, you'll have to pre-encode those characters.
.PP
.B http://www.utf8\-chartable.de/unicode\-utf8\-table.pl?number=1024
will help you to look up the proper UTF\-8 codes.
Prefix each two-digit hex value with a percent sign:
.PP
For example
.B (capital_letter_O_with_diaeresis)lscheich
will become
.B %c3%96lscheich
\- the TUI may show strange characters, don't worry.

.SS "Colons in file names:"
If you're planning to use colons (e.g. for \fB(USERFILE)\fR) on the command line,
you may have a look at the \fB\-m\fR option which allows you to redefine the
delimiter set.

.SH "TEXT USER INTERFACE and CONFIG.YAML"

The text user interface (TUI) stores several items in \fBconfig.yaml\fR in
the configuration directory. \fBThis includes username and password.\fR
.PP
Upon invocation of the TUI (by omission of command-line parameters), this file
is used to fill in the various fields in the TUI mask. Before performing the
actual search, the values are written back.
.PP
If \fB\-\-username\fR \fIor\fR \fB\-\-password\fR are not given on the
command-line, this file is read as a last resort to set \fIboth\fR values.
In case of failure, an error is thrown.


.SH "ENVIRONMENT"

.SS "GEO_DIR"
.PP
If set, GeoToad will put its file cache in this directory.
.PP
If not the file cache is placed in \fB~/.geotoad/\fR .
.PP
Note that GEO_DIR should not point to a world-writable directory such as /tmp
(see the discussion of \fBconfig.yaml\fR above).

.SS "LANG"
To properly handle special characters (which are not in the ASCII character
set, such as umlauts, etc.) we recommend to set
.B LANG
to
.B en_US.UTF\-8
or similar.
.PP
The syntax depends on the shell you're using:
.B setenv LANG en_US.UTF\-8
for C-shell derivatives (csh, tcsh)
.B LANG=en_US.UTF\-8; export LANG
for Bourne and Korn shell (sh, ksh)
.B export LANG=en_US.UTF\-8
for Bourne Again shell and derivatives (bash, dash).

.SS "GEO_HOME_LAT, GEO_HOME_LON"
.PP
If set (numerical values only!), distances are computed (using Haversine) relative to that location.
.PP
If both values are set to zero, the home location registered at GC will be used.
.PP
If there's no setting, the distances reported by the search (or \fBN/A\fR) will be used.
\fICaveat:\fR This will result in less useful values when combining multiple search locations/coordinates!

.SS "SSL_CERT_FILE"
.PP
Windows users who want to use SSL peer verification need a CA-certificate bundle.
This seems to be included with all modern Linux distributions, but
since this usually doesn't come with Windows nor Ruby, it is recommended to use
the \fBcontrib\\CA_Bundle\\ca\-bundle.crt\fR file, and declare that as \fBSSL_CERT_FILE\fR
before starting \fBruby geotoad.rb\fR, e.g.:
.PP
.B set SSL_CERT_FILE=C:\\\\Programs\\\\GeoToad\\\\contrib\\\\CA_Bundle\\\\ca\-bundle.crt
.PP
You may want to check \fBhttps://gist.github.com/fnichol/867550\fR as well, for
how to make this change permanent.
.\" .PP
.\" The Windows_Installer tries to add environment settings,
.\" both system-wide and for the installing user,
.\" where the former intentionally needs renaming, and both may fail.

.SH "OUTPUT FORMATS"

.\" set indentation to "none", use fixed-width font for format list
.PP 0
.ft CW
 cachemate(=)  cetus(+)      csv           delorme        delorme\-nourl 
.ft CW
 dna(+)        easygps       gclist        gcvisits(%)    gpsdrive      
.ft CW
 gpsman(+)     gpspilot(+)   gpspoint      gpspoint2(+)   gpsutil(+)    
.ft CW
 gpx           gpx\-gsak      gpx\-nuvi      gpx\-pa         gpx\-wpts      
.ft CW
 holux(+)      html          kml(+)        list           magnav(+)     
.ft CW
 mapsend(+)    mxf           myfindgpx     myfindlist     ozi           
.ft CW
 pcx(+)        poi\-nuvi(+)   psp(+)        sms            sms2          
.ft CW
 tab           text          tiger         tmpro(+)       tpg(+)        
.ft CW
 vcf           wherigo       wp2guid       xmap(+)        yaml          
.ft CW
 yourfindgpx   yourfindlist  
.ft CW
  (+) requires gpsbabel
  (=) requires cmconvert
  (%) requires iconv in PATH
.\" back to normal font
.ft P

.SH "RETURN CODES"

.B 0
normal termination
.PP
.B 1
any general error not covered by higher return codes, also
unsupported Ruby or SSL versions, check your setup
.PP
.B 2
error in input parameters, run \fBgeotoad --help\fR for usage
.PP
.B 3
query page progress error \fB(*)\fR
.PP
.B 4
details page parsing error (possibly corrupt cache page)
.PP
.B 7
communication (network) problem \fB(*)\fR
.PP
.B 8
cookies lost or got out of sync \fB(*)\fR
.PP
.B 9
authentication problem, check login data, then \fB(*)\fR
.PP
.B 42
something has happened that wasn't considered in the code, provide feedback
.PP
.I Caveat:
\fB(*)\fR re-running may succeed,
 but require deletion (or waiting for expiration) of cached files before

.SH "KNOWN LIMITATIONS"
.SS "Release cycle, OS support:"
.PP
.B  geotoad
is released every now and then ("it's ready when it's ready") as a tarball,
and derived from that as Debian (/Ubuntu) and Mac OS X packages.
.\"  and Windows Installer.
A Windows Installer had been provided for older versions, but can no longer
be built for technical reasons.
.PP
.B  geotoad
development had been started in a Mac OS X environment, and has been moved
to (Debian) Linux later.
All testing is currently done in a Debian Linux context, on multiple
hardware architectures, including armel and i386.
Mac OS X and Windows packaging take/took place on a foreign (or virtual)
machine, testing is close to impossible, but feedback is appreciated.
.PP
Starting with Ruby 2.1, Windows XP is no longer supported.
While 3.24.0 was the last release that came with (now obsolete) Ruby 2.0
pre-packaged, using GeoToad in a Windows environment is still possible:
You will have to install Ruby yourself, and use the tarball.
.PP
32-bit support will be preserved as long as possible.
.PP
Ruby versions before 1.9.3 cannot be used;
\fBgeotoad\fR will throw an error and exit.
.PP
Ruby versions before 3.1 are deprecated and discouraged.
Since Linux distributions may continue patching end-of-life versions
you will just get a warning - don't complain if something fails afterwards.
.SS "Limitations by design:"
.PP
Almost all searches provide enough information for the second stage that
interprets cache-specific information.
.PP
.B  geotoad
parses \fIprintable\fR pages (cdpf format).
This has been a fundamental design decision - cdpf pages have been mostly
unharmed by website redesigns, but those pages don't contain owner IDs,
trackable IDs, etc. 
Also the "cache by" string can contain arbitrary information. It's therefore
not reliable to deduce the real owner. (Owner searches aren't affected by this.)
.PP
It is not possible to search for more than one cache type if \fBevent+\fR
or \fBunknown+\fR are involved.
.PP
Early filtering by attributes like D, T, size, or PMO may fail if this
information hasn't been provided by the initial query. This is true for
bookmark list processing, for example. Under such circumstances,
use the \-\-disableEarlyFilter (\-X) option to avoid disappointment.
.SS "Limitations imposed by GroundSpeak:"
.PP
The GC webpages can be displayed in more than 20 languages.
While relative times (like "today", "yesterday" or "5 days ago" can be
parsed with sufficient precision, the multitude of date representations
causes a few ambiguities: There's no safe way to decide whether "05/06/2007"
was in May or June. Using the current user preferences may provide a clue
but may fail for saved cache descriptions that haven't been updated (e.g.
because the cache was converted to PMO). Also month-name abbreviations
haven't been included in the program code. This means that you cannot use
a foreign language and abbreviated month names in a reliable manner.
.PP
English language, and ISO date style ("2007\-06\-05" for 5th of June) are
considered safe. A warning is shown if your settings are different.
.SS "Little-tested features:"
.PP
The TUI doesn't get tested very much - the command line is still a lot more
powerful, and there are a lot of options which aren't supported by the TUI.
.PP
\fBCaveat: Starting with version 3.34.0, TUI items have been renumbered!\fR
.PP
Bookmark mode will parse list pages which are very sparse - 
they contain no coordinates -,
then proceed directly to cdpf pages matching the list of \fIwid\fRs obtained.
The \fIcdpf.aspx\fR (printable cache) pages may not be able to provide the missing
values.
.PP
.B  geotoad
is being tested with English only. While there is some support for other
languages as well, parsing may fail in some extreme situations (for example,
result pages may have a slightly different structure for Dutch).
None of the authors speaks or reads Korean, Greek or Chinese, thus 
patterns have been derived from analyzing result pages in multiple languages.
.SS "Wrappers:"
The "progress" output format may change (and actually did before 3.24.0).
If you are using a wrapper, that may need some adjustment.
.SS "Output formats:"
.B  geotoad
comes with a limited set of pre-defined output templates, but you are free
to create your own ones. User-specific template files can be kept in a
\fBtemplates\fR subdirectory of the configuration tree (\fBGEO_DIR\fR).
It is recommended to start with a known template from the distribution, then
modify it until the desired behaviour has been reached.
.PP
Templates of the same name will be superseded by the user-defined variants.
Make sure to test them for syntax errors (use \fB ruby \-wc\fR) - they are valid
Ruby source files!
.PP
Some output formats require external programs, like \fBgpsbabel\fR or \fBcmconvert\fR.
.PP
A template file maps (fixed) names of output file sections to string expressions
which are evaluated when creating the output file.
In general, a \fB<%type.value%>\fR in such a string gets replaced by the corresponding
\fIvalue\fR calculated in \fBlib/output.rb\fR's \fBcreateExtraVariablesForWid()\fR function,
converted to the desired \fItype\fR.
Some cases (e.g., \fBconditionWP\fR for conditional output) will result in crude syntax.

.\".SS "PMO for Basic Members:"
.\"There are a couple of unofficial patches to make
.\".B  geotoad
.\"ready for Premium Member caches, also for Basic Members.
.\"Those will not be made public now.

.SH "RESOURCES"
.PP
.B  geotoad
is currently hosted on GitHub
.ft CW
https://github.com/steve8x8/geotoad/
.ft P

.SH "EXAMPLES"
.PP
\fINote:\fR Some of these examples may still no longer work as shown.
Please help to fix this; see Issue 284.
.PP
Additional examples are welcome!

.SS "Getting started:"
.TP
.B  geotoad
invokes the text user interface
.TP
.B  geotoad \-u user \-p password 27513
You've just made a file named gt_27513.gpx containing all the geocaches
nearby the zipcode 27513 (Cary, NC - with a maximum distance of 10 miles)
suitable to be read by almost every GPSr device.
.PP
Why do we need a username and password? In October of 2004, Geocaching.com
began to require a login in order to see the coordinates of a geocache.
.PP
(Please note: Put quotes around your username if it has any spaces in it.)

.SS "Going into details:"
Here are some more complex examples that you can work with:
.TP
.B  geotoad \-u user \-p password \-y 5 \-q coord "N56 44.392, E015 52.780"
searches for caches within 5 miles of the above coordinates
.TP
.B  geotoad \-u user \-p password 27513:27502:33434
performs a multiple search, and combines the results into a single output.
.PP
You can combine searches with a delimiter (default is "\fB|\fR", or "\fB:\fR" - except TUI).
This works for all search types (and other \fB(MULTI)\fR options).
.TP
.B  geotoad \-u user \-p password \-x text \-o nc.txt \-n \-q state 34
Outputs a text file with all of the caches in US state North Carolina that are
virgins (have never been found).
.PP
Please note that for state and country command-line queries, the numerical id has to be used.
You may use the TUI to determine the country or state id number.
.PP
Warning: Querying a whole state or country can be dangerous and may harm your account!
For example, NC has (as of Oct 2013) more than 24k active caches.
.PP
You may want to limit the number of search pages parsed (e.g. using \fB\-L 10\fR),
as country and state searches return caches in reverse chronological order
(newest ones first).
.TP
.B  geotoad \-u user \-p password \-x html \-o palestine.html \-q country 276
Get a HTML representation of all caches in Palestine. (Oct 2013: 7, one of them unfound)
.TP
.B  geotoad ... \-t 2.5 \-E "helixblue:Sallad" \-x gpx \-o charlotte.gpx 28272
Get caches in the 10-mile zone of zipcode 28272, with a terrain score of 2.5 or higher, 
which users helixblue and Sallad have not visited.
Outputs a GPX format file, which is usable by most GPSr's and other devices.
.TP
.B  geotoad ... \-t 2.5 \-E anyname=/path/to/file \-x gpx \-o charlotte.gpx 28272
As before, but read a list of GCxxxxx cache IDs from a file instead of querying the server
for found caches.
.TP
.B  geotoad ... \-b \-K 'stream|creek|lake|river|ocean' \-x html \-o watery.html \-q state 15
Gets every cache in Indiana state with trackables that matches those water keywords,
and makes a pretty HTML file out of it.
.TP
.B  geotoad ... \-x gpx \-o mylocal.gpx \-z \-y 1.75 \-T 4 \-q coord "N 51 23.456 E 012 34.567"
Create a GPX file with all caches around the given location,
max. 1.75 miles away, terrain rating below or equal 4, including disabled ones.
.TP
.B  geotoad ... \-m '^+|' \-o output.gpx \-x "gpx+list|html" \-y 2km \-q coord "52.25,6.075^53.1,\-7.2"
Perform a search around two travel stops with a 2 kilometre radius, 
create three files output.gpx, output.lst, output.html combining the results.
.PP
(Note the usage of the \fB\-m\fR option to modify the set of delimiters.
As the \fB|\fR character has a special meaning, it must be "quoted".)
.TP
.B  geotoad ... \-c multicache \-a 6 \-A 57 \-o family.gpx \-x gpx:list \-y 25km \-q coord "52.25,6.075"
Prepare for a Sunday afternoon walk, and find all multi-caches around
which pretend to be "Kid friendly" (attribute 6) and shorter than 10km (attribute 57).
.TP
.B  geotoad ... ... (as above) \-\-minLat 52.10 \-\-maxLat 52.40 \-q coord "52.25,6.075"
This will further reduce the number of caches, by dropping all outside a "latitude zone".
.PP
You may also define Eastern and Western limits, e.g. \fB\-\-minLon 6.00 \-\-maxLon 6.20\fR.
.PP
Note that this is a \fBfilter\fR applied after querying the server.
.TP
.B  geotoad ... \-z \-q owner \-\- \-aBcDe\-
Find all caches created by one owner, even the disabled or archived ones.
.PP
Note that here the argument (owner name) has to be separated by \fB\-\-\fR from the rest of the command line.

.SH "AUTHOR"

Thomas Stromberg and The GeoToad Project