BCaching Field Notes API

The bcaching API is intended for use by mobile geocaching apps to retrieve geocache data and have access to a large repository of geocache data without needing to store it all on the device itself.

The Query API can be found here.

The Notes API is new and currently only in the test environment (http://test.bcaching.com/…). It allows a mobile app to upload field notes (finds, dnfs, and notes). When used in combination with the BCaching Query API it can be used to prevent found caches from being re-downloaded in subsequent BCaching queries. Field notes uploaded to BCaching can also be downloaded from BCaching for use in uploading to geocaching.com.

Request format is an HTTP POST or PUT to the following URL (format is nearly identical to the query api):
http://(www|test).bcaching.com/api/notes.ashx?u=<username>&a=add&time=<current-time>&sig=<signature>
where:

• username is a valid bcaching.com username (UrlEncoded)
• current-time is the current mobile device time in “java” milliseconds (i.e. java.util.Date.getTime)
• signature is an md5 hash of the querystring plus an md5 hash of the bcaching user’s password.

The posted request content format is identical to the geocaching fieldnotes text file format. A utf-8 text file, with comma-separated values including waypoint, time, log-type, and text. Multiple notes can be posted when separated by newlines.

<waypoint>,<time>,<log-type>,”<text>”

where:

• <waypoint> is the geocaching GC#
• <time> is the complete log date and time in UTC format. For example, 2009-11-25T22:37:55Z. The time may also be expressed in local time with a time zone offset instead of the letter Z.
• <log-type> is a valid field note log type:
  • Found it
  • Didn’t find it
  • Write note
  • Attended
  • Webcam Photo Taken
  • Private note (bcaching note only, won’t be exported)
• <text> is the log text. Note that it is surrounded by double-quotes. It can also contain newlines inside the double-quotes and those newlines will not be treated as an end-of-record character but part of the note text.

BCaching API

The bcaching API is intended for use by mobile geocaching apps to retrieve geocache data and have access to a large repository of geocache data without needing to store it all on the device itself. Response data for all requests except for “login” is in the standard GPX format. All query results are restricted to those that are accessible by the authenticated user.

Request format is
http://(www|test).bcaching.com/api/q.ashx?u=<username>&{{REQUEST}}&time=<current-time>&sig=<signature>
where:

• username is a valid bcaching.com username
• current-time is the current mobile device time in “java” milliseconds (i.e. java.util.Date.getTime) or equivalent
• signature is an md5 hash of the querystring plus an md5 hash of the bcaching user’s password.

{{REQUEST}} can be one of the following:

• Verify login only: a=login
  Does nothing more than return success or failure based on the validation of the username password/hashword.

• Find nearest caches (Summary): a=find&lat=<latitude>&lon=<longitude>&find=<find>&maxdistance=<max-distance>&maxcount=<max-count>
  Returns summary-only gpx data — with no short or long descriptions, extra waypoints, logs, etc.

   

  • latitude is the latitude in signed degree decimal form i.e. 40.123456
  • longitude is the longitude in signed degree decimal form i.e. -74.987654
  • find is a URL-encoded string to search for caches by waypoint# (with or without the GC prefix) or partial name match.
  • max-distance is optional and specifies the maximum distance in degrees. Default is 0.3 – about 30 miles
  • max-count is optional and specifies the maximum number of nearest caches to return in the gpx data. Default is 50.

• Get cache detail: a=detail&ids=<cache-id-list>&desc=<description-mode>&wpts=<wpts>&logs=<logs>&tbs=<tbs>
  Returns detailed gpx data for one or more caches

   

  • cache-id-list is a comma-separated list of cache ids (not waypoint numbers). Cache ids are included in the summary gpx request.
  • description-mode indicates what form to send the description and can be one of the following:
    • none: neither short nor long description is included
    • short: short description is included, converted to text if was html
    • long: short and long description are included, converted to text they were html
    • html: full original short and long descriptions are included
  • wpts is a flag indicating whether or not additional waypoints should be included: 0 = no waypoints (default), 1 = include waypoints
  • logs is the maximum number of logs to include: 0 = none (default), 1 or more indicates the maximum number
  • tbs is a flag indicating whether or not cache inventory should be included: 0 = no waypoints (default), 1 = include TBs

• Get nearest caches (Detail): a=nearest&maxcount=<max-count>&desc=<description-mode>&wpts=<wpts>&logs=<logs>&tbs=<tbs>
  • max-count is optional and specifies the maximum number of nearest caches to return in the gpx data. Default is 30.
  • all other parameters (desc, wpts, logs, tbs) are identical to Get cache detail section.

Server Outage

The hosting provider for bcaching.com is experiencing issues with the database server and is actively working to bring it back online.

I will post updates here as they become available.

15:15 MST: Root cause was an issue with the database server RAID hardware (guess it was hardware related after all!) The solution involved RAID card replacement, RAID and Motherboard BIOS updates, and a full filesystem checkdisk. Although the site is back online, the DB server is running a RAID rebuild which may slow performance somewhat.

15:10 MST: Server is coming back online now.

14:50 MST: Doesn’t appear to be a hardware error. There was disk corruption error in a database log file (not the bcaching database).

BCaching Release 0.6

The latest release has been completed and includes some cool new features including Custom Waypoints, Desktop Map “Universal Search”, Mobile Coordinates Conversion, Geolocation support, and more!

See the forum post for full details

Upcoming Release

I’ve been busy working on a bunch of features lately so the upcoming release is a bit more significant in scope than earlier ones have been. As a consequence the chance of bugs and issues associated with the release are increased as well.

Unfortunately my testing team currently consists of … well, myself and I would appreciate any help I could get from a few real users before I unleash a big mess on everyone. So if you would be interested in participating in some pre-release testing, jump over to the forum post for more details.

BCaching Release 0.5.1

This release fixes a couple of GPX file export issues that were causing problems with CacheBerry and BlackStar Navigation.

There is also a new GPX link on the mobile Nearest Caches page that will export geocache data for up to 20 nearest caches at once. If CacheBerry is installed it will process the GPX export automatically without need for an intermediate save.

There are a few other minor changes. Full details are on the forums.

bcaching or www.bcaching?

If you’re using “http://bcaching.com” instead of “http://www.bcaching.com” your browser will be redirected to the www version from now on. You will probably need to login again the first time it happens. Please update any of your bookmarks to use the www. version instead.

Server Outage

You may have noticed BCaching is down Saturday morning (the worst possible time?). The hosting provider had some scheduled maintenance this morning that was supposed to be relatively short but they ran into some unforeseen difficulties. Rest assured they are working to restore the server as soon as possible. I apologize for the inconvenience.

- Update 5:30 pm

Yes, the site is still down. Turns out there was a RAID disk controller failure during the migration from the old disks to the new disks (the new disks were the scheduled maintenance). When the controller failed it caused some corruption and the only way to get the system back up and running is with a “bare metal restore”. As of 3pm MST it had been running for over 6 hours and was 87% complete.

- Update 6:30 pm

And it’s back!! They are proceeding with the disk migration which may cause things to respond a little slower than usual but everything should be functional again.  We cached all day **without** bcaching… it was painful.

Puzzle Solving 101

Here’s a great series of Puzzle Caches by ePeterso2 in a lesson format. The location is Ft. Lauderdale, Florida, but you can still solve them remotely and post a note that you did it. Maybe you’ll even be in Ft. Lauderdale at some point and can find them too. Either way they’re good practice for solving puzzles no matter where you are.

Garmin Custom Waypoint Symbols

You can use BCaching to send geocaching waypoints to your Garmin device using custom geocaching waypoint symbols that differentiate cache type (Traditional, Multi-Cache, Mystery Cache, Letterbox, etc.) using the following symbol set:

First you must load the custom symbols onto your device (see below), then to use the custom symbols, go to the BCaching Desktop Map View, find the location you want to use as the center of the geocache data to load. Click [Send to Garmin Device] at the bottom of the page, then choose [Custom Waypoint Symbols] and follow the rest of the instructions on that page to finish.

Note that using Custom symbols will limit the Geocaching “functionality” built into some Garmin devices since only one symbol can be designated as a  “Geocache” that can be marked “Found”. If you want to retain that functionality for all geocache types then don’t use this feature. If you want to designate one of the custom symbols as a Geocache (such as the symbol for Traditional since they’re the most common), use the the Geocache Setup function on your device (on the 60CSx: Find => Geocache => Menu => Geocache Setup) and change the Find symbol.

Loading Symbols onto your Garmin Device

1. To load the custom symbols into your Garmin device, you must first download and install Garmin’s xImage utility (for Windows 2000 or later only).
2. Then download the Custom Waypoint Symbols ZIP file and extract them to a temporary folder on your computer.
3. Connect your Garmin device to your computer and turn it on.
4. Run the xImage program and click [Next] on the Welcome page.
5. On the Device Settings page, click [Find Device] to identity and select your device, then click [Next].
6. Click [Send images to the GPS] and click [Next].
7. Click [Select All] to highlight all Waypoint Symbols then click [Next].
8. Browse for and select the Custom Waypoint Symbols folder from where you extracted the ZIP file and click [OK]. xImage will then send the images to your device.
9. Click [Finish] to exit.