Geocaching Buddy (GCBuddy) API

The geocaching buddy API makes it possible to transfer a cache you have somehow available in your app (e.g. after a GPX import) to GCBuddy using one specially crafted URL.
Note that these URL's can even be included on a regular web pages so creators of a multi-cache can make it simple for users to transfer the initial information to an iPhone running GCBuddy. Users can browse to the description on their iPhone or iPod touch and click on the special link to create that cache in GCBuddy including all information included in that link.

A convenient way to create these special URL's is to enter information in GCBuddy and then mail a backup to some email address. The special URL included in that mail contains all entered information and can be copied/pasted to a web page.

Launch Geocaching Buddy

Open the url "gcbuddy://" in a browser or via code to launch GCBuddy.

NSURL* url = [NSURL URLWithString:@"gcbuddy://"];
[[UIApplication sharedApplication] openURL:url];

Add a new cache to GCBuddy (or merge new info into an existing cache)

gcbuddy://add/cache?<KEY>=<VALUE>&<KEY>=<VALUE> etc.

Where KEY and VALUE are RFC 2396 percent escaped strings **. Possible KEY's and VALUE's are described below. The first two KEY's are required, the rest is optional. The values below are not yet percent escaped.

KEY VALUE
id The GC code or OC code: examples are GC12345 or OC12345
name The name of the cache
   
type multi or traditional or puzzle or earth (default is multi if type is not specified)
parking latitude;longitude
Both values must be floating point values e.g. parking=51.123456;-5.123456
Negative latitude means S, negative longitude means W
wp1 latitudeformula;longitudeformula;Arrived;description
latitude and longitude formula's have a degreees minutes formula format (like in the app itself) but are cleverly cleaned so the examples shown below will all work. Arrived; at the start of the description is stripped off the description and sets the waypoint visited flag to signal that this waypoint was visited. The description is the information shown at a waypoint.
wp2 51º12.138;-5º12.145;Arrived;A=number of big stones, B=first digit of phone number on sign
wp3 51 12.C*A+B;E 5 12.CCC;find a small container here (space after first numeric value counts as degrees symbol)
wp4 project;D;meter;120º;E=house number
This is the format for a projection from the previous waypoint. Distance is D (value or formula), units is meter or feet, angle can be in degrees or as a formula.
wp5 offset;(A*B);(C+D);Find wp5 location on post
This is the format for an offset from the previous waypoint.
wp10 wp10=;;this implicitly creates wp's 6,7,8 and 9 as empty waypoints (they take over the first digits of the previous waypoint)
etc. Add as many waypoints as required
xwp1

Type;Name;fromWaypointName
The number after xwp is the number of the waypoint in the waypoint list to be modified. Numbering starts at 1.
Type can be 0 (normal waypoint), 1 (Parking), 2 (POI), 3 (Other waypoint)
Name is the new name for this waypoint.
fromWaypoint is the name of the waypoint to be used as source for the projection. If empty the previous waypoint is used.

clA 5
The first two letters cl in a KEY indicate a clue value or formula
clF (A+B)
etc. Clues can be entered in any order, not all clues have to be entered
cache 51º12.(C+D+E);-5º1A.BDE;find the cache
Special waypoint for the cache itself, same format as wp
log the log notes as text
lastfounddate Date string in the format yyy-MM-dd HH:mm with the date/time of last waypoint visited YES/NO switch for this geocache (kind of latest activity). This date is shown in the geocache table view.
hint text for the hint
description HTML description of the cache. Picture URL's can be included and will be cached on the device for off-line viewing.
sender URL scheme string for returning to the sender application. This can include some cache id to show this cache again in the sender app. The exact format and contents are up to the sending app.

**: I personally use the functions below to escape/unescape strings:

@implementation NSString (URLEscaping)
- (NSString *)urlEscape {
   NSString *unsafe = @" <>#%'\";?:@&=+$/,{}|\\^~[]`-_*!()";
   return [NSMakeCollectable(CFURLCreateStringByAddingPercentEscapes(kCFAllocatorDefault, (CFStringRef)self, NULL, (CFStringRef)unsafe, kCFStringEncodingUTF8)) autorelease];
}
- (NSString *)urlUnescape {
   // The + sign is kind of special, it is a space
   NSMutableString *result = [[self mutableCopy] autorelease];
   [result replaceOccurrencesOfString:@"+" withString:@" " options:NSLiteralSearch range:NSMakeRange(0, [result length]) ];
   return [result stringByReplacingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
}