GSAK API Intro

that’s geek for:

Introduction to using GSAK to access geocaching.com for data

Heiner Lieth (a.k.a. Hynr)

Davis, California, USA

This educational session:

I assume you already know: What GSAK is and that it is something you have use for How to use it for data management – filtering, exporting,..

Here we focus on “Geocaching.com access”:

Introduction to getting data from Geocaching.com

Geocaching data about geocaches flows to your GSAK installation: Type it in yourself (NO!!!!!!!!!!! – just because you can,

does not mean you should!) Click on GPX button on individual cache pages. Use “Pocket Query” tool at geocaching.com to have them

create a file for you Sent to your email account (limit: 500 caches per file) Download resulting gpx file from their website (limit 1000 caches

per file)

Use the geocaching.com API

Various names mean the same thing:

GSAK menu: “Geocaching.com access” Also known as: “Geocaching.com API” “API” means “applications programmer’s interface”

For all practical purposes, what it means: Direct link to the geocaching.com data servers Get data from Geocaching.com to your computer Move data from your computer to the servers.

How you use data

Before you go geocaching: Get data so you can analyze it on the map, put it into the

GPS, etc. After you visited some geocaches: Publishing a log Give your opinion on how great the cache is by issuing a

“Favorite Point” Log information about trackables Attach a photo

Data flow from Geocaching.com to you:

A few functions have been provided by Groundspeak to get information directly from the servers to your GSAK database. Generally you will still need to browse to the website for various things.

Most important API functions that move data to you: Status update (archived, temporarily unavailable,

available) Get cache information with up to the 30 most-recent

recent logs each. Refreshing cache data that you already have

(Aside: limitations of PQs is that you get no information about status of archived caches!)

Data flow from Geocaching.com to you:

A few functions have been provided by Groundspeak to get information directly from the servers to your GSAK database. Generally you will still need to browse to the website for various things.

Most important API functions that move data to you: Status update (archived, temporarily unavailable,

available) Get cache information with up to the 30 most-recent

recent logs each. Refreshing cache data that you already have

(Aside: limitations of PQs is that you get no information about status of archived caches!)

Differences between PQ-data and API-data You would think that these two data sources would

provide you with the same data. You would be wrong!

Differences: (more info at GSAK Forum)

“Favorite Points” – only with API PQs: 5 logs/cache; API: up to 30 (more with Get Logs) “Geocaching.com Corrected Coords” are sent as posted

coords in PQs (without indication that they are not the posted coords), not sent with API – causes problems if you want to manage data. If you use GSAK you should avoid using geocaching.com corrected coords.

Commonality: The data format is generally “gpx”

“Full” vs “Lite” data

In some cases you can select whether you want all the data for a geocache (“Full”) or just some summary data (“Lite” – similar to data in Loc files format)

Note “Full” data request takes much longer Quota for Full data is 6000 geocaches per day while

quota for Lite data is 10000 geocaches per day

Get Geocaches

Purpose: obtain geocache gpx data for Individual GCcode A circular region A rectangular region

Geocaching data that you get this way: Both short and long descriptions, hints, dif, ter, location Favorite points Most-recent logs (max 30)

When you use this feature, GSAK will communicate interactively with the server until it has all the desired/allowed information

Get Geocaches – Basic Tab:

Get Geocaches

There are limits: 6000 full descriptions (premium membership needed) per

24 hour period. Your patience – if you ask for 6000 caches with 30 logs

then that represents huge amounts of data which will take a long time (up an hour?)

GSAK creates batches of gpx files which it then loads. So note that this is tricky: you have to set up Load Settings

before you can use this function

Load Dialog settings

Note that all dialogs can be saved so you can rapidly select settings for particular

For loading gpx files you will want to save settings with a name of your choice (here “NZ_Quiet”)

Get Geocaches Let’s look at both dialogs at the same time. Note that

the folder locations (where the temporary gpx files are stored) MUST match.

Get Geocaches Note the match And be sure the

database is your desired data destination

Get Geocaches As you wait for GSAK to finish data retrieval from

geocaching.com you see a progress meter (but you have no clue how long it will take)

Data will be in gpx files – GSAK loads these for you if you set the dialogs correctly

Refresh Cache Data

This command assumes that you already have geocaching data in the selected database and want to refresh the data for those geocaches

Shares data limits with “Get Geocaches” (<30 logs) Set up Load dialog settings before (just as with Get

Geocaches – I suggest you use the same temporary gpx files folder for both functions)

Suggestion: This function is great for doing a quick update of caches

before you go on a cache run – request just a few logs per cache (depending how recent your data already are).

Refresh

Again: match dialogs And verify destination DB

Refresh

Again – after you click “OK” – it will take some time to complete this data transfer using gpx files.

Status check

This does not involve gpx data

Sets Available/Archived status (only)

Data flow to Geocaching.com:

Most important API function that moves data geocaching.com: Publish logs (submitting “Found It”, “Write Note”,… logs) Along with the logs also upload Favorite points Photos with captions Trackable logs

Publish Logs

Ways of publishing geocaching.com logs Interactively at the web site using the “Log your visit”

link on cache page Fieldnotes file out of GPS devices – upload to

geocaching.com and then process the list using the web page

Load/Edit Fieldnotes file into GSAK and process there, then have GSAK submit each log through the API

Since this presentation is just about the API, I will focus only on the last method

Publish Logs with GSAK API

Note that there are various features to be aware of: Templates You can set these up and they are then applied You can have a different template for each type of log

Source of logs Fieldnotes files out of GPSrs Usernotes in GSAK Simply blank logs for all the caches in the display grid

Trackables, Favorite Points

Publish Logs - Overview of the process:

1. If you have draft logs in a Fieldnotes file, then load these into the Publish Logs dialog (with Fetch from File or GPSr); otherwise filter caches in database for which you want to submit a log – “Fetch”

2. Then process each to: edit a log, apply templates, make other choices (favorite points, images, trackables).

3. Review to make sure you are ready to publish 4. Publish

Publish Logs - Let’s go through it in detail: 1. Attach GPSr to computer 2. Geocaching.com access, Publish Logs

Publish Logs 1. Attach GPSr to computer 2. Geocaching.com access, Publish Logs 3. Tricky part: Right-click in pale-yellow area to Fetch

Publish Logs 4. See list of caches for which you can now prepare a log. Name missing means: No match in current database Matched in current database

5. Edit log one-by-one; as you do you see an off-line cache page for each.

Here you fix up each log exactly as you want it, with images, trackables, etc

6. Once you are done: Click on one of the Publish buttons to upload the logs to

geocaching.com (note that this is not reversable – make sure you have the logs right at this point and that you have API access set for your geocaching name)

Note: records in the current database are marked “Found” for all geocaches where you published a “Found it” log

Download Pocket Queries

Pocket Queries (PQs) are set up and scheduled to run at geocaching.com (requires premium membership).

Once the results from a PQ are available, you can get these into your computer in various ways – one way is the API

Download Pocket Queries With the GSAK API “Download Pocket Queries” function you can download the files into GSAK in one step. (Premium Membership required; also this only works if you have an internet connection)

Again: Use Load Dialog Settings ALSO: Match folder names on dialogs

Download Pocket Queries

Note: the MyFinds PQ results cannot be loaded with the API!

Get Logs

If you need just the logs for geocaches, you can use this function.

Used by some geocachers to get all the logs for caches they own (part of generating statistics)

Note that this function has limitations (hourly volume constraints) – you would not be able to get all the logs for all caches in even a small database

Other elements of GSAK’s “Geocaching.com Access”

Update user information… Add to bookmark list... Get available balances Get another access token Here you can indicate a userid; this then communicates

with geocaching.com to confirm that you authorized If successful, then your userid is added to the list below

Remove account Reverse of the above step

API in GSAK Macros

Most of the menu items is also implemented in the GSAK macro language as macro commands. <end of presentation>

If you want a copy of this as pdf file, then please send request to: Heiner.Lieth@SBCglobal.net