Skip to content

Commit 90975e7

Browse files
SurfooSurfoo
committed
update documentation
1 parent ba5d620 commit 90975e7

3 files changed

Lines changed: 242 additions & 38 deletions

File tree

‎README.md‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -76,20 +76,30 @@ $sdk = new GeocachingSdk($options);
7676
$response = $sdk->ping();
7777

7878
// Optional: Enable automatic token refresh
79-
use League\OAuth2\Client\Provider\Geocaching;
79+
use League\OAuth2\Client\Provider\Geocaching as OAuthProvider;
8080

81-
$oauthProvider = new Geocaching([
82-
'clientId' => 'your_client_id',
83-
'clientSecret' => 'your_client_secret',
84-
'redirectUri' => 'https://your-app.com/callback',
85-
'environment' => 'production',
81+
$oauthProvider = new OAuthProvider([
82+
'clientId' => 'your_client_id',
83+
'clientSecret' => 'your_client_secret',
84+
'redirectUri' => 'https://your-app.com/callback',
85+
'environment' => 'production',
8686
]);
8787

8888
$options->enableTokenRefresh([
89-
'user_id' => 'user_123',
90-
'storage' => $tokenStorage, // Your TokenStorageInterface implementation
89+
'reference_code' => 'PR12345', // User reference code
90+
'storage' => $tokenStorage, // TokenStorageInterface implementation
9191
'oauth_provider' => $oauthProvider,
9292
]);
93+
94+
// Or let the SDK create the OAuth provider automatically:
95+
$options->enableTokenRefreshWithCredentials([
96+
'reference_code' => 'PR12345',
97+
'storage' => $tokenStorage,
98+
'client_id' => 'your_client_id',
99+
'client_secret' => 'your_client_secret',
100+
'redirect_uri' => 'https://your-app.com/callback',
101+
'environment' => 'production',
102+
]);
93103
```
94104

95105
### Configuration Options

‎docs/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,4 @@ This folder collects the SDK documentation with examples for the Groundspeak Geo
77
- [Authentication & Tokens](./authentication.md) — work with access tokens, wire OAuth, and enable automatic refresh.
88
- [Configuration & HTTP Clients](./configuration.md) — understand runtime options, environments, and how to plug in custom PSR clients.
99
- [Reliability & Observability](./reliability.md) — enable structured logging, retries, and circuit breaking for resilient calls.
10-
- [API Usage by Domain](./api-usage.md) — call the main API areas (geocaches, users, adventures, trackables, lists, status) with documented examples.
10+
- [API Usage by Domain](./api-usage.md) — call all API areas (geocaches, geocache logs, log drafts, users, friends, adventures, lists, trackables, user waypoints, wherigo, geotours, HQ promotions, reference data) with documented examples.

‎docs/api-usage.md‎

Lines changed: 223 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@ $response = $sdk->searchGeocaches(['q' => 'traditional cache', 'take' => 10]);
77
$data = json_decode($response->getBody()->getContents(), true);
88
```
99

10+
Add per-request headers (e.g., culture or client identifiers) with the optional `$headers` argument on any method:
11+
12+
```php
13+
$sdk->getGeocache('GC123ABC', [], [
14+
'Accept-Language' => 'en-US',
15+
'X-Client' => 'my-app/1.2.3',
16+
]);
17+
```
18+
1019
## Geocaches
1120

1221
```php
@@ -22,16 +31,91 @@ $sdk->searchGeocaches([
2231
'take' => 25,
2332
]);
2433

34+
// Fetch multiple geocaches by reference codes
35+
$sdk->getGeocaches(['referenceCodes' => 'GC123ABC,GC456DEF']);
36+
37+
// Geocache images
38+
$sdk->getGeocacheImages('GC123ABC', ['take' => 10]);
39+
40+
// Users who favorited a geocache
41+
$sdk->getFavoritedUsersByGeocache('GC123ABC');
42+
43+
// Trackables currently in a geocache
44+
$sdk->getGeocacheTrackables('GC123ABC');
45+
2546
// Retrieve logs for a cache
26-
$sdk->getGeocacheLogs('GC123ABC', [
27-
'take' => 20,
28-
'skip' => 0,
47+
$sdk->getGeocacheLogs('GC123ABC', ['take' => 20, 'skip' => 0]);
48+
49+
// Personal note
50+
$sdk->updateGeocacheNote('GC123ABC', ['note' => 'Bring a pen.']);
51+
$sdk->deleteGeocacheNote('GC123ABC');
52+
53+
// Corrected coordinates (mystery/multi)
54+
$sdk->updateCorrectedCoordinates('GC123ABC', ['latitude' => 47.606, 'longitude' => -122.332]);
55+
$sdk->deleteCorrectedCoordinates('GC123ABC');
56+
57+
// User waypoints attached to a geocache
58+
$sdk->getGeocacheUserWaypoints('GC123ABC');
59+
60+
// Check final coordinates against a geocache solution
61+
$sdk->checkFinalCoordinates('GC123ABC', ['latitude' => 47.606, 'longitude' => -122.332]);
62+
63+
// Post bulk trackable logs on a geocache visit
64+
$sdk->setBulkTrackableLogs('GC123ABC', [
65+
['trackableCode' => 'TB1234', 'logTypeId' => 75],
66+
]);
67+
```
68+
69+
## Geocache Logs
70+
71+
```php
72+
// Post a found-it log
73+
$sdk->setGeocacheLog([
74+
'geocacheCode' => 'GC123ABC',
75+
'logTypeId' => 2, // 2 = Found it
76+
'loggedDate' => '2025-06-01T12:00:00',
77+
'text' => 'Great hide!',
2978
]);
3079

31-
// Update a personal note
32-
$sdk->updateGeocacheNote('GC123ABC', [
33-
'note' => 'Bring a pen and check the nearby trailhead.',
80+
// Fetch, update, delete a log
81+
$sdk->getGeocacheLog('GL123ABC');
82+
$sdk->updateGeocacheLog('GL123ABC', ['text' => 'Updated text.']);
83+
$sdk->deleteGeocacheLog('GL123ABC');
84+
85+
// Images on a log
86+
$sdk->getGeocacheLogImages('GL123ABC');
87+
$sdk->setGeocacheLogImages('GL123ABC', ['imageUri' => 'https://example.com/photo.jpg', 'description' => 'Cache photo']);
88+
$sdk->deleteGeocacheLogImage('GL123ABC', 'image-guid-here');
89+
90+
// Upvotes
91+
$sdk->getGeocacheLogUpvotes(['logReferenceCode' => 'GL123ABC']);
92+
$sdk->setGeocacheLogUpvotes('GL123ABC', 1); // upvoteTypeId 1 = Great Story
93+
$sdk->deleteGeocacheLogUpvotes('GL123ABC', 1);
94+
```
95+
96+
## Log Drafts
97+
98+
```php
99+
// Create and list drafts
100+
$sdk->setLogdraft([
101+
'geocacheCode' => 'GC123ABC',
102+
'logTypeId' => 2,
103+
'loggedDate' => '2025-06-01T12:00:00',
104+
'note' => 'Draft note',
34105
]);
106+
$sdk->getLogdrafts(['take' => 20]);
107+
108+
// Fetch, update, delete a draft
109+
$sdk->getLogdraft('LD123ABC');
110+
$sdk->updateLogdraft('LD123ABC', ['note' => 'Updated draft.']);
111+
$sdk->deleteLogdraft('LD123ABC');
112+
113+
// Promote a draft to a real log
114+
$sdk->promoteLogdraft('LD123ABC', ['text' => 'Final log text.']);
115+
116+
// Draft images
117+
$sdk->setLogdraftImage('LD123ABC', ['imageUri' => 'https://example.com/photo.jpg']);
118+
$sdk->deleteImageFromLogdraft('LD123ABC', 'image-guid-here');
35119
```
36120

37121
## Users
@@ -40,12 +124,39 @@ $sdk->updateGeocacheNote('GC123ABC', [
40124
// Profile with optional query params (e.g., fields or cultureCode)
41125
$sdk->getUser('PR12345', ['fields' => 'referenceCode,username,memberType']);
42126

127+
// Multiple users
128+
$sdk->getUsers(['usernames' => 'alice,bob,charlie']);
129+
43130
// A user's logs and lists
44131
$sdk->getUserGeocacheLogs('PR12345', ['take' => 50]);
45132
$sdk->getUserLists('PR12345');
46133

47-
// Multiple users in one call
48-
$sdk->getUsers(['usernames' => 'alice,bob,charlie']);
134+
// User images and souvenirs
135+
$sdk->getUserImages('PR12345', ['take' => 10]);
136+
$sdk->getUserSouvenirs('PR12345');
137+
138+
// Privacy settings
139+
$sdk->getUserPrivacySettings('PR12345');
140+
141+
// Users who opted out of friend searches
142+
$sdk->getOptedOutUsers(['take' => 10]);
143+
```
144+
145+
## Friends
146+
147+
```php
148+
// List friends and their cache logs on a specific geocache
149+
$sdk->getFriends(['take' => 20]);
150+
$sdk->getFriendsGeocacheLogsByGeocache('GC123ABC');
151+
152+
// Friend requests
153+
$sdk->getFriendRequests();
154+
$sdk->sendFriendRequest(['userCode' => 'PR99999']);
155+
$sdk->acceptFriendRequest('request-id-here');
156+
$sdk->deleteFriendRequest('request-id-here');
157+
158+
// Remove a friend
159+
$sdk->deleteFriend('PR99999');
49160
```
50161

51162
## Adventures
@@ -60,19 +171,40 @@ $sdk->searchAdventures([
60171

61172
// Get full details for one adventure
62173
$sdk->getAdventure('adventure-guid-here');
174+
175+
// Search adventure stages
176+
$sdk->searchAdventuresStages([
177+
'adventureId' => 'adventure-guid-here',
178+
'origin' => '45.5152,-122.6784',
179+
]);
63180
```
64181

65182
## Lists
66183

67184
```php
185+
// Create a new list
186+
$sdk->setList([
187+
'name' => 'My bucket list',
188+
'description' => 'Caches I want to find.',
189+
'typeId' => 2, // 2 = bookmark list
190+
'isPublic' => true,
191+
]);
192+
68193
// Get a bookmark list and its caches
69194
$sdk->getList('LSTABCDE', ['fields' => 'referenceCode,name,geocaches']);
70195
$sdk->getGeocacheList('LSTABCDE', ['take' => 50]);
71196

72-
// Add caches in bulk
73-
$sdk->setBulkGeocachesList('LSTABCDE', [
74-
'geocacheCodes' => ['GC123ABC', 'GC456DEF'],
75-
]);
197+
// Update or delete a list
198+
$sdk->updateList('LSTABCDE', ['name' => 'Renamed list']);
199+
$sdk->deleteList('LSTABCDE');
200+
201+
// Add/remove caches
202+
$sdk->setGeocacheList('LSTABCDE', ['geocacheCode' => 'GC123ABC']);
203+
$sdk->setBulkGeocachesList('LSTABCDE', ['geocacheCodes' => ['GC123ABC', 'GC456DEF']]);
204+
$sdk->deleteGeocacheList('LSTABCDE', 'GC123ABC');
205+
206+
// Download a pocket query as a ZIP file
207+
$sdk->getZippedPocketQuery('PQ123ABC', '/tmp');
76208
```
77209

78210
## Trackables
@@ -81,37 +213,99 @@ $sdk->setBulkGeocachesList('LSTABCDE', [
81213
// Trackable details and journey
82214
$sdk->getTrackable('TB1234');
83215
$sdk->getTrackableJourneys('TB1234', ['take' => 10]);
216+
$sdk->getTrackableImages('TB1234');
217+
$sdk->getTrackableLogs('TB1234');
218+
219+
// User's trackables
220+
$sdk->getUserTrackables(['take' => 20]);
84221

85-
// Post a log with an image
86-
$sdk->setTrackableLog('TB1234', [
87-
'logTypeId' => 14, // e.g., "Retrieve It"
222+
// Geocoin types
223+
$sdk->getGeocoinTypes();
224+
225+
// Trackable logs CRUD
226+
$sdk->setTrackableLog([
227+
'trackableCode' => 'TB1234',
228+
'logTypeId' => 14, // e.g. "Retrieve It"
88229
'text' => 'Picked up at the event.',
89230
'geocacheCode' => 'GC123ABC',
90231
]);
91-
$sdk->setTrackableLogImages('TB1234', [
92-
'imageUri' => 'https://example.com/pickup.jpg',
93-
'description'=> 'Pickup proof',
232+
$sdk->getTrackableLog('TL123ABC');
233+
$sdk->getUserTrackableLog(['take' => 20]);
234+
$sdk->updateTrackableLog('TL123ABC', ['text' => 'Updated text.']);
235+
$sdk->deleteTrackableLog('TL123ABC');
236+
237+
// Trackable log images
238+
$sdk->setTrackableLogImages('TL123ABC', ['imageUri' => 'https://example.com/pickup.jpg', 'description' => 'Pickup proof']);
239+
$sdk->getTrackableLogImages('TL123ABC');
240+
$sdk->deleteTrackableLogImage('TL123ABC', 'image-guid-here');
241+
```
242+
243+
## User Waypoints
244+
245+
```php
246+
// List all user waypoints across caches
247+
$sdk->getUserWaypoints(['take' => 50]);
248+
249+
// Create, update, delete a waypoint
250+
$sdk->setGeocacheUserWaypoint([
251+
'geocacheCode' => 'GC123ABC',
252+
'isCorrectedCoordinates' => false,
253+
'coordinates' => ['latitude' => 47.606, 'longitude' => -122.332],
254+
'description' => 'Parking area',
94255
]);
256+
$sdk->updateUserWaypoint('UW123ABC', ['description' => 'Updated parking.']);
257+
$sdk->deleteUserWaypoint('UW123ABC');
258+
```
259+
260+
## Wherigo
261+
262+
```php
263+
// Fetch a Wherigo cartridge by GUID
264+
$sdk->getWherigoCartridge('cartridge-guid-here');
95265
```
96266

97-
## Status, Reference Data, and Health Checks
267+
## Geotours
268+
269+
```php
270+
// List all geotours
271+
$sdk->getGeotours(['take' => 10]);
272+
273+
// Get a specific geotour and its geocaches
274+
$sdk->getGeotour('GT123ABC');
275+
$sdk->getGeotourGeocaches('GT123ABC', ['take' => 50]);
276+
```
277+
278+
## HQ Promotions
279+
280+
```php
281+
// Get promotion metadata (banners, events, etc.)
282+
$sdk->getHQPromotionsMetadata();
283+
```
284+
285+
## Reference Data & Statistics
98286

99287
```php
100288
// API health
101289
$sdk->ping(); // alias: status()
102290

103-
// Reference data for filters
291+
// Convert a numeric ID to a reference code
292+
$sdk->getReferenceCodeFromId(['id' => 12345, 'type' => 3]);
293+
294+
// Difficulty/terrain statistics for the authenticated user
295+
$sdk->getDifficultyTerrainStatistics();
296+
297+
// Lookup tables for filters and log forms
104298
$sdk->getGeocacheTypes();
105299
$sdk->getGeocacheLogTypes();
300+
$sdk->getGeocacheSizes();
301+
$sdk->getGeocacheStatuses();
302+
$sdk->getAttributes();
303+
$sdk->getMembershipLevels();
304+
$sdk->getTrackableLogTypes();
305+
$sdk->getGeocoinTypes();
306+
307+
// Geography
106308
$sdk->getCountries();
309+
$sdk->getStates();
107310
$sdk->getStatesByCountry(2); // e.g., USA
108311
```
109-
110-
Add per-request headers (e.g., culture or client identifiers) with the optional `$headers` argument on any method:
111-
112-
```php
113-
$sdk->getGeocache('GC123ABC', [], [
114-
'Accept-Language' => 'en-US',
115-
'X-Client' => 'my-app/1.2.3',
116-
]);
117-
```

0 commit comments

Comments
 (0)