GeoQO Geocaching and Waypoint Database Software
GeoQO
Project Pages


NAME

geoqo - Geocaching DataBase


ABOUT GeoQO

The geoqo program is designed to be:

  - usable with a graphical user interface
  - usable on the command line
  - fast (uses a database  (mysql, postgresql, sqlite2 or sqlite supported)
  - highly extensible.  It's easy to:
    - add new search types
    - add new import routines
    - add new export routines
    - add new display routines
    - add new modification plugins
    - ...
  - A very extensive scripting ability that can automatically create
    GUI screens from script definitions.
  - In summary, you should be able to control your data.


DOCUMENT CONVENTIONS

The documentation uses the following structures for examples:

      > geoqo -argument value
      output line 1
      output line 2

In the above example, ">" is the command prompt. "geoqo -argument value" is an example command, and "output line 1" (and 2) would be the example output it might give.

Tutorials and Other Documentation

Make sure you check out the wiki pages as well, which provide tutorials, tips and tricks, FAQs, and other documentation:

  http://www.geoqo.org/wiki/

This document discusses how to use geoqo using the command line syntax. For instructions on using the GUI, please see the tutorial on the wiki web page above which contains screen-shot walk throughs.


QUICK OVERVIEW

Import a file:

  geoqo -i filetoimport.gpx

Search for and list all caches owned by Yamar

  geoqo -s cache:owner_name=Yamar -d list

Display result number 3 from the last search:

  geoqo -s 3 -d show

Export your search to a new file (in this case, the last search [Yamar's caches] since a new -s flag wasn't specified)

  geoqo -e filetoexport.gpx

List geocache data sets (includes imports, searches, etc)

  geoqo -d sets

Show stats about your data:

  geoqo -d stats


THE LONG, LONG MANUAL

GeoQO is very powerful. Thus, you'll find that this manual is long. It's divided up into sections based on the types of things geoqo can do: setup, import, search, display, modify, and export.

Make sure you check out the wiki pages as well, which provide tips and tricks, FAQs, and other documentation:

  http://www.geoqo.org/wiki/

Have I mentioned the wiki yet?

Help Is Nearby

The -d switch (you'll learn about this later) displays things. One of the things it can display is "help". To get help at any time, run:

  > geoqo -d help

To get started with the help system. To get help about a particular topic, include the major type and a slash (/) and the subtype. For example, Get get information about importing gpx files:

  > geoqo -d help:topic=import/gpx

To get a list of the particular subtypes for a given section, look up the major section:

  > geoqo -d help:topic=import

And it will list all of the subtyes (in the example above, it would display a list of all the import types).


DATABASE SETUP

Database setup is automatic for the default database. You can, however, create as many databases using other file names as you want (but why?).

      > geoqo --db-name otherdb --setup-database


IMPORTING DATA

To import an existing pocket query or other gpx file, simply use the -i switch:

      > geoqo -i somefile.gpx

You can import multiple files:

      > geoqo -i somefile.gpx,someotherfile.zip

Note that most importing plugins do store things in "sets". See sections further below for more details on what a "set" is and how useful they can be.

File import types currently available:

Import Gpx:

  > geoqo -i myfile.gpx
  > geoqo -i gpx:setname=myname:myfile.gpx

The gpx importer imports gpx files taken from the geocaching.com site (and probably many other sites too, but only geocaching.com GPX files have been tested so for) and imports the data into your geoqo database.

Options:

setname:

Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with "import:". IE, if you had a pocket query named "my search" then, when you imported the gpx file into geoqo, you'd get a new set named "import:my search".

Import Zip:

  > geoqo -i myfile.zip

The zip importer allows you to simply specify a zip file for importing instead of having to unzip it yourself. It expects the contents of the zip file to be named similar to the zip file itself, just like groundspeak sends them out for geocaching.com pocket queries. IE, if you import "111111.zip" it'll try to unzip it and then import the contained 111111.gpx file. It'll also try to import the 1111111-wpts.gpx file, if one existed as well.

Note: using this importer requires you to have unzip installed on your system.

Options:

setname:

Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with "import:". IE, if you had a pocket query named "my search" then, when you imported the gpx file into geoqo, you'd get a new set named "import:my search".

tmpdir:

The zip importer works by copying the zip file to a tmpdir and then unzipping it there. This is normally set to $HOME/.geoqo/tmpdir. This option lets you override that default.

default: /home/hardaker/.geoqo/temp

Import Dir:

  > geoqo -i /path/to/directory/

The dir importer allows you to simply specify a directory ("folder") to attempt to read every file from. It will skip any file types it does not understand.

Options:

setname:

Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with "import:". IE, if you had a pocket query named "my search" then, when you imported the gpx file into geoqo, you'd get a new set named "import:my search".

tmpdir:

The zip importer works by copying the zip file to a tmpdir and then unzipping it there. This is normally set to $HOME/.geoqo/tmpdir. This option lets you override that default.

default: /home/hardaker/.geoqo/temp

Import Loc:

  > geoqo -i myfile.loc
  > geoqo -i loc:setname=myname:myfile.loc

The loc importer imports loc files taken from the geocaching.com and waymarking.com site (and probably many other sites too, but only geocaching.com and waymarking.com LOC files have been tested so for) and imports the data into your geoqo database.

Options:

setname:

Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with "import:". IE, if you had a pocket query named "my search" then, when you imported the gpx file into geoqo, you'd get a new set named "import:my search".

Import Base64:

  > cat message | geoqo -i base64:-

The base64 importer allows you to send mail messages with encoded pocket queries directly to geoqo for decoding, unzipping, extracting and importing.

Note: using this importer requires you to have MIME::Base64 installed on your system. Most modern perl packages contain this out of the box.

Options:

setname:

Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with "import:". IE, if you had a pocket query named "my search" then, when you imported the gpx file into geoqo, you'd get a new set named "import:my search".

tmpdir:

The zip importer works by copying the zip file to a tmpdir and then unzipping it there. This is normally set to $HOME/.geoqo/tmpdir. This option lets you override that default.

default: /home/hardaker/.geoqo/temp

Import Wigle:

  > geoqo -i myfile.wigle
  > geoqo -i wigle:setname=myname:mywiglefile

The wigle importer imports wigle files taken from the geocaching.com and waymarking.com site (and probably many other sites too, but only geocaching.com and waymarking.com WIGLE files have been tested so for) and imports the data into your geoqo database.

Options:

setname:

Uses setname as the name of geoqo SET to create based on the data.

Import System:

  > geoqo -i "system:gpsbabel -i garmin -f /dev/ttyS0 -o gpx -F %{file:gpx}"

The system importer allows you to simply specify a command to run which generates a file of a type that geoqo can actually import. For example, the above command runs gpsbabel to import all the waypoints stored in a GPS on a unix system (/dev/ttyS0 is the name of a serial device on a linux machine).

Options:

cmd:

It must contain a %{file:TYPE} string that indicates where the output file will be stored, but the path and the name of that file will be created by geoqo. Example gpsbable arguments would be -o gpx -F %{file:gpx}

setname:

Uses setname as the name of geoqo SET to create based on the data. Normally this is extracted from the name field within the gpx file itself and prepended with "import:". IE, if you had a pocket query named "my search" then, when you imported the gpx file into geoqo, you'd get a new set named "import:my search". However if your system command doesn't properly name the resulting file, this can be used to override it.

tmpdir:

The temporary directory to use

default: /home/hardaker/.geoqo/temp

Import Create:

  > geoqo -i create:ident=home,lat=N38

The create import plugin lets you create new waypoints and inserts them into the database. The list of options is quite long as each type supported by a given supported waypoint system (geocaching, geodining, ...) requires an appropriate set of fields. Running geoqo simply as:

  > geoqo -i create

should bring up a GUI form which will prompt you for the needed information. Leave anything out that isn't appropriate for the waypoint type you're creating.

Options:

type:

default: Waypoint

ident:
setname:

default: created

desc:
lat:
lon:
sym:
time:
subtype:
url:
urlname:
cmt:

Import Average:

  > geoqo -i average:ident=newwaypoint,from1=oldwaypoint1,from2=oldwaypoint2

The average import plugin lets you create a new waypoint by averaging the latitude and longitude of a number of other waypoints. Useful to find the center of a number of waypoints, which is required for a number of geocaching puzzle caches.

Options:

ident:
type:

default: Waypoint

from1:
from2:
setname:

default: created

Import Project:

XXXXX DO NOT USE THIS PLUGIN; IT IS NOT FINISHED XXXXX

  > geoqo -i project:ident=newwaypoint,from=oldwaypoint,distance=528,direction=45

The project import plugin lets you project a new waypoint which is a distance from an older one.

Options:

ident:
type:
from:
distance:

default: 0

direction:

default: 0

setname:

default: created


SEARCHING THE DATABASE

The search system in geoqo is highly flexible and extensible. It supports multiple types of searching, which are documented below. The "-s" or "--search". The format of the search field is as follows:

  type:terms

Type is the type of search you want to do. This can be any of the types shown further below, or any types provided by a plugin. For those that want to write search plugins, please run "perldoc GeoDB::Search" to learn how to write search plugins.

Note: searching does nothing if you're not going to act on the results. Thus, you should at least provide a -l, -S or -e flag to list, show, or export the results. All the examples below are using the -l flag.

Search types are as follows:

Search Cache:

  > geoqo -s cache:name=unusual -d count
  Search/Set Count: 6

Searchs the database for only waypoints that are of type 'Geocache' and conform to the terms given. See the documentation on the waypoint: search type for further details on how to use it because everything else is the same.

Possible search columns for geocaches include the following, beyond those listed in the waypoint section:

        available
        archived
        groundspeak_name
        groundspeak_placed_by
        groundspeak_owner_id
        groundspeak_owner_name
        groundspeak_type
        groundspeak_container
        groundspeak_difficulty
        groundspeak_terrain
        groundspeak_country
        groundspeak_state
        groundspeak_short_description_html
        groundspeak_short_description
        groundspeak_long_description_html
        groundspeak_long_description
        groundspeak_encoded_hints

Search Waymark:

  > geoqo -s waymark:name=unusual -d count
  Search/Set Count: 6

Searches the database for only waypoints that are of type 'Waymark' and conform to the terms given. See the documentation on the waypoint: search type for further details on how to use it, because everything else is the same.

Possible search columns for waymarks include the following beyond those listed in the waypoint section:

      waymark_owner_name

When waymarking.com starts releasing more data in .gpx files, this will get significantly longer, of course.

Search Geodining:

  > geoqo -s geodining:resturant_name=Cafe -d count
  Search/Set Count: 6

Searches the database for only waypoints that are of type 'Geodining' and conform to the terms given. See the documentation on the waypoint: search type for further details on how to use it, because everything else is the same.

Possible search columns for geodining waypoints include the following beyond those listed in the waypoint section:

                               geodining_restaurant_name
                               geodining_submitted_by
                               geodining_price
                               geodining_service
                               geodining_continent
                               geodining_country
                               geodining_state
                               geodining_city
                               geodining_zip
                               geodining_address
                               geodining_description
                               geodining_details

Search Wigle:

  > geoqo -s wigle:name=unusual -d count
  Search/Set Count: 6

Searches the database for only waypoints that are of type 'Wigle' and conform to the terms given. See the documentation on the waypoint: search type for further details on how to use it, because everything else is the same.

Possible search columns for wigles include the following beyond those listed in the waypoint section:

                           wigle_ssid
                           wigle_netid
                           wigle_discover
                           wigle_channel
                           wigle_type
                           wigle_freenet
                           wigle_firsttime
                           wigle_sep
                           wigle_comment
                           wigle_qos
                           wigle_lastupdt
                           wigle_paynet
                           wigle_userfound

Search Waypoint:

  > geoqo -s waypoint:name=unusual -d count
  Search/Set Count: 6

The waypoint search type is for searching for primary fields in a waypoint record. Possible search terms include anything in the type-specific searches (since waypoint: searches include everything) and the following fields which apply to all waypoints regardless of specific type:

        desc
        lat
        lon
        sym
        time
        type
        subtype
        url
        urlname
        cmt

The following are some examples of how to use the waypoint: search type. Note that cache: and waymark: searches work the exact same way and also do everything below, but limit your search to just waypoints of those types.

The format for using the waypoint (or similarily for cache: or waymark:) search terms is:

  geqo -s waypoint:I<TERMS>

where TERMS are a comma separated list of search terms. Normally these would be specified like:

  waypoint:FIELDNAME=VALUE

The FIELDNAME indicates the field name you want to search (see below), and the VALUE is the value you want to search for. The value field is actually surrounded by wildcards, and thus searching for "me" will match any value with "me" somewhere in it including "He and I went to the store" and "sometimes". Using two equals signs turns off the automatic wildcard support (ie, name==me means search for a name that is just "me").

An example: find all waypoints with a urlname field containing "unusual":

      > geoqo -s waypoint:urlname=tubular -d list
      num GCID     Name
        1 GCDFE0   Hidden Headstones
        2 GCE29A   Celebrated Cemetery
        3 GCHW9M   The eyes have it (Yamar's unusual #1)
        4 GCJ491   O where art thou (Yamar's unusual #2)
        5 GCJ5DV   Inverted Cache (Yamar's unusual #3)
        6 GCJ66H   Gone Fishin' (Yamar's unusual #4)
        7 GCQEBQ   Yamar's Unusual #6: The ORB
        8 GCB284   Don't Be A Drip!

An example: find all geocaches owned by 'Spelunk':

      > geoqo -s cache:owner_name=spelunk -d list
      num GCID     Name
        1 GCJVTR   Here's to Your Health Cache
        2 GCJY4V   Sumac Grove Cache
        3 GCJZ2N   Wildlife View Cache
        4 GCKNZB   Misplaced Seed Cache
        5 GCKQBN   Out-N-About Cache
        6 GCKVFW   We Give-A-Hoot Cache
        7 GCNWM9   BUG JAR
        8 GCP5YP   Greenbelt  Hideaway
        9 GCPZK3   Davis Shopping Spree
       10 GCQ6Q8   BUG JAR II
       11 GCQ6TV   Great Experience Cache
       12 GCQ87Z   Here's to the Greenbelts
       13 GCQFYJ   Toby & Willie's Friends
       14 GCQH1M   Connect the Dots Cache
       15 GCTCC5   Canal Cache
       16 GCTFJH   The Micro Equalizer Cache
       17 GCVVWY   Spelunk's 'Fishy' Doings
       18 GCW26F   Mountain or Desert? Cache

Note that terms will match anything beyond the underscore ("_"). IE, if you do a search for:

  waypoint:short=some text

It will search the short description for "some text" even though the actual field name it'll search is "groundspeak_short_description". Using an exact fully spelled out field name is the most precise, but you can truncate names for convience.

Finally, you can use '*'s to indicate wildcard spots (u*sal would match "unusual" and "unit of sale"). By default geoqo already adds a * to both the front and the back of your search time (ie, name=unusual is actually interpreted as name=*unusual*).

You can also use the folling ARGUMENT types when searching for field values in a waypoint:

   field ARGUMENT value
field=value

Fuzzy match on value. The value will be surrounding by wildcards, as previously discussed so searching for "desc=blowfish" will actually search the desc field for "*blowfish*".

  waypoint:desc=blowfish
field==value

Also as mentioned above, if you don't want to use the automatic wild card searching discussed above, you can use 2 equal signs to indicate this. Thus if you search for "desc=blowfish" it will search the desc fields for an exact match on the word "blowfish" (IE, must not contain any other words).

You should use == searches for numeric values too, or else something like "difficult=3" will also match difficult numbers like 3.5.

  waypoint:desc==blowfish
field<value and field>value

Allows you to search on less than or greater than numeric values. IE:

  waypoint:lon<42.123

or

  waypoint:terrain>2
<>

If you use both, it becomes "not equal to". IE:

  waypoint:type<>unusual

Will list all waypoints without the word unusual in their desc field. This is also doing the same automatic wildcard matching like the = sign does, and thus the above search is actually searching for "*unusual*".p

<=>

This is also "not equal to", but is an exact match and thus:

  waypoint:desc<=>blowfish

will match any type of cache that doesn't have a desc field of "blowfish". It will include, in the search, caches with a desc field of "blowfish dinner" however because it's not an exact match.

Search Ident:

  > geoqo -s ident:gcabcd,gcefgh,gcijkl -d count
  Search/Set Count: 3
  > geoqo -s ident:abcd,efgh,ijkl -d count
  Search/Set Count: 3

The ident plugin merely lets you quickly list a bunch of waypoint identifiers you want to select with geodb.

The identifiers do have a wild card inserted before them so you can leave off a common prefix, as shown in the second example above, and still match the list (saves typing).

Really, the ident: search type is just a faster way to type:

  > geoqo -s waypoint:ident=abcd||waypoint:ident=efgh||...

Options:

idents:

A comma separated list of identifiers to search for

Search Log:

The log: search type lets you search waypoint log entries for waypoints matching a criteria. As an example, you can search for all waypoints in you database found by Yamar (me):

      > geoqo -s 'log:finder=Yamar' -d list
      num GCID     Name
        1 GCJVTR   Here's to Your Health Cache
        ...

Log tokens to search by:

   id
   ident
   date
   type
   logger_id
   logger
   text_encoded
   text

Special tokens to search by (makes sure a log was made by someone of a particular type):

   finder
   noter
   dnfer

WARNING: this may be amazingly slow on a mysql server. I think. Postgresql or sqlite2 (the defualt) database backends are just zippy, however.

Search Attribute:

Attribute searches groundspeak (geocaching.com) attributes that were loaded into the database when doing an import from a groundspeak .gpx file.

  > geoqo -s attribute:Dogs -d count
  Search Result Count: 32

NOTE: this does NOT search the user-defined attributes and only searches (geocaching.com) attributes. For searching user attributes you should use the attr: search plugin intstead.

Search Attr:

Attr searches attributes that you yourself have placed on a cache using the modify setattr module.

  > geoqo -s ident:gcabcd -m setattr:found=1 --save
  > geoqo -s attr:found=1 -d count
  Search Result Count: 1

NOTE: this does NOT search groundpseak (geocaching.com) attributes. For this you should use the attribute: search plugin intstead.

Search Rating:

The rating plugin lets you search ratings that may have been placed on a cache using the modify rate module.

  > geoqo -s ident:gcabcd -m rate:fun=8
  > geoqo -s "rating:fun>5" -d count
  Search Result Count: 1

If you have downloaded average ratings from the ratings server, you can search by those as well by prefixing the name with "others:" to search by the average rating given to the cache by others:

  > geoqo -s "rating:others:fun>5"

If you want to search for all caches that you have not rated for a particular category, use:

  > geoqo -s "rating:fun=-"

Search Tag:

Tag searches tags that you yourself or others have placed on a cache.

You can place them using the Tag Modify plugin:

  > geoqo -s ident:gcabcd -m tag:cool/awesome
  > geoqo -s tag:cool -d count:
  Search Result Count: 1

Prefix the tag names with "mine:" if you want to search just you tags, or "others:" if you want to search other people's tags.

  > geoqo -s tag:mine:cool -d count:
  Search Result Count: 1
  > geoqo -s tag:others:cool -d count:
  Search Result Count: 2

Search Set:

Sets, which are described further below, are a bunch of waypoints all with an identically named "tag". As an example, if your geocaching.com pocket query was named "my query" and you import it into geoqo using the -i switch the waypoints contained in that gpx file will be assigned to the "import:my query" set. You can use the set:setname search type to load these waypoints.

  > geoqo -s "set:import:my query" -d count
  Search Result Count: 500

This command would count everything in the database that was in the "import:my query" set name (that was likely imported from a pocket query). See the Advanced Searching section in the geoqo documentation for other examples of combining set: searches and waypoint: (or other) searches so you can search for "all waypoints matching a criteia within a set" for example.

If you prefix the name with a minus sign (-) then it will include all caches NOT in that set. For example to find all caches that are in seta but not in setb then the following expression would accomplish that:

    > geoqo -s 'set:seta&&set:-setb'

Search File:

  > geoqo -s file:foo.gpx -d count
  Search/Set Count: 3
  > geoqo -s file:foo.loc -d count
  Search/Set Count: 3

The file plugin loads a file into memory and then searches the normal geoqo database for all the waypoints that match those found in the file.

Options:

file:

A file to load and search for matching waypoints from

Search Track:

  > geoqo -s track:mytrackfile.gpx -d count:
  Search/Set Count: 3

The track plugin loads track data from a GPX track file (which you can retrieve from you gps using gpsbabel) and then compares the list of caches in you database to this data. It then matches all caches where your speed dropped below a configurable speed (3MPH is the default) and where the distance from the track is less than a configurable amount (defaults to near 500 feet).

This is even more useful when combined with the Track modify plugin, which can order caches based on the track and report the times you found them as well.

If you know all the caches are in a given set, however, you should probably limit the data it has to search through to a subset of you total database if it runs slowly.

To get track data from the gps, use gpsbabel:

  gpsbabel -t -i garmin -f usb: -o gpx -F track.gpx

See the Modify/Track plugin for a detailed example

Options:

trackfile:

A GPX trackfile to load and search by

speed:

Only look for caches where your speed dropped below this

default: 3

delta:

lat/lon delta to use looking for caches near a stopping point

default: 0.002

laterthan:

Only use track points which are beyond a specifed time.

Search File:

  > geoqo -s file:foo.gpx -d count
  Search/Set Count: 3
  > geoqo -s file:foo.loc -d count
  Search/Set Count: 3

The file plugin loads a file into memory and then searches the normal geoqo database for all the waypoints that match those found in the file.

Options:

file:

A file to load and search for matching waypoints from

Search Returnhome:

  > geoqo -s gps -d count
  Search/Set Count: 3

This plugin combines the functionality of a number of other ones rolled into one. In particular, it:

  1. pulls the existing waypoints from the GPS
  2. pulls the existing track from the GPS
  3. searches for the waypoints in the geoqo database that match the
     ones in the GPS using the GeoDB::Search::File plugin
  4. seaches the results of those for ones that the track came close
     using the GeoDB::Search::Track plugin.

Options:

gpstype:

Type of GPS

default: garmin

gpsport:

The port to use

default: usb:

Search Gps:

  > geoqo -s gps -d count
  Search/Set Count: 3

The gps plugin talks to a gps and finds all the waypoints in the geoqo database that are also in the GPS. This is done by pulling out all the waypoints from the GPS and then using the list to search the database.

Options:

gpstype:

Type of GPS

default: garmin

gpsport:

The port to use

default: usb:

Search Any:

The any: search type simply uses all the waypoints in the entire database. It (hopefully) obviously doesn't make sense to use this combined with other types of searches.


ADVANCED SEARCHING

There are advanced things you can do while searching. This section documents those:

Accessing a single result from the last search

Sumarize just the 12th waypoint from the last search results:

      > geoqo -s 12 -d list
       12 GCNK57   James Bond 047

Export caches 5-10 from the last search results:

      > geoqo -s 5-10 -e out.gpx

Logical Searches

You can use && (AND) and || (OR) pairs to add powerful searching combinations to your results. In fact, this is actually useful and can increase the speed of your queries if used properly (if you know you only want to search the data from a particular import, use a set: search && with a waypoint: search and the result will likely be returned faster).

This example searches for all waypoints owned by "spelunk" that I have found (ie, it exists in the "import:My Finds Pocket Query" imported gpx file).

      > geoqo -s 'waypoint:owner_name=spelunk&&set:import:My Finds Pocket Query' -d list
      num GCID     Name
        1 GCJVTR   Here's to Your Health Cache
        2 GCJY4V   Sumac Grove Cache
        3 GCJZ2N   Wildlife View Cache
        4 GCKNZB   Misplaced Seed Cache
        5 GCKQBN   Out-N-About Cache
        6 GCKVFW    We Give-A-Hoot Cache
        7 GCNWM9   BUG JAR
        8 GCP5YP   Greenbelt  Hideaway
        9 GCPZK3   Davis Shopping Spree
       10 GCQ6Q8   BUG JAR II
       11 GCQ6TV   Great Experience Cache
       12 GCQ87Z   Here's to the Greenbelts
       13 GCQFYJ   Toby & Willie's Friends
       14 GCQH1M   Connect the Dots Cache
       15 GCTCC5   Canal Cache
       16 GCTFJH   The Micro Equalizer Cache
       17 GCVVWY   Spelunk's 'Fishy' Doings
       18 GCW26F   Mountain or Desert? Cache

That is likely faster than doing the next search, but the following is another way to do something similar. In this case, I'm searching for all waypoints owned by spelunk that there is a log entry by me for (note: finder is a mis-nomer as a finder may have logged it as a "did not find"; search on the log "type" as well to limit it to just finds):

      > geoqo -s 'waypoint:owner_name=spelunk&&log:finder=Yamar' -d list
      num GCID     Name
        1 GCJVTR   Here's to Your Health Cache
        ... [same result] ...

grouping search terms

The () arguments can be used to group search terms together as well when you need to mix operations. In the following case we're looking for all waypoints "owned by scoobert AND have the word Ditch in them", and add to that all waypoints logged by me and all waypoints with 'ninja' in the title. Silly example, I know.

      > perl -I. geoqo -s '(waypoint:groundspeak:name=Ditch&&waypoint:owner_name=scoobert)||waypoint:groundspeak:name=ninja||log:finder=Yamar' -d list
        1 GCYBDY   Whodunit?
        2 GCP8MT   All Day
        3 GCQJY0   Kate's Watching
        [...]


SETS: Searches, imports, and just about everything are saved in "sets"

Actually, just about everything is stored in a set. They're a powerful way to "tag" a group of waypoints. The -N flag (or --set-name) flag specifies which name you want to store your current search results into (it's currently required and will always store the results somewhere).

Sets can be created from a search

    > geoqo -N search:47dad47 -s waypoint:owner_name=47dad47 -d list
    num GCID     Name
      1 GCH5EF   Sacramento's Second Webcam Cache
    [...]
     14 GCR86K   .
    > geoqo -N search:gary -s waypoint:owner_name=gary -d list
    num GCID     Name
      1 GCRWXC   Fishing in Cache Creek

Sets can be listed:

    > geoqo -d saved
    Set Name             Cache Count
    -------------------- -----------
    file:somefile        200
    search:geoqo         13                   <i>(default search name)</i>
    search:47dad47       14
    search:gary          1

And they can be combined:

    > geoqo -s set:search:gary,search:47dad47 -d list
    num GCID     Name
      1 GCRWXC   Fishing in Cache Creek
      2 GCH5EF   Sacramento's Second Webcam Cache
      [...]
     15 GCR86K   .


DISPLAYING SEARCH RESULTS

You've already seen the effects of the -d list switch, which lists all the waypoints in the resulting set/search. But there are a number of display types to pick from, and 'list' is only one such search output style:

Display Help:

The help module displays help on a given topic. You can specify help on a given topic.

  Example 1:
  geoqo -d help
  Example 2:
  geoqo -d help:topicname

The help routine displays help for the various geoqo plugins.

Options:

topic:

Specifies the topic to display help on.

Display Count:

  Example:
  geoqo -s 'set:import:my pocket query' -d count
  Search/Set Count: 500

The Count display simply counts the results in a set. This is very useful for counting the results before you do something with them (like dumping 500 caches to your screen when you were looking for just a few).

Options:

prefix:

The prefix string to print right before the count

default: Search/Set Count:

Display List:

  Example 1:
  geoqo -d list
  num GCID     Name
  1   GCMR3M   The Mystery of Livinrgttoo
  2   GCPWBT   Hidden Cactus Garden
  Example 2:
  geoqo -d 'list:format=%{3:count} %{6:ident} terr=%{3:groundspeak_terrain} diff=%{groundspeak_difficulty}'
  1   GCMR3M terr=1.5 diff=1.5
  2   GCPWBT terr=2   diff=1.5

The List display shows the contents of the search Set one line at a time. By default, the format is (may vary depending on type though):

  %{3:count} %{8:ident} %{66:urlname}

The number prefix is the number of spaces to print it in and it will pad with extra spaces if it doesn't fill that space. If left out, it'll print it straight out in any length it may be. Adding a decimal point will limit it to a maximum of that length. IE:

  %{20.20:urlname}

Will print only the first 20 characetrs of the urlname.

Options:

format:

Specifies the formatting parameters

Display Show:

  Example 1:
  geoqo -s 1 -d show
Show (-d show) the waypoint details for #3 from the last search (which is
really #3 from the default set or the set specified via the -N
switch):
      > geoqo -s 3 -d show
      GCHW9M     Multi-cache         Location:   38.542933, -121.6998
      Name:      The eyes have it (Yamar's unusual #1)
      Owner:     Yamar                (#183928)  Created:  2004-03-08
      Placed By: yamar
      Rating:    3/1.5
      URL:       http://www.geocaching.com/seek/cache_details.aspx?guid=5f9bd8d4-193a-4e0c-92c4-f107ae6d878b
      Short Description:
        A 3 part waypoint: a virtual, an unusual and a regular
      Long Description:
        Yamar to Spelunk on 2004-04-06:
        "If this cache is under that lamp post [again], I'm going to scream."
        [...]

Show the waypoint details and also the logs (-L, but this may change in the future):

      > geoqo -s 3 -d show -L
      GCHW9M     Multi-cache         Location:   38.542933, -121.6998
      Name:      The eyes have it (Yamar's unusual #1)
      [...]
      Log #13914681 by Mango101: (Found it)
        This cache took us way too many tries! Finally we found it! TNLN.
      Log #14812407 by Mister Grim & Pooka: (Found it)
        The hint threw us for a loop but we figured it out
        eventually. Thanks for another great cache!
      [...]

Options:

logs:

If true, shows the logs in the output.

default: 0

Display Map:

  Example 1:
  geoqo -s 'set:import:My Pocket Query' -d map

The Map display plugin displays a map of a set of waypoints with little red dots for each waypoint.

This plugin requires internet access since the map tiles are pulled from the http://www.openstreetmap.org/ project (which I highly recommend you contribute to; it's easy and fun to edit/fix the maps!).

(Eventually it should be possible to display with symbols, colors, etc as well as display the density overlays like the KML export plugin does)

Options:

style:

default: icons

icondir:

default: dist/tomtom-icons/

iconscale:

Size to scale icon sizes in the map. "auto" scales based on the number of waypoints to be shown.

default: auto

maptiles:

default: 2

notext:
dodensity:

Display Top10:

The top10 dispaly plugin counts the values in a particular field and shows you the top10 results of the counts in that field.

Example (defaults to counting the top 10 waypoint owners):

  > geoqo -s any: -d top10
  Top 10 'groundspeak_owner_name's
   Num    % Value
  ----------------------------------------------------------------------
  22    4 BootyBuddies
  20    4 sailorscodgers
  17    3 retiredprof
  16    3 two bison
  14    2 Sac D
  14    2 Oldhippy & Granny
  13    2 TRAKD
  12    2 rivercity
  11    2 2Dee2Dee
  10    2 jimlips
  10    2 Pirate Princesses

Example: counting container types

  > geoqo -s any: -d top10:groundspeak_container
  Top 10 'groundspeak_container's
   Num    % Value
  ----------------------------------------------------------------------
   234   50 Micro
   103   22 Regular
    92   19 Small
    13    2 Not chosen
    12    2 Other
    10    2 Virtual
     4    0 Large

Setting the "doaverage" parameter will also display the average value associated with a numeric field:

  > geoqo -s 'cache:owner_name=Yamar' -d top10:groundspeak_difficulty,doaverage=1
  Top 10 'groundspeak_difficulty's
   Num    % Value
  ----------------------------------------------------------------------
    14   38 2
     9   25 1.5
     6   16 1
     3    8 2.5
     2    5 3
     1    2 4
     1    2 3.5
  Average: 1.90278

Options:

field:

default: groundspeak_owner_name

show:

default: 10

doaverage:
averagetext:

default: Average:

script:
noblank:

default: 1

Display Sets:

  Example:
  geoqo -d sets
 Count Set Name
 ----- ----------------------------------------
   450 import:Bethel Island
   500 import:Concord
   500 import:Copy of SanFrancisco
 [...]

Shows the list of existing sets remembered by the geoqo system, and the number of caches in each one. See the geoqo documentation on "sets" for further details.

Options:

match:

Only lists set names containing this value

orderby:

Can be set to order by "modified" (default) or "setname" or "count"

default: modified

Display Attributes:

  Example:
  geoqo -d attributes
    Id  Attribute Name
------  ----------------------------------------
     1  Dogs
     3  Climbing gear
     4  Boat
     5  Scuba gear
 [...]

Shows the list of known groundspeak/geocaching attributes. This is useful for knowing which attributes you can search with using the 'attribute' search plugin.

Options:

match:

Only lists attributes names containing this value

orderby:

Can be set to order by "attributename" (default) or "attributeid"

default: attributename

Display Stats:

Example:

  > geoqo -d stats
  Waypoints:     8754
  Geocaches:     8751
  Waymarks:         0
  Logs:         56659
  Sets:            33

The stats display plugin shows statistics about what is contained in your database.

Display Gui/list:

  Example:
  geoqo -s cache:urlname=funny -d gui/list

The gui/list module displays a GUI in a graphical window that lets you examine the caches within a cache set.

This is only very preliminary work and is subject to greater expansion in the future.

Options:

fields:

default: Ident Type Subtype Groundspeak_Owner_Name URLNAME

plugins:
separator:

default: 0

Display Gui/show:

  Example:
  geoqo -s cache:urlname=funny -d gui/show

The gui/show module displays a GUI in a graphical window that lets you examine the caches within a cache set.

This is only very preliminary work and is subject to greater expansion in the future.

Display Bounds:

  Example 1:
  geoqo -s set:import:minneapolis -d bounds
  min    lat: 44.888483
  max    lat: 45.061767
  min    lon: -93.391317
  max    lon: -93.146517
  center lat: 44.975125
  center lon: -93.268917

The Bounds display shows the maximum and minimum latitude and longitude found in the set. It also outputs the center of the bounds as well.

Display Graph/find:

  Example:
  geoqo -s log:finder=Yamar -d graph/find:finder=Yamar

This shows a graph of finds over time by a given person. Generally, you'll want to run this after you've incorporated a pocket query of all of your finds. You can run it against other user names too, but it's unlikely you have every log record for them unless you've imported their find pocket query too.

Options:

finder:

Sets the NAME of the finder you're looking for to a particular geocaching name (ie, the name of the user that is logging the finds). 99/100 egoists recommend using your own geocaching name here.

logtype:

Defines the log type to graph.

default: Found it

Display Graph/placed:

  Example:
  geoqo -s any: -d graph/placed:type=month

Shows a graph displaying which during months, weeks, etc the caches were placed. Really this just gives an indication of which months are the most popular months for placing a cache (probably due to weather).

Options:

type:

Examines creation date based on this frequency (X-axis column). PERIOD may be either month, day, year, weekday or yearday. The default is month (ie, the graph will be from 1-12 showing the number of caches placed during each month in your loaded search set).

default: month

Display Dump:

  Example 1:
  geoqo -d dump
  Example 2:
  geoqo -d dump:short=1
  Example 3:
  geoqo -d dump:format=perl

The Dump display type dumps the contents of a set of waypoints. This is primarily a debugging mechanism.

Options:

short=1

Makes everything fit on one 80column line per item. This will truncate field values to something short enough to do this.

format=perl

Uses Data::Dumper to show the output in perl structure form. For the expert.

Options:

short:

If specified, limits output to 1 line per field

includeall:

If set then all waypoint items will be included, even if the field itself is blank

default: 0

format:

If set to "perl" will use perl's Data::Dumper to dump the perl object


MODIFYING RESULTS

There are a number of modification plugins that modify data after it's been extracted from the database and before it gets either displayed (-d) or exported (-e). These are most useful for changing data before it's exported.

Modify Solved:

Example of solving a puzzle and saving it:

  > geoqo -s ident:GCABCD -m 'setattr:puzn=N38 42.444,puzw=W121 42.444' --save

Example of exporting it with the replaced coordinates:

  > geoqo -s ident:GCABCD -e 'solved:+loc:out.loc'

This plugin replaces the latitude and longitude coordinates of a waypoint with those in the puzn and puzw attributes. Use the above examples as a guide for solving a puzzle and then using the solved: plugin when exporting your database ready for uploading into a GPS.

Options:

nattr:

The name of the attribute storing the new north coordinate

default: puzn

wattr:

The name of the attribute storing the new west coordinate

default: puzw

dropunparsed:

Drops caches that do not have puzzle answers but are not parseable

default: 1

Modify Gctodiff:

The "gctodiff" plugin (short for "GC to difficulty") replaces the first two letters in the 6-digit cache identifier with a single digit representation of both the difficulty and terrain ratings.

IE, if you had this cache:

    > geoqo -l
    num GCID     Name
    1   GCQEBQ   Yamar's Unusual #6: The ORB

It's rated a 1.5 in difficulty and a 2 in terrain. If you ran the gctodiff modify plugin on this data, it would replace the 'GC' with a 2 and 3:

    > geoqo -m gctodiff: -d 'list:format=%{newident} %{desc}'
    23QEBQ   Yamar's Unusual #6: The ORB

It actually stores the data in the 'newident' field so the old one is still available. The export modules, however, use the newident field when writing out the cache identifiers so this is what your GPS, or what-have-you, will see when you load it into that.

I (Yamar) do this specifically so when I'm looking at my garmin, for example, I get an immediate feel for how hard a particular cache is going to be without having to pull up data about it. (I also use the symbol plugin to change the symbol so I can see the type of cache it is too). My goal here is to maximize the amount of data I seen on the screen!

The map from groundspeak/geocaching.com ratings is as follows:

  1    => 1
  1.5  => 2
  2    => 3
  2.5  => 4
  3    => 5
  3.5  => 6
  4    => 7
  4.5  => 8
  5    => 9

Modify Rewrite:

The rewrite modify plugin lets you rewrite fields based on other fields. For example, I (Yamar) use the following rewrite when putting stuff to a gpx file I'm going to load into my TomTom so I get as much information as possible when clicking on the icon in the tomtom map display:

  rewrite:groundspeak_name=%{ident}/%{4:subtype}: %{groundspeak_name}

That way the groundspeak_name which might have been "some cache" becomes "GCABCD/Trad: some cache" to give me more information about it. (actually, I use the gctodiff plugin too and use the newident field instead; see the gctodiff plugin for details).

Modify Setattr:

The "Setattr" plugin (short for 'Set Attributes') allows you to add your own "attributes" to waypoint(s). You must specify the command line option "--save" to get them to be saved permenently to the database though. You can pick any attribute name you want, although some other modify plugins (like the "solved" plugin) may expect particular attribute names.

Atttributes can be used for just about anything. For example, you can use them to store notes, remember hints from other people, collect data for a complex puzzle cache, etc.

Example of storing a note:

  > geoqo -s ident:GCABCD -m 'setattr:notes=I hate this puzzle' --save

Example of something silly:

  > geoqo -s ident:GCABCD -m 'setattr:foo=bar' --save

Then you can search for all caches with that name and value later:

  > geoqo -s attr:foo=bar -l

Example of solving a puzzle and saving it:

  > geoqo -s ident:GCABCD -m 'setattr:puzn=N38 42.444,puzw=W121 42.444' --save

Example of exporting it with the replaced coordinates:

  > geoqo -s ident:GCABCD -e 'solved:+loc:out.loc'

The setattr plugin lets you store your own information about a cache into the database. Some of the other plugins use attributes to manipulate things (see the solved plugin for an example). Sometimes you may want your own "notes". As an example, I modify Unknown puzzles that you solve in the field (instead of "in advance" puzzles like cross puzzles) with "setattr:infield=1". (then I can use that attribute with the modifier: plugin to drop all unknowns that don't have that attribute set or don't have a 'puzn' coordinate assigned showing I've solved it.

IMPORTANT NOTE: You must specify --save to the command line to have geoqo save your attribute changes back to the database. Otherwise you're only setting attributes temporarily during the one-time call of geoqo.

Math and Substitution

Math and Substition can be done by prefixing the values with "math:" and "substitute:" where the contents will be searched for names with other attribute names in ()s and replaced with the attribute values. And if the math: was used, it will then be evaluated. Multiple depth replacements/math will work.

Here's a more complex than needed example (the puzw attribute needs to be set as well for this to work):

  > geoqo -s ident:GCABCD -m 'setattr:puzn=substitute:N38 42.(A)(B)(C)' --save
  > geoqo -s ident:GCABCD -m 'setattr:A=4' --save
  > geoqo -s ident:GCABCD -m 'setattr:B=math:(A)*2' --save
  > geoqo -s ident:GCABCD -m 'setattr:C=math:(B)-(A)' --save
  > geoqo -s ident:GCABCD -m solved: -e out.gpx

Note that the actual equation will still be stored as the attribute; The calculation is done when the attribute is later read (for example, by the "solved" modify plugin).

Modify Tag:

The "Tag" plugin allows you to add "tag"s to your caches.

Example:

  geoqo -s cache:owner_name==Yamar -m 'tag:tags=awesome/cool'

Another to remove tags:

  geoqo -s cache:owner_name==Yamar -m 'tag:tags=lame,deletetags=1'

Publishing tags

Your tags may be published to a geoqo tag server, and you may pull information about how other people have tagged waypoints from the tag server. To do this you must first create an account on the tag server:

  http://tagserver.geoqo.org/

Then put your created username and password into your $HOME/.geoqo/config file like:

  geoqouser YOURUSERNAME
  geoqopass YOURPASSWORD

Then you can publish your tags for a given set using:

  geoqo -s SEARCHTERMS -m tag:publish=1

Additionally you can fetch data about other people's tags using:

  geoqo -s SEARCHTERMS -m tag:fetch=1

When you use the -S option to show a the data for a waypoint you will see a list of all your tags as well as a list of other peoples tags that you have fetched.

Options:

tags:
deletetags:
publish:
publishtags:
ignoretags:

default: lamppost/found

fetch:
geoqouser:
geoqopass:

Modify Rate:

The "Rate" plugin allows you to add "ratings"s to your caches.

Example:

  geoqo -s cache:owner_name==Yamar -m 'rate:overall=4'

(at the moment "overall" is the only rating you can provide; more coming)

Publishing ratings

Your ratings may be published to a geoqo rating server, and you may pull information about how other people have rated waypoints from the rating server. To do this you must first create an account on the rating server:

  http://ratingserver.geoqo.org/

Then put your created username and password into your $HOME/.geoqo/config file like:

  geoqouser YOURUSERNAME
  geoqopass YOURPASSWORD

Then you can publish your ratings for a given set using:

  geoqo -s SEARCHTERMS -m rate:publish=1

Additionally you can fetch data about other people's ratings using:

  geoqo -s SEARCHTERMS -m rate:fetch=1

When you use the -S option to show a the data for a waypoint you will see a list of all your ratings as well as a list of other peoples ratings that you have fetched.

Options:

overall:
ratings:
publish:
publishtags:
ignoreratings:
deleteratings:
fetch:
geoqouser:
geoqopass:

Modify Makepuzzle:

This plugin extracts puzzle coordinates and equations from a cache description and sets up some attributes for doing the puzzle solving. If a cache description has text in it like "N38 AB.CDE" then this plugin will create 5 attributes A-E and a "puzn" attribute with the text "replace:N38 (A)(B).(C)(D)(E)" so that merely by filling in the A-E attributes will complete the puzzle.

Options:

nattr:

The name of the attribute storing the new north coordinate

default: puzn

wattr:

The name of the attribute storing the new west coordinate

default: puzw

reextract:

Force rextraction of the equation wiping out the existing data

default: 0

Modify Delete:

This command removes the waypoints from the database. Obviously, this should be used with caution because it can not be undone.

For those that really and truly hate puzzles:

  > geoqo -s 'cache:subtype=Unknown' -m delete

This can be useful for temporarily importing a bunch of items you don't want to keep around in the long run.

Modify Classify:

Options:

inputprefix:

default:

outputprefix:

default: predicted:

categories:

default: kids,coolcontainer,goodlocation,fun

LearningType:

default: DecisionTree

stopwordsfile:

default: /usr/share/geoqo/classify-ignore-words

Debugging:

Modify Symbol:

This plugin replaces symbol identifier (normally "Geocache" for geocaches) with a new symbol based on your set criteria.

As an example, I (Yamar) use the following mem: file definition to remap all my symbols into things that look (on my garmin) kind like the cache container:

  symbol:
  subtype=Multi-cache=Fitness Center,
  subtype=Unknown Cache=Information,
  subtype=Webcam Cache=Shower,
  groundspeak_container=Micro=Cemetery,
  groundspeak_container=Small=Tunnel,
  groundspeak_container=Large=Geocache Found,
  subtype=Virtual Cache=Ultralight Area

Then I can run geoqo to remap stuff before exporting it to a .gpx file:

  > geoqo -s some_search_criteria -e 'mem:FILENAME+out.gpx'

That way all multi-caches get remapped to a 'Fitness Center' because the 'Fitness Center' icon on my garmin looks like a little guy lifting weights, and thus I know it's going to be a harder cache (or one I'll likely have to walk more). I like multi's a lot, but I do like to know when I'm hitting them. Similarily, a Cemetery icon on my etrex is a small dot, a Tunnel is a bit larger, and a Geocache found icon is very large so I use them to represent sizes.

If you want to use the symbol plugin, you should pick your own symbols that seem right on your gps or other software system. Each GPS's symbols tend to be quite different (and the name chosen should be a symbol your GPS or software actually matches).

Formatting

The format of the plugin is as follows:

  symbol:CACHEDATA=CACHEVALUE=SYMBOLNAME,CACHEDATA2=CACHEVALUE2=SYMBOLNAME2,

They are exact matches only. So the CACHEVALUE must exactly equal the value found in the CACHEDATA field or it won't be replaced. The symbol plugin will stop after the first match so the first symbol in the list that gets matched always wins.

Modify Translate:

By far, this is one of the most powerful modification plugins. It uses online services (like Google) to translate cache fields from one language to another. As an example, here are some of my caches:

  > geoqo -s cache:owner_name==Yamar&&waypoint:ident=GCJ -l
  num GCID     Name
  1   GCJYPW   Hoppin' mad about Davis
  2   GCJGRQ   Beneficial cache
  3   GCJKMD   Historical water tower
  4   GCJ7KT   Got Coffee?
  5   GCJ66H   Gone Fishin' (Yamar's unusual #4)
  6   GCJ491   O where art thou (Yamar's unusual #2)
  7   GCJ5DV   Inverted Cache (Yamar's unusual #3)

And here is what they look like when translated from English to Spanish:

  > geoqo -s cache:owner_name==Yamar&&waypoint:ident=GCJ -l -m translate:source=English,destination=Spanish
num GCID     Name
  1   GCJYPW   Hoppin' enojado sobre Davis
  2   GCJGRQ   Escondrijo beneficioso
  3   GCJKMD   Torre historica del agua
  4   GCJ7KT   Cafe Conseguido?
  5   GCJ66H   Fishin ido ' (4) inusual de Yamar #
  6   GCJ491   O donde mil del arte (2) inusual de Yamar #
  7   GCJ5DV   Escondrijo invertido (3) inusual de Yamar #

Valid languages to pick from:

  English
  Spanish
  French
  German
  Italian
  Korean
  Japanese
  Portuguese

Requirements

1) you must be connected to the net

2) you must have the WWW::Babelfish perl module installed.

Options:

source:

The source language to translate from.

default: Spanish

destination:

The destination language to translate to.

default: English

fields:

A / separated list of fields to translate.

default: urlname

service:

The name of the translation service to use.

default: Babelfish

Modify Distance:

The distance modify plugin puts distance information from a given lat, lon coordinate and inserts the data into the "distance" field of the waypoint. You can then use it in other ways like in rewrite modification engines or in list formatting, etc.

  > geoqo -s ident:GCABCD -d 'list:format=%{ident} %{distance}

You can calculate distance from coordinates:

  > geoqo -s ident:GCABCD -m 'distance:n=n38 12.123,w=w42 22.333'

or from another waypoint already in the DB:

You can calculate distance from coordinates:

  > geoqo -s ident:GCABCD -m 'distance:from=GCABCD'

Options:

from:

The waypoint name distances should be calculated from

n:

The North coordiante to calculate distance from

w:

The West coordiante to calculate distance from

Modify Sortby:

The sort by function sorts data in a set by a particular field.

  > geoqo -s SOMETHING -m sortby:groundspeak_terrain -l

Options:

sortby:

Field to sort by

default: distance

Modify Track:

The track plugin lets you compare a list of waypoints found in a search against the data in a gpx track file. Specifically, it:

 - adds the following attribute fields to the waypoint's attribuets
   (not permenantly; use --save to save them):
   trkptdate    -  The date of the track point nearest the cache
   trkpttime    -  The time of the track point nearest the cache
   trkptnum     -  The number of the track point nearest the cache
   trkptname    -  The name of the track the point is in
   trkptdist    -  Distance in feet from the cache to the nearest track point
   trkptnum     -  The Nth track point counter into the track point data
   trkptepoch   -  Seconds since 1970 of the trackpoint closest to the cache
   trkptstart   -  Start time of the search (got closer than config distance)
   rtkptend     -  End time of the search
   rtkptnearby  -  Amount of time spent searching (= end - start)
 - optionally sorts the resulting waypoints by time visited if the
   sort option is set.

Using this and the track search plugin you can take a track GPX file downloaded from a GPS and list all the caches you came near in the order you went to them along with the time stamp when you visited it. As an example, this is the results of a trip I took one day:

  > geoqo -s 'track:track.gpx' -m 'track:track.gpx' -d list:'%{7.7:ident} %{attr:trkpttime}  %{urlname}'
  
  GC10J27 10:55:22  This one is Golden
  GCPC2R  11:16:53  "THE ISLAND"
  GCYCGE  13:02:07  Legacy Trail #1 - River BBQ
  GCD8A1  13:10:55  Under Lock & Key
  GC5CBC  13:52:32  Let the Games Begin
  GCPR6E  14:11:27  YFcache10
  GCWR36  14:31:10  Granite Rock
  GCK8YR  14:54:07  The Cache in The Middle of The Freeway
  GCYYXV  16:02:05  Cisco Grove TB Stop
  GC10Q0Q 16:02:41  Hard Rock Exchange #2
  GCW1C3  16:27:08  Crack with a View
  GCG38E  16:45:33  The Solar System - Pluto

To get track data from the gps, use gpsbabel:

  gpsbabel -t -i garmin -f usb: -o gpx -F track.gpx

Options:

trackfile:

Track data to sort by

sort:

field to sort resulting set by (if set)

default: trkptepoch

distance:

Distance away in feet to use for determining how long you were in the area

default: 528

hroffset:

Offset in hours to use from the datestamp found in the track; useful if the timezone in the GPS/track does not match the track was laid

Modify Diff:

Options:

out:

the name of the output file to store the html formated differences in.

Modify Limit:

This module limits the number of waypoints in a set to a certain number (starting at an optional certain point in the list of waypoints).

IE, it starts at the offsetth waypoint in the set being modified, and limits the total number to number, stripping off all of the waypoints before the offset first and then everything from offset+number next.

If just number is specified (the common case) the firest number waypoints are kept.

If there are 250 caches in the set:

number = 100, offset = 0

Will get the first 100 caches

number = 100, offset = 100

Will get the next 100.

number = 100, offset = 200

Will get the last 50.

This module is very useful when combined with the distance and sortby modify pluigns to get the top 10 caches (for example) near something:

  geoqo -s 'set:import:mypocketquery' -m distance:from=GCABCD+sortby:+limit:10

Options:

number:

default: 100

offset:

default: 0

Modify Only:

This is most useful when doing really complex exporting. See Yamar's usage description on the web page for why this is helpful sometimes. It's mostly useful when you want to only include certain waypoints in a given export file, and you want to create lots of export files (TomTom's require one file per POI you wish to create, and I (Yamar) create different POIs for each cache type, size, etc.)

The argument formatting is:

  only:field=value

where field is the field (or attribute prefixed with 'attr:') name, and value is the exact value. The valid match types are:

only:field=value

Includes the waypoint only if the value is exactly the same as the waypoint's field value.

only:field<>value

Matches if the field is not that value

only:field=-

Matchs if the field doesn't exist.

only:field=+

Same as =- but only includes the waypoint if it does exist.

Modify Drop:

This is most useful when doing really complex exporting. See Yamar's usage description on the web page for why this is helpful sometimes.

The Drop modifier is a compliment to the only modifier. Generally the "only" modifier will be easier for most people to think about, but technically you only need one as they can both accomplish the same tasks with inverse logic.

The argument formatting is:

  drop:field=value

where field is the field (or attribute prefixed with 'attr:') name, and value is the exact value. The valid match types are:

drop:field=value

Matches only if exactly the same.

drop:field<>value

Matches if the field is not that value

drop:field=-

Matchs if the field doesn't exist. I use this like follows:

  #
  # unknown caches with solved puzzle coords
  #
  drop:subtype<>Unknown Cache
  +drop:attr:puzn=-
  +solved:
  +gpx:nologs=1:palm-solved.gpx

To drop any unknown cache that a 'puzn' attribute hasn't been added to it (see the Solved modify plugin for details).

drop:field=+

Same as =- but only drops it if it does exist.

Modify Dropexisting:

This modify function is really only useful during an import before a data save.

The plugin simply removes all data from the current set that already exists in the database. This can be used to import data where only the new data is desired.

Example:

  > geoqo -i 'myfile.gpx+dropexisting'

Options:

prefix:

default:

onlyprefixold:

default: 1

Modify Load:

This is only useful when you're going to be doing complex exporting where you need the caches data loaded early before exporting to multiple files. Otherwise geoqo may load all the data once per file.

  > geoqo -s something -m load -e 'gctodiff+file1.gpx;file2.gpx

See the export documentation for details on why file1.gpx and file2.gpx may contain separate data.

Basically, since this is a confusing one, is if you're doing complex exporting (multiple files at once) put this on the -m switch to speed things up.


EXPORTING RESULTS

None of this is useful if you can't export your results of course. There are a number of export plugins you can pass to the -e switch to export the results of your search to a file.

QUICK EXPORT EXAMPLES

Some quick examples:

Exporting all waypoints from two sets:

    > geodb -s 'set:search:gary&&set:search:47dad47' -e garyand47.gpx --debug 1
    1: writing file: garyand47.gpx

Exporting all waypoints in a set that are of type "Unknown" to a .loc file:

    > geodb -s 'set:import:somefile&&waypoint:type=Unknown' -e partfilebackout.loc

EXPORTING AND MODIFYING

You can also combine modifications and exports in one pass. First list the modifications specs you want to do (see the documentation on the modification plugins for details) separated by + signs. Everything before the last + will call a modification plugin, and after the last + will be an export plugin.

An example:

    > geodb -s 'cache:type=Unknown' -e gctodiff+partfilebackout.loc

OUTPUTING TO MULTIPLE FILES

You can also specify multiple output files separated by ';'s. Modification attributes will only apply to the next file. If you want every file to contain a modification plugin result, use the -m flag instead.

    > geodb -s 'cache:type=Unknown' -e 'gctodiff+partfilebackout.loc;partfilebackout2.gpx

The above applies the gctodiff plugin to only the .loc file; the gpx file is written out using raw data.

EXPORT PLUGIN TYPES

Export Gpx:

  > geoqo -s 'cache:name=cool cache' -e myfile.gpx

The gpx exporter writes out a gpx file containing all the caches in the search set.

Options are applied between the colon delimiter type specifier (first part) and the file name (th e last part) like so:

  > geoqo -s 'cache:name=cool cache' -e gpx:nologs=1,setname=boo:myfile.gpx

Options:

setname:

Makes the name field in the gpx file set to this value.

default: geoqo-export

nologs:

If set the resulting gpx file does not contain the wayoint logs.

nogcattributes:

If set the resulting gpx file does not contain the groundspeak attributes.

Export Loc:

  > geoqo -s 'cache:name=cool cache' -e myfile.loc

The loc exporter writes out a loc file containing all the caches in the search set.

Export Map:

  Example:
  geoqo -s set:import:myPQ -e map:output.png

The map will show red dots whereever there is a cache (Yes virginia, there will eventually be symbols and names). The output (currently) must be a PNG file.

Options:

style:

default: icons

icondir:

default: dist/tomtom-icons/

iconscale:

Size to scale icon sizes in the map. "auto" scales based on the number of waypoints to be shown.

default: auto

maptiles:

default: 2

notext:
dodensity:

Export Html:

  > geoqo -s 'cache:name=cool cache' -e myfile.html
  Prints a set of caches to a series of web pages.  Each cache will
  get it's own file and a top level index file will be created that
  links to each cache page.
  Very useful for outputting geocaches to plucker.

Options:

subdir:

Puts created HTML files in this sub directory name.

default: caches

title:

The title to put at the top of the page

default: GeoDB HTML Export

Export Kml:

  > geoqo -s 'set:import:near me' -e fortheearth.kml

The software will also produce a density plot as well, which shows the density of caches in particular areas color-coded by relief colors (rainbow; red = very few, purple = many). Examples of this can be seen on Yamar's cache homepage page http://geocaching.sharedlists.com/.

Options:

size=NUM
  > geoqo -s 'set:import:near me' -e kml:size=100:fortheearth.kml

Changes the number of squares in the density plot to NUM by NUM. Defaults to 50.

width=NUM
height=NUM

Changes just the width and height of the squares. The size parameter can change both at once.

(there are a bunch of options for the density plot, which are currently undocumented).

Options:

bogus:
dataname:

default: Export from GeoQO

dowaypoints:

default: 1

dodensity:

default: 1

dojail:

default: 0

bogus:
waypointstyle:

default: geoqo

waypointheight:

default: 150

waypointmode:

default: relativeToGround

waypointextrude:

default: 1

includedescriptions:

default: 1

bogus:
squareratio:

default: 1

size:

Creates a plot where there are SIZE by SIZE squares of colored rectangles

default: 200

width:

Normally equal to the size value but can be set independently. It specifies the width (in squares) of the density plot.

height:

Normally equal to the size value but can be set independently. It specifies the height (in squares) of the density plot.

spread:

Sets the spread that determines the number of neighboring squares that a given cache will effect. EG, a spread of 5 will affect a circle of density squares in a radius of 5. This generally should be a low value of probably not more than 5 or so.

default: 5

doempty:

If set to 1, even empty squares will be colored (red). Otherwise the empty squares are removed from the plot leaving the plane ground underneath.

default: 0

bogus:
altitude:

The altitude to set the density plot squares at.

default: 1000

densitymode:

default: relativeToGround

extrude:

Whether or not to extrude the density plot squares down to the ground.

default: 0

opaque:

The opacity of the density squares. Must be between 0 and 100, with 0 being completely see-through (and thus completely useless).

default: 20

linewidth:

The width of the border lines to draw (0-4). 0 means don't draw borders on the squares.

default: 0

bagus:
jailaltitude:

default: 100

jailmode:

default: relativeToGround

bogus:
limitdata:

default: 1

nmax:

The maximum north coordinate value to created the grid over. Normally this is automatically set by the maximum value found in the data, but can be overridden

nmin:

The minimum north coordinate value to created the grid over. Normally this is automatically set by the minimum value found in the data, but can be overridden

wmax:

The maximum west coordinate value to created the grid over. Normally this is automatically set by the maximum value found in the data, but can be overridden

wmin:

The minimum west coordinate value to created the grid over. Normally this is automatically set by the minimum value found in the data, but can be overridden

Export System:

There are two ways to use the system export mechanism:

Run a system command for cache:
  > geoqo -s 'cache:name=cool cache' -e 'system:cmd=echo %{ident} %{desc}'

That command runs echo for each cache in the set, replacing %{ident} and %{desc} with the fields from those caches.

Useful things to do for this would be to open firefox (a web browser) on each cache page:

  > geoqo -s 'cache:name=cool cache' -e 'system:cmd=firefox %{url}'
Run a system command

You can also run a command on a file generated by an export module. As an example, the following command will call gpsbabel to convert a gpx file to a tomtom compatible file:

  > geoqo -s 'cache:name=cool cache' -e 'system:cmd=gpsbabel -i gpx -f %{file:gpx} -o tomtom -F mycaches.ov2'

Options:

cmd:

COMMAND is what gets run. If it contains a %{file:TYPE} string in it, that will be replaced with a file name of that type and it'll get run just once. If it doesn't, it'll get run once per cache in the set being processed and each %{token} specifier will get replaced by that item from the cache.

sleep:

Between each command executed in the per-cache mode, geoqo will sleep for NUM seconds before running the next. It defaults to 1, and can be set to 0 to just fire them off as fast as possible.

dontdelete:

if set to 1, don't delete the temporary files

tmpdir:

The temporary directory to use

default: /home/hardaker/.geoqo/temp


PLUGINS TO USE EVERYWHERE

Here are some useful plugins that can be used in many command line definitions.

Everywhere mem:

It hard to repeatedly type complex queries, tasks, or what have you so to facilitate this you can use the Mem plugin for remembering complex strings (or even simple onse, if you choose).

To do this, take a complex search (or export, or modify) string and save it in a file in the directory "$HOME/.geoqo/mem/TYPE/FILENAME". Where TYPE is one of "search", "export", or "modify" and FILENAME is a file name of your choosing. You can also store file entries directly in $HOME/.geoqo/mem/FILENAME (note the missing "TYPE" part), which then makes the definition usable for all types. It is not likely you'll need to use a definition for both searching and exporting (as an example), however, so I suggest you store them in a type-based subdirectory instead. Only because it's cleaner. You want to be neat and tidy right?

All lines read in these file will be merged together and leading and trailing white-space characters are stripped as well comment lines (which should start with a #). For example if you had a file like so:

  > cat $HOME/.geoqo/mem/search/memtest
    # Searches a particular imported set named "near me"
    set:import:near me
      # but only for items I haven't logged as found
      &&cache:finder<>Yamar
      # and aren't unknown caches.
      &&cache:subtype<>Unknown

You can then run geoqo like so:

  > geoqo -s mem:memtest -d count
  Search Result Count: 480

Which is really a replacement for:

  > geoqo -s set:import:near me&&cache:finder<>Yamar&&cache:subtype<>Unknown -d count

Since you may want to frequently replace parts of your super-long and complicated definition strings you've built up, you can do this as well by putting %[NAME,DEFAULT] strings inside your definitions. IE, doing this:

  > cat $HOME/.geoqo/mem/memtest
    set:import:%[setname,near me]
      &&cache:finder<>Yamar
      &&cache:subtype<>Unknown

Makes the import: set default to "near me" so the above example command will work just like it would before, but if I specify a setname option on the command line I can override it. Here's the original command example:

  > geoqo -s mem:memtest -d count
  Search Result Count: 480

And here's using the same search criteria, but using "fairfield" as the import set name instead of the default "near me":

  > geoqo -s mem:memtest,setname=fairfield -d count
  Search Result Count: 182

Final note: you can have mem: definitions that call other mem: definitions. The only caveat there is that parameters aren't passed down automatically, so if your second mem: definition being called has a %[something,xxx] definition then you should call it within the higher definition as mem:subdef,something=%[something,xxx] as well.


SCRIPTING ABILITY

GeoQO can also perform a bunch of tasks at once in a scripted fashion. IE, if you find yourself repeatedly doing a standard search followed by an export, you can script things together in a single file and call geoqo -x FILE.

The script file format contains lines that start with a '%MODE' followed by text for that MODE. MODE should be one of: search, export, import, modify, display or print. You can break long lines into pieces just like the mem: plugin discusses above.

Thus the following script (saved in, for example, "myscript.txt") will display unsolved puzzles in your database ordered by distance:

  # searches for all 'Unknown' caches
  %search
  subtype=Unknown
  &&attr:puzn=-
  # displays them in list format
  %display
  list

Then running the script will display the list:

  > geoqo -x myscript.txt
  ... [list displayed here] ...

Scripts can be stored in $HOME/.geoqo/scripts and if a script is run and the file doesn't exist in the current working directory, then the $HOME/.geoqo/scripts directory will be checked to see if it contains the file.

Scripts can contain %[name,default value] sections just like Everywhere Mem: definitions can and are acted upon the same way. Thus a script of:

  %search
  waypoint:type==%[type,Waymark]
  %display
  count

Will default to counting all the Waymarks in the database. But if run as:

  > geoqo -x myscript.txt:type=Geocache

It'll count all the geocaches instead.

Special Script Formatting

White Space Wrapping

Normally script lines are merged together, stripping leading and trailing white space off of a line. EG, Scripts that look like:

  %search
  waypoint:type=
    =
  Geo
   cache

will actually be translated to a search using just:

  wayoint:type==Geocache

If you need to force whitespace into a script line at the begining or end you can use a triple " in order to forec it. EG:

  %search
  cache:owner_name=Super
  """ Sleuth"

Will keep the space between the """ and the word Sleuth:

  cache:owner_name=Super Sleuth

Trailing """s work similarily.

Special Script Keywords

All script pieces begin with a % sign on a new line. The line format looks like:

  %keyword someoption=1 otheroption=yes

These special options may include these global options as well as any keyword-specific options discussed below:

allowgui=1

This lets the GUI screens be shown for the sub-scripts. Normally they're hidden as the top script is always expected to pass needed parameters down.

The special script keywords that mayb be used are:

%print

Prints everything from that section to the screen.

Example:

%print hello world

%script

Runs a subscript based on the text following the %script line. (may include the script name and potentially arguments following a ':').

Example:

%script scriptname:arg1=value1

%include [ARGUMENTS] SCRIPT_FILE_NAME

Include another script as part of this script. Unlike the %script command, the %include command operates on the same search set, becomes part of the same auto-gui screen, etc.

You can also pass a type=hooks argument to include a bunch of files. EG:

%include type=hooks specialhooks/*.inc

Will include every file that matches that pattern in each of the script search paths. The order in which they are included is determined by alphabetical ordering of the last filename component (ie, not directory path component).

Finally, you can auto-wrap includes in if statements and use the resulting titles from the included files in menu to select which file gets executed. This is primarily intended for building dynamic menus from found plugins. This is best seen by an example:

In a file called "testincludetop.txt", we put the menu definition:

  %ignore
  %[mymenu,0
  ,labels=(%{VALUELABELS})
  ,type=menu,text=top menu:
  ,refresh_on_change=1
  ]

In two files called testinclude-1.txt and testinclude-2.txt we put:

  #scriptname: item number 1
  %print
  some thing or other to handle choice #1

(And something similar for number 2)

Then finally, in the real top level script you call the whole shabang with:

  %include type=hooks autoif=mymenu hookheader=testincludetop.txt testinclude*.txt

In the end, the whole result gets built as follows:

  %ignore
  %[mymenu,0
  ,labels=(0,item number 1,2,item number 2)
  ,type=menu,text=top menu:
  ,refresh_on_change=1
  ]
  %if "%[mymenu]" eq "0"
  %title
  item number 1
  %print
  some thing or other to handle choice #1
  %endif
  %if "%[mymenu]" eq "1"
  %title
  item number 2
  %print
  some thing or other to handle choice #2
  %endif

If you could follow that, I'll be impressed. But it's really powerful! See the included "searchbase" script for a much larger example.

%save

Calls 'save' on the current set saving all the data to the db (needed if modified in anyway that should result in a save, such as when the setattr: modify plugin was called).

%saveset name=MYNAME

Remembers the current set as MYNAME.

%webfile

Pulls a file from a URL and saves it to a file. The format is the file name to save it to, a comma and then the URL. Example:

  %webfile
  waymarks-train.gif,http://www.waymarking.com/images/cat_icons/train.gif

You can then refer to these files using webfile:waymarks-train.gif in %copy or %system commands.

%copy

Copy's a file from one place to another. Example format:

  %copy
  file1.loc,file2.loc

Or refering to a webfile previously pulled from a %webfile directive:

  %copy
  webfile:waymarks-train.gif,/some/path/to/waymarks-train.gif
%system

Run's a system command. webfile: prefixes within the command string will be replaced by paths to a stored %webfile.

%if CLAUSE
%else
%endif

These sections allow for variablity of what is done based on user input. CLAUSE is evaluated as perl code (returning a perl true or false response (eg, 1 or 0)) to determine what to do next. CLAUSE will be evaluated first in terms of parameteritized input. Thus:

  %print
  %if %[desire,1,type=checkbox]
  hello
  %else
  world
  %endif

Will print "hello" if the user clicks the check box (defaults to on) or "world" if the user does not. (They may also hand-specify the 'Desire' parameter as scriptname:desire=1 or equievelent).

Nesting is properly handled.

%foreach VAR value1 value2 ...
%endforeach

Allows repeated script sections with %{VAR} being replaced with a different value for each section.

  %foreach it 1 2 3 a b word
  %print
  This is it: %{it}
  %endforeach

Will output:

  This is it: 1
  This is it: 2
  This is it: 3
  This is it: a
  This is it: b
  This is it: word
%perl

Embeds perl into the script. $self is a reference to the master GeoDB object. Use this functionality only if you're an expert (and in desperate need).

  %perl leavewhitespace=1
%title

Names the script with a title.

  %title
  My super title
%introduction

Includes a paragraph in the top of the GUI screen when the script is run.

  %introduction
  This is how you use this screen


COMMAND LINE OPTIONS

-i STRING
--import-file=STRING

Import a file. File should be specified as type:file

-n STRING
--name=STRING

Comma separated names to assign to the objects in the file

-m STRING
--modify=STRING

Modify the search set before displaying or exporting

-e STRING
--export-file=STRING

Export a file. File should be specified as type:file

--execute-script=FILENAME
-x FILENAME

Run a script stored in FILENAME

Search Options:

-s STRING
--search=STRING

Search terms for geocaches

--limit=INTEGER

Maximum number of records to return for searches

-N STRING
--set-name=STRING

Set/Search Storage Name ('search:geoqo')

Display Options:

-l
--list-caches

List geocaches found in search

-S
--show-caches

Show details of geocaches found

-L
--show-logs

Show log messages in details output

-d STRING
--display=STRING

Display output thingies

--save
--save-changes

Save changes to the set to the DB

Database Options:

-t STRING
--db-type=STRING

Database Type (sqlite2, sqlite, mysql, postgres)

-H STRING
--db-host=STRING

Database Host (localhost)

-u STRING
--db-user=STRING

Database User (geoqo)

-p STRING
--db-password=STRING

Database Password

--db-name=STRING

Database Name (geoqo)

--db-flush

Delete the existing DB first

--db-port=INTEGER

Port number for the database

--setup-database

Initialize the database table structure

Configuration Options:

-c STRING
--config-file=STRING

Configuration File to read

-C
--no-config

Do not read any configuration file

--debug=INTEGER

Turn on debugging output

--test

Prints a bunch of test output that Yamar (or someone else) may ask you for if you have problems.

Help Options

-h

Display a help summary (short flags preferred)

--help

Display a help summary (long flags preferred)

--help-full

Display all help options (both short and long)

--version

Display the script version number.


CONFIGURING

GeoQO supports a configuration file where multiple types of things can be specified.

Command Line Options and Default

You can also store "always use this" options in a configuration file named ~/.geoqo/config. This file should be the option name on the left (single letter option if available, not longer ones) followed by the value you want after a space. EG to always use debugging and postgresql and the 'geo' database user:

  t postgresql
  u geo
  debug 5

Any option may be added to this file. Options on the command line will override options in this file (as you'd expect).

GUI Defaults

When using the auto-gui created screens, you can specify your own defaults for widgets created by geoqo modules or scripts using the "default" keyword. EG:

  default searchby Power Search

Will set the default search mechanism to the "Power Search" option. Knowing what keyword to use and what value to use generaly requires understanding how geoqo works at this point though (or you can ask Yamar in the #geoqo IRC channel).

Per-Screen GUI Defaults

You can also set defaults or for particular script screens. To set the default search type in the devices/cachemate script GUI screen:

  screen devices/cachemate searchby Power Search


Debugging

If you really want to see what geodb is doing internally, run with the --debug switch. In particuluar, "--debug 5" will print lots of interesting information. Too much. The higher the number the more you get.


ACKNOWLEDGEMENTS

The following people (geocachers) helped in useful ways with this program:

BlueNinja

Self proclaimed "test monkey". He tested lots of early verions and has caught various bugs as well and given me better usage ideas through his "why can't I do this" set of questions.

He was also the first person to get it working on Windows and has contributed vastly to the windows documentation.

ClayJar

Who won the renaming contest on IRC after SourceForge told me GeoDB was an internal reserved name:

  [03:38:13 pm] <ClayJar_SSH>Yamar: How about "Geoqo".  You'll have
  sole Google of that one, I imagine. You can pronounce it "ge-OH-ko",
  and "QO" is DB after ROT13.

For those that don't know, ROT13 is the cheap encryption mechanism that geocaching.com (and other places) use to encrypt their logs.

(ROT13 is used in many, many other ways too, and the first most popular usage of it was to encrypt potentially offensive material (ie, jokes) when posting to USENET news groups)

Planet

Planet nicely volunteered to proof-read a copy of this manual and sent me many wonderful suggestions about improving it.

jslagle

The first person to send me a code patch (implementing a better zip file import handler)! Yay! He's now a co-developer.

brdad

The first person to wade through what it takes to get the GUI working under windows.

lairsdragon

Submitted patches for the build system to make it more PREFIX friendly.

Zemmy

An early Windows test case for the installer components.


AUTHOR

Wes Hardaker <hardaker ATAT users.sourceforge.net>

AKA "Yamar" on Geocaching.com, IRC, and other places



SourceForge.net GeoQO / GeoDB Project