search

steve8x8 / geotoad

Geocaching query tool written in Ruby
https://buymeacoffee.com/steve8x8
Other
28 stars 8 forks source link

readme

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

Table of Contents:

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

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

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] -u Geocaching.com username, required for coordinates -p 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 --------------------- Command-Line Examples --------------------- You need to get to a command-line (DOS, cmd.exe, UNIX shell), and go into the directory you extracted geotoad into. Then you should be able to type something simple like: - geotoad.rb -u user -p password 35466 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. If that does not work, try: - ruby geotoad.rb -u user -p password 35466 You've just made a file named gt_35466-y10.gpx containing all the geocaches nearby the zipcode 35466 (Gordo, Alabama) suitable to be read by a Garmin device. Here are some more complex examples that you can work with: - geotoad.rb -u user -p password -q coord "N56 44.392, E015 52.780" -y 3 Search for caches within 3 miles of the above coordinates - geotoad.rb -u user -p password -q coord "56 44.392 15 52.780" -y 5km Search for caches within 5 kilometres. - geotoad.rb -u user -p password -x gpx -o threezipcodes.gpx 35466:99722:99788 You can combine searches with the : delimiter. This works for all types, though it's most often used with coordinate searches. - geotoad.rb -u user -p password -x text -o nc.txt -n -q state 34 Outputs a text file with all of the caches in North Carolina (state ID: 34) that are virgins (have never been found). GeoToad's TUI can assist you to find the state ID: select search type "state", then enter a pattern for country/state in a form like "states/no.*caro". Pick the numeric ID for command line queries. (Should your pattern be ambiguous, GeoToad will let you select from a list.) - geotoad.rb -u user -p password -t 2.5 -x gpx -E "helixblue:Sallad" -o charlotte.gpx 28272 Gets every cache in the 10-mile radius of zipcode 28272, with a terrain score of 2.5 or higher, and that helixblue and Sallad have not visited. Outputs a GPX format file, which is usable by many GPSr's and other devices. Please note: Put quotes around your username if it has any spaces in it. Another note: This kind of query will put a high load on GroundSpeak's servers and may change your account status to "banned". Be careful. - geotoad.rb -u user -p password -x html -b -K 'stream|creek|lake|river|ocean' -o watery.html -q country 72 Gets every cache in Finland (country ID: 72) with travel bugs that matches those water keywords. Makes a pretty HTML file out of it. - geotoad.rb -u user -p password -q user -x myfindgpx -o myfinds.gpx -- -aBcDe- If your search item starts with a dash, not to confuse the command line parser you will have to insert a '--' (double dash) into the command line right at the end of all options. - geotoad.rb ... -A 15- ... Exclude all caches which are tagged as "Not available for winter". (See the FAQ for a list of attributes.) - geotoad.rb ... -a 52 ... Select only "night cache"s. - geotoad.rb ... -a 6 -A 57 ... Select caches "recommended for kids" not longer than 10km. See the manual page for more examples.