========================================================================== GeoToad 3.34.2 by Thomas Stromberg and The GeoToad Project (c) 2002 - 2024

---

Table of Contents:

• About GeoToad
• System Requirements
• Getting Started
• Command-Line Syntax
• Command-Line Examples

---

About GeoToad

GeoToad is an open-source query tool to query the geocaching.com website. It supports exporting your results into a dozen or more formats such as GPX (also variants suited for GSAK, or your road nav device) and HTML.

---

System Requirements

• Windows
  • Windows 98 or Higher with
    • a sufficiently recent Ruby version
    • a SSL certificate chain required for HTTPS (also provided with GeoToad)
• Mac OS
  • Mac OS X 10.4 or Higher
• Other Operating Systems
  • You may need to install Ruby before running GeoToad.
    • RedHat/Fedora Linux: built-in
    • Debian/Ubuntu Linux: apt-get install ruby libopenssl-ruby, then dpkg -i geotoad_*.deb
    • FreeBSD: pkg_add -r ruby

Optionally, if you have gpsbabel (=> http://www.gpsbabel.org/) GeoToad can output to over a dozen additional GPS formats.

---

Getting Started

The easiest way to get started with GeoToad is to use the "text user interface" (TUI). Simply double click on the GeoToad program icon, or from a command prompt run "geotoad". On UNIX, you may have to run "./geotoad.rb". On first invocation, if you confirm the request to open the TUI, you will see a screen that looks like this:

=============================================================================== ::: // GeoToad 3.34.2 Text User Interface // :::

(1) search type [ location] | (2) distance maximum (km) [ 0.01] (3) location [schloss finsterwalde ] --------------------- page 1: basic cache specifications ---------------------- (11) cache type [ any] (12) cache size [ any - any] | (13) no Premium Member Only caches [ ] (14) difficulty [1.0 - 5.0] | (15) terrain [1.0 - 5.0] (16) title keyword [ ] | (17) descript. keyword [ ] (18) include disabled caches [ ] | (19) include archived caches [ ] ----------------------------- search limits etc. ------------------------------ (31) limit search to pages [ ] | (32) max log entries [ ] (33) skip cache descriptions [ ] | ---------------------------- output specifications ---------------------------- (41) EasyName WP length [ 0] | (42) filename [(automatic) ] (43) output format [list ] | (0) GC.com login [Erd_Kroete ] (44) output directory [. ]

** Verbose (debug) mode disabled, "v" to change -- Enter number, "p" for page 2, "s" to start, "R" to reset, "X" to exit -->

At this point, follow the prompt and change items by typing the number and pressing <ENTER> afterwards. You will need to enter your login and some basic search criteria. Note that changing the "search type" (1) will change the label of (3), etc., and some settings may become meaningless and hidden (like distance (2) for searches without a center point).

After entering the basic cache specs, you may switch to page 2 for more selection criteria, by selecting "p". The screen will change to this:

=============================================================================== ::: // GeoToad 3.34.2 Text User Interface // :::

(1) search type [ location] | (2) distance maximum (km) [ 0.01] (3) location [schloss finsterwalde ] ---------------------- page 2: further cache selections ----------------------- (21) caches not found by me [ ] | (22) caches not found by anyone [ ] (23) found by [ ] | (24) owner is [ ] (25) not found by [ ] | (26) owner isn't [ ] (27) cache age (days) [ 0 - any] | (28) last found (days ago) [ 0 - any] (29) caches with trackables only [ ] | (35) fav factor [0.0 - 5.0] ----------------------------- search limits etc. ------------------------------ (31) limit search to pages [ ] | (32) max log entries [ ] (33) skip cache descriptions [ ] | ---------------------------- output specifications ---------------------------- (41) EasyName WP length [ 0] | (42) filename [(automatic) ] (43) output format [list ] | (0) GC.com login [Erd_Kroete ] (44) output directory [. ]

** Verbose (debug) mode disabled, "v" to change -- Enter number, "p" for page 1, "s" to start, "R" to reset, "X" to exit -->

Once you have entered in all of your information, press "s" and then <ENTER> to begin your search. GeoToad will report the options for the current run, and save them for future runs.

Caveat: Item numbering has been changed starting with version 3.34.0!

---

Command-Line Syntax

Sometimes people prefer to use the command-line switches instead of the text user interface. This comes especially in handy when you wish to automate it so that every morning your iPod or GPS has the freshest list of geocaches that have not been found in your area.

If you go to the command line, and run geotoad -h, you will get a screen with a list of of options such as the following:

syntax: geotoad [options] search:search2:search3

-u <username> Geocaching.com username, required for coordinates -p <password> Geocaching.com password, required for coordinates -m [delimiters] set delimiter(s) (default "|:") for multiple selections -o [filename] output file name (automatic otherwise) -x [format] output format type, see list below (default: gpx) -q [location|coord|user|owner|country|state|keyword|wid|guid|bookmark] query type (default: location) -d/-D [1.0-5.0] difficulty minimum/maximum -t/-T [1.0-5.0] terrain minimum/maximum -g/-G [0.0-5.0] fav factor minimum/maximum -y [0.01-500] distance maximum, in miles, or suffixed "km" (10) -k [keyword] title keyword(s) search -K [keyword] desc keyword(s) search (slow!) -i/-I [username] include/exclude caches owned by this person -e/-E [username] include/exclude caches found by this person -s/-S [virtual|not_chosen|other|micro|small|regular|large] min/max size of the cache -c [traditional|multicache|unknown|virtual|event|...] type(s) of cache -j/-J [# days] include/exclude caches placed in the last X days -r/-R [# days] include/exclude caches found in the last X days -a/-A [attribute] include/exclude caches with attributes set -z include disabled caches -n only include not found caches (virgins) -N only caches not yet found by login user -b only include caches with travelbugs -w [length] set EasyName waypoint id length. (0=use WID) -L [count] limit number of search pages (0=unlimited) -l [count] limit number of log entries (default: 10) -Y do not fetch cache descriptions, search only -Z don't overwrite existing cache descriptions -O exclude Premium Member Only caches -Q select only Premium Member Only caches -P HTTP proxy server, http://username:pass@host:port/ -M download my cache logs (/my/logs.aspx?s=1) -W download my trackable logs (/my/logs.aspx?s=2) -X emergency switch: disable early filtering -C selectively clear local browser cache -U use unbuffered output -V show version, then exit

::: OUTPUT FORMATS: cachemate(=) cetus(+) csv delorme delorme-nourl dna(+) easygps gclist gcvisits(%) gpsdrive
gpsman(+) gpspilot(+) gpspoint gpspoint2(+) gpsutil(+)
gpx gpx-gsak gpx-nuvi gpx-pa gpx-wpts
holux(+) html kml(+) list magnav(+)
mapsend(+) mxf myfindgpx myfindlist ozi
pcx(+) poi-nuvi(+) psp(+) sms sms2
tab text tiger tmpro(+) tpg(+)
vcf wherigo wp2guid xmap(+) yourfindgpx
yourfindlist (+) requires gpsbabel (=) requires cmconvert (%) requires iconv in PATH

::: EXAMPLES: geotoad.rb -u helixblue -p password 27502 find zipcode 27502 (Apex, NC 27502, USA), search 10mi around, write gpx geotoad.rb -u john -p password -c unknown -d 3 -x csv -o NC.csv -q state 34 will find all mystery caches with difficulty >= 3 in all of North Carolina (Be careful: NC has more that 24k active caches!) geotoad.rb -u ... -p ... -z -Y -H -c cito -x list -o cito.list -q country 11 creates a list (with dates, but no coordinates) of all CITO events in the UK for more examples - and options explanations - see manual page and README

---

Comm