The geocaching buddy API makes it possible to transfer a cache you have somehow available in your app 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.
Open the url "gcbuddy://" in a browser or via code to launch GCBuddy.
NSURL* url = [NSURL URLWithString:@"gcbuddy://"];
[[UIApplication sharedApplication] openURL:url];
You can specify a comma separated list of cache codes from geocaching.com and/or the various opencaching sites. All caches will be downloaded into the main (offline) cache list. If the cache is already present in this list, new information will be merged in the existing cache.
gcbuddy://add/caches?codes=GC12345,OC12345 etc.
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 |
| 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))];
}
- (NSString *)urlUnescape {
// The + sign is kind of special, it is a space
NSMutableString *result = [self mutableCopy];
[result replaceOccurrencesOfString:@"+" withString:@" " options:NSLiteralSearch range:NSMakeRange(0, [result length]) ];
return [result stringByReplacingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
}