A Python API and CLI client for GaiaGPS. I wrote this for myself, but it may be useful for others. Gaia does not have a published API, so this was developed by reverse engineering the browser client and thus may be incomplete or poorly behaved. It is possible to use this to put undue strain on gaiagps.com, so please be judicious with its use. This client is not supported or blessed by Gaia, so do not complain about it to them or ask them for help.
For complete instructions, see the installation docs. For advanced users, the quickstart is:
$ sudo python3 -mpip install git+https://github.com/kk7ds/gaiagpsclientFor more information on usage, see the full documentation. Below is a quick introduction to get you started. For more common usage recipes, check out the cookbook.
As of 2023, the only way to authenticate the client to gaiagps is to login with the browser and extract a sessionid cookie. Use a browser extension or the development tools to copy the sessionid cookie value from a logged-in session. Pass that to the command-line tool like this:
$ gaiagps --sessionid asd9sdjd8errr4n8ssff35sff test
Success!If you see the "Success!" message then you are logged in. Once the session with gaiagps expires, you will need to repeat the procedure.
The available high-level commands are displayed with --help:
$ gaiagps --help
usage: gaiagps [-h] [--user USER] [--pass PASS] [--debug] [--verbose]
{waypoint,folder,test,tree,track,upload} ...
Command line client for gaiagps.com
positional arguments:
{waypoint,folder,test,tree,track,upload}
waypoint Manage waypoints
folder Manage folders
test Test access to Gaia
tree Display all data in tree format
track Manage tracks
upload Upload an entire file of tracks and/or waypoints
optional arguments:
-h, --help show this help message and exit
--user USER Gaia username
--pass PASS Gaia password (prompt if unspecified)
--debug Enable debug output
--verbose Enable verbose output
Help per-command is displayed the same way:
$ gaiagps waypoint --help
usage: gaiagps waypoint [-h]
{add,remove,move,rename,export,list,dump,url,coords}
...
This command allows you to take action on waypoints, such as adding, removing,
and renaming them.
positional arguments:
{add,remove,move,rename,export,list,dump,url,coords}
add Add a waypoint
remove Remove a waypoint
move Move to another folder
rename Rename
export Export to file
list List
dump Raw dump of the data structure
url Show direct browser-suitable URL
coords Display coordinates
optional arguments:
-h, --help show this help message and exit
$ gaiagps waypoint add --help
usage: gaiagps waypoint add [-h] [--existing-folder EXISTING_FOLDER]
[--new-folder NEW_FOLDER]
name latitude longitude [altitude]
positional arguments:
name Name (or ID)
latitude Latitude (in decimal degrees)
longitude Longitude (in decimal degrees)
altitude Altitude (in meters
optional arguments:
-h, --help show this help message and exit
--existing-folder EXISTING_FOLDER
Add to existing folder with this name
--new-folder NEW_FOLDER
Add to a new folder with this name
Here are some example common operations to demonstrate usage:
# Add a waypoint by coordinates (i.e. specifying a latitude and longitude)
$ gaiagps waypoint add 'My Campsite' 45.123 -122.9876
# Show the waypoints so far
$ gaiagps waypoint list
+--------------------------------+----------------------+------------------+
| Name | Updated | Folder |
+--------------------------------+----------------------+------------------+
| My Campsite | 19 Apr 2019 03:41:53 | |
+--------------------------------+----------------------+------------------+
# Create a folder and move our waypoint into that folder
$ gaiagps folder add 'Camping Trip'
$ gaiagps waypoint move 'My Campsite' 'Camping Trip'
$ gaiagps waypoint list
+--------------------------------+----------------------+------------------+
| Name | Updated | Folder |
+--------------------------------+----------------------+------------------+
| My Campsite | 19 Apr 2019 03:41:53 | Camping Trip |
+--------------------------------+----------------------+------------------+
# Upload a GPX file with a track inside
$ gaiagps upload --existing-folder 'Camping Trip' myhike.gpx
$ gaiagps track list
+--------------------------------+----------------------+------------------+
| Name | Updated | Folder |
+--------------------------------+----------------------+------------------+
| Cool Hike | 19 Apr 2019 03:42:17 | Camping Trip |
+--------------------------------+----------------------+------------------+
# Dump all data in Gaia account (assuming more has been added), like a filesystem
$ gaiagps tree
/
├── My Trip/
├── [W] Backup camp spot
├── [W] Backup camp spot in gravel lot
├── [W] Barnhouse Campground
├── [W] Blue Basin Trail Parking
├── [W] Camp spot
├── [W] Cell coverage
├── [W] Ochoco Divide Campground
├── [W] Priest Hole
├── [W] Shoe tree
├── [T] Burnt Ranch and Twickenham to Priest Hole
├── [T] Ochoco Hwy to Priest Hole via Twickenham
├── [T] Priest hole to OR218
├── My Hike/
├── planning/
└── [T] Cool Trail
└── [W] My House
Tests are split into unit and functional groups. Unit tests can be run in isolation; functional tests run against gaiagps.com itself and require credentials to be set in the environment to run. As functional testing has the potential to generate potentialy-unwanted load on Gaia's servers, try to avoid running those more than necessary.
Testing and building docs requires tox:
$ pip install tox $ tox -e style,unit,doc
Docs will be built and available in doc/build/index.html, or you can read them at RTD.
