Introduction

The Geocaching API is designed to give developers access to Geocaching.com data and enhance the geocaching community experience. The API uses a RESTful approach and json data to make consuming the service simple and familiar. Partners who are accepted into the API program will receive a test and live token. The test token will allow our partners to play with the API without affecting live data. Once comfortable moving forward to live data, you may request a live token. You will need to provide access to your application to Geocaching HQ so that we may review it before receiving a live token.

As an API partner:

Authorization

The API uses OAuth 2.0's authorization code grant flow to authorize you to access Geocaching.com data on behalf of your app/site user. The OAuth process uses simple steps to authorize the application and allow the end user to grant your app/site permission to access their data.

The API also supports PKCE use which protects against authorization code interception attacks. You can implement PKCE as part of the authorization code grant by generating a code_verifier and code_challenge. To create a code_verifier, the partner application should create a record a secret, which should be a high-entropy cryptographic random string (ASCII characters) using the unreserved characters [A-Z][a-z][0-9]["-",".","_","~"] with a minimum length of 43 characters and a maximum length of 128 characters. The code_challenge is then created by creating a SHA2 256-bit hash of the code_verifier and then base64url encoding the hash. If your application is unable to support S256 hashing, you may pass in the code_verifier untransformed and use plain as the code_challenge_method.

Requirements: In order to utilize OAuth 2.0, partners need to provide Geocaching HQ with the application's redirect uris. The redirect uri passed in during the authorization process will be verified against the known uris by matching exactly. Staging environment will allow any valid url so partners can use a localhost url to test. Production requires a secure uri (https) or a valid native app custom protocol.

Authorize Endpoint

The first step of the OAuth 2.0 process is to redirect the end user to the Geocaching OAuth service authorize endpoint (https://www.geocaching.com/oauth/authorize.aspx). This allows the end user to log in directly to Geocaching.com and grant the app/site access. No passing of end user credentials is needed. The OAuth service will then redirect to the redirect_uri parameter given above while passing the app/site a code and state via querystring parameters.

Parameters
Parameter Name Required Description
client_id Yes consumer key
response_type Yes always equal to code
scope Yes always equal to *
redirect_uri Yes the url to redirect the end user after successfully granting access
code_challenge No the transformed code verifier generated if using PKCE
code_challenge_method No code verifier transformation method if using PKCE. The value can either be "S256" or "plain".
state No consumer provided code to mitigate XSRF attacks
Response Values
Parameter Name Description
code a string to pass into the token endpoint
state the state parameter passed into the authorize endpoint
Example Staging URL: https://staging.geocaching.com/oauth/authorize.aspx?client_id=12345&response_type=code&scope=*&redirect_uri=https://www.geocaching.com&state=1234abcd
Example Production URL: https://www.geocaching.com/oauth/authorize.aspx?client_id=12345&response_type=code&scope=*&redirect_uri=https://www.geocaching.com&state=1234abcd
Example Response: https://www.geocaching.com?code=92232758f93a4dcda0223b45d9360ba2&state=1234abcd

Token Endpoint

Next, the app can make a POST call into the OAuth service's token endpoint (https://oauth.geocaching.com/token) to exchange the code for an access token via the following endpoint. The post body must be formatted using x-www-form-urlencoded. The access token can then be used in the header for subsequent calls with key Authorization and value bearer {access_token}.

Parameters
Parameter Name Required Description
client_id Yes consumer key
client_secret Yes consumer secret key
grant_type Yes always equal to authorization_code
redirect_uri Yes the same redirect uri passed into the authorize endpoint
code Yes the code returned from the authorize endpoint
code_verifier No the secret generated for implementing PKCE and is required if code_challenge was passed in the authorize request
Response Values
Parameter Name Description
access_token string access token to used in the authorization header when calling api endpoints
token_type will always return bearer
expires_in number in seconds that the access token will expire
refresh_token string code to use to get a new access token after expiration, expires after one year
Example Staging URL: https://oauth-staging.geocaching.com/token
Example Production URL: https://oauth.geocaching.com/token
Example Response:
{
    "access_token": "eyJyb2xlIjoiYWRtaW4iLCJ1bmlxdWVfbmFtZSI6Ik1Ob2ZNaW5kIiwic3ViIj",
    "token_type": "bearer",
    "expires_in": 3599,
    "refresh_token": "d0d103213cef4f299137424a3fcf39d01d43dba028f1480885f61d3695ae702f"
}

Refresh Token Endpoint

When the access token expires, the app can make a POST call into the OAuth service's token endpoint (https://oauth.geocaching.com/token) to exchange the refresh_token for a new access token without any additional authorize calls. The post body must be formatted using x-www-form-urlencoded.

Parameters
Parameter Name Required Description
client_id Yes consumer key
client_secret Yes consumer secret key
grant_type Yes always equal to refresh_token
redirect_uri Yes the same redirect uri passed into the authorize endpoint
refresh_token Yes the refresh token returned from the token endpoint
Response Values
Parameter Name Description
access_token string access token to used in the authorization header when calling api endpoints
token_type will always return bearer
expires_in number in seconds that the access token will expire
refresh_token string code to use to get a new access token after expiration
Example Production URL: https://oauth-staging.geocaching.com/token
Example Production URL: https://oauth.geocaching.com/token
Example Response:
{
    "access_token": "eyJyb2xlIjoiYWRtaW4iLCJ1bmlxdWVfbmFtZSI6Ik1Ob2ZNaW5kIiwic3ViIj",
    "token_type": "bearer",
    "expires_in": 3599,
    "refresh_token": "d0d103213cef4f299137424a3fcf39d01d43dba028f1480885f61d3695ae702f"
}

Using the Access Token

To use the access_token response value from either the token or the refresh token endpoint, add a header value. The header key should be Authorization and the value should be bearer {access_token}.
Base Staging URL: https://staging.api.groundspeak.com
Base Production URL: https://api.groundspeak.com

Responses

The Geocaching API uses HTTP status codes in all responses to help partners easily understand and handle the service response. The following are examples of the response objects.

List of status codes used in Geocaching API:

Status Code Description
200OK
201Created
204No Content
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Conflict
422Unprocessable Entity
429Too Many Requests
500Internal Server Error

An error response will comprise of the HTTP status code, the status code message, an error message, and the request uri. The status code and message should give the general idea of why an error was thrown while the error message gives more specifics depending on the method. See methods for the specific error messages that can be returned.

{
  "statusCode": 404,
  "statusMessage": "Not Found",
  "errorMessage": ""
}

A successful response will include a status code but the bulk of the body will typically be the resource requested. Navigate to the methods section to see specific response bodies.

The response will also contain some custom headers.

Headers
Name Description
x-total-countthe sum of all resources that match the request, regardless of what is returned via pagination
x-rate-limit-resethow much time in seconds before the rate limit remaining number is reset

Restrictions

Membership Restrictions

To act in accordance with our Geocaching API Agreement, there are certain restrictions you must be include for Geocaching.com Basic Members.

Geocache Limits

As explained in the membership restrictions above, the number of geocaches the user can fetch per day are limited to the following. The number per day is based off of fetching lite geocaches (which contain less fields) vs full geocaches and whether the user is a premium member. The same geocache reference code will only count as one on the user's daily limit (allowing consumers to make lightweight calls without worrying about wasting the daily limit). Requesting only the referenceCode field on a geocache does not count towards the user's limit:

The user's geocache remaining limit and when the limit is reset can be viewed as part of the User object using the Get User endpoint.

Third Party Data Sharing

Users have the ability to opt-out of allowing other users to view their public profile data, shared through our Geocaching API, in their account settings. If the user has not authorized the sharing of their public profile data, the API will return only the reference code and username, and the reference code will be returned as part of a comma delimited list of strings in the header named x-opted-out.

Rate Limiting

Rate limiting is enforced on all methods of the Geocaching API. The methods are limited on the calling IP, end user, and by partner consumer key. The current limits are set to:

If abuse is detected, we may add additional limiting to mitigate risk and attacks on the server. If the call is being subject to rate limiting, a 429 HTTP status code will be returned. If a 429 HTTP status code is returned, the x-rate-limit-reset header is returned with the number of seconds until the limit is reset.

Third Party Data Sharing

Users have the ability to opt-out of allowing other users to view their public profile data, shared through our Geocaching API, in their account settings. If the user has not authorized the sharing of their public profile data, the API will return only the reference code and username, and the reference code will be returned as part of a comma delimited list of strings in the header named x-opted-out.

Pagination

The Geocaching API supports pagination in all calls that return a list of a resource. The two parameters available are skip and take. Skip will tell the query how many results to pass over and take will tell how many to return in the results. Both parameters are optional and will have a default value if not assigned as specified in the methods section. The take parameter also has a maximum value, which is specified for each relevant method in the Methods section.

Page 1 Example: ?skip=0&take=50
Page 2 Example: ?skip=50&take=50

Fields (Partial Responses)

One way to increase the performance and shrink the payload of the Geocaching API is to use the fields parameter. This parameter can be added to any GET request to specify which object properties the app/site needs. The fields parameter can be used with a comma delimited list of all properties desired.

Example Request: https://api.groundspeak.com/v1/geocaches/gc25?fields=name,referenceCode

Example Response:

{
    "referenceCode": "GC25",
    "name": "Camels Prairie Stash"
}

To specify nested object fields, list the nested fields as a comma separated list inside square brackets ("[", "]"). This is especially useful when using the expand parameter as you can request specific expanded fields. Including the top level of an object will include all nested properties.

Example Request: https://api.groundspeak.com/v1/geocaches/gc25?fields=userData[favorited,founddate]
Example Response:

{
    "userData": 
    {
        "favorited": true,
        "foundDate": "2013-07-16T12:00:00"
    }
}


Example Request: https://api.groundspeak.com/v1/geocaches/gc25?fields=userData
Example Response:
{
    "userData": 
    {
        "favorited": true,
        "foundDate": "2013-07-16T12:00:00",
        "dnfDate": "2013-07-05T12:00:00",
        ...
    }
}

Expand (Expanded Responses)

On the other side of fields, expand is a keyword on some endpoints to help reduce the number of calls to the API but return more data than what the endpoint normally returns. Expand allows resources that have a parent child relationship (especially when the parent has a one to many relationship with the child) from different endpoints to be combined under the parent resource. An example of this would be including geocache logs within the Get Geocache endpoint. The drawback of this approach is the payload will be larger and the call duration will be longer but depending on the platform used, this approach may be useful to your application. Expand queries allow a limited subset of data to be returned then the correct endpoint will be needed to page upon the results. Use the specific endpoint documentation to see if expand is allowed and what values are able to be expanded. The expand parameter is a comma separated array of the expanded values. Each expand parameter will include the resource name, a colon, and number (geocachelogs:5) to set the number of expanded resources returned. All expanded resources are allowed a max take of 30.

Tip: Use the fields parameter to reduce the fields that come back with the expanded resource. This will increase the efficiency as well as decrease the payload size of the request.

Example Request: https://api.groundspeak.com/v1/geocaches/gck25b?expand=geocachelogs:5,geocachelog.images:5&fields=referenceCode,geocachelogs[referencecode,text,images[url]]

Example Response:

{
  "referenceCode": "GCK25B",
  "geocacheLogs": [
    {
      "referenceCode": "GLXJA1WB",
      "text": "Nice to be able to finally visit the center of it all! TFTC!",
      "images": [
        {
          "url": "https://img.geocaching.com/12345.jpg"
        }
      ]
    },
    {
      "referenceCode": "GLXJ723B",
      "text": "2nd visit. Was here last year visiting family. Dropping off TB. ",
      "images": []
    },
    {
      "referenceCode": "GLXJ71J5",
      "text": "Drop off travel bugs at headquarters ",
      "images": [
        {
          "url": "https://img.geocaching.com/67890.jpg"
        }
      ]
    },
    {
      "referenceCode": "GLXJ710W",
      "text": "2nd visit 20018 drop off travel bugs",
      "images": []
    },
    {
      "referenceCode": "GLXJ6J18",
      "text": "Dropping off TBs",
      "images": []
    }
  ]
}

Reference Codes

Reference codes are the primary means of uniquely identifying a data object sent to or returned by the API. They are identified by a string with a two character prefix followed by a sequence of base16 or base31 characters.

The following pseudo code shows how to perform the conversion from a string based code to the 64bit integer value and vice versa.

Base16_Characters = [
    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F'
]

Base31_Characters = [
    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F',
    'G', 'H', 'J', 'K', 'M', 'N', 'P', 'Q', 'R', 'T', 'V', 'W', 'X', 'Y', 'Z'
]


Id to Reference Code
--------------------

If Id < 65536
    ReferenceCode = Base16(Id) // Decimal to Hex
else
    ReferenceCode = Base31(Id + 411120)


    
Reference Code to Id
--------------------

if Prefix == "GC" 
    ReferenceCode = Replace(code, "S", "5")
    ReferenceCode = Replace(code, "O", "0")

ReferenceCode = RemovePrefix(ReferenceCode)
    
FirstChar = substring(ReferenceCode, 0, 1)
    
if len(ReferenceCode) >= 5 or FirstChar >= 'G'
    Id = Base31(ReferenceCode) - 411120
else
    Id = Base16(ReferenceCode)

Geocache Methods

Get Geocache

This method will fetch a specified geocache using the reference code

Path: /v1/geocaches/{referenceCode}
HTTP Method: GET
Response Type: Geocache


Parameters
Argument Type Example Required Description Default
referenceCode path GCK25B Yes the identifier of the geocache -
lite query lite=true No whether the response should be a lite geocaches or not false
fields query fields=referenceCode false The fields of the geocache object to return in the response referenceCode
expand query expand=geocachelogs:5,trackables:5 false The fields of the geocache object to expand. Cannot be used with lite geocaches. The available options are geocachelogs, trackables, geocachelog.images, userwaypoints, and images. -

Get Geocaches

This method will fetch the specified geocaches using the reference codes

Path: /v1/geocaches
HTTP Method: GET
Response Type: Array of Geocaches or Lite Geocaches


Parameters
Argument Type Example Required Description Default
referenceCodes query referenceCodes=gc25,gc26,gc27 Yes the identifiers of the geocaches. The max number of codes allowed is 50. -
lite query lite=true No whether the response should be a lite geocaches or not false
fields query fields=name,state No partial response fields to return referenceCode
expand query expand=geocachelogs:5 false The fields of the geocache object to expand. Cannot be used with lite geocaches. The available options are geocachelogs, trackables, geocachelog.images, userwaypoints, and images. -

Get Geocache Images

This method will fetch the images for the specified geocache

Path: /v1/geocaches/{referenceCode}/images
HTTP Method: GET
Response Type: Array of Images


Parameters
Argument Type Example Required Description Default
referenceCode path GCK25B Yes the identifier of the geocache -
fields query fields=url,description No partial response fields to return url
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Upsert Geocache Note

This method will add or update a note to the specified geocache. It will return the inserted or updated geocache note.

Path: /v1/geocaches/{referenceCode}/notes
HTTP Method: PUT
Response Type: string
Response Codes: 200, 400, 401, 403, 404, 409, 500
Restrictions: Only owner may update the note.


Parameters
Argument Type Example Required Description Default
referenceCode path GCK25B Yes the identifier of the geocache -
note body {"note": "the cache is in a tree."} Yes note text to add/update -

Delete Geocache Note

This method will delete a specified geocache note

Path: /v1/geocaches/{referenceCode}/notes
HTTP Method: DELETE
Response Type: No response body
Response Codes: 204, 400, 401, 409, 500
Restrictions: Only owner may delete the geocache note.


Parameters
Argument Type Example Required Description Default
referenceCode path GCK25B Yes the identifier of the geocache -

Get Geocache Types

This method will fetch all valid geocache types

Path: /v1/geocachetypes
HTTP Method: GET
Response Type: Array of Geocache Types
Response Codes: 200, 401, 500


Get Attributes

This method will fetch all valid attributes

Path: /v1/attributes
HTTP Method: GET
Response Type: Array of Attribute Types
Response Codes: 200, 401, 500


Geocache Log Methods

Get Geocache's Logs

This method will fetch a specified geocache's logs using the reference code

Path: /v1/geocaches/{referenceCode}/geocachelogs
HTTP Method: GET
Response Type: Array of Geocache Logs
Response Codes: 200, 400, 401, 404, 429, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info.


Parameters
Argument Type Example Required Description Default
referenceCode path gc25 Yes the identifier of the geocache -
fields query fields=name,referenceCode No partial response fields to return referenceCode
expand query expand=images:5 No The fields of the geocache log object to expand. The available option is images. -
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Get Geocache Log

This method will fetch the specified geocache log using the reference code

Path: /v1/geocachelogs/{referenceCode}
HTTP Method: GET
Response Type: Geocache Log
Response Codes: 200, 400, 401, 404, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info.


Parameters
Argument Type Example Required Description Default
referenceCode path gl100 Yes the identifiers of the geocache log -
fields query fields=name,referenceCode No partial response fields to return referenceCode
expand query expand=images:5 No The fields of the geocache log object to expand. The available option is images. -

Create Geocache Log

This method will create a new log to the specified geocache. It will return the created geocache log.

Path: /v1/geocachelogs
HTTP Method: POST
Response Type: Geocache Log
Response Codes: 201, 400, 401, 404, 409, 500


Parameters
Argument Type Example Required Description Default
log body GeocacheLog Yes geocache log to create -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Update Geocache Log

This method will update a specified geocache log. It will return the updated geocache log.

Path: /v1/geocachelogs/{referenceCode}
HTTP Method: PUT
Response Type: GeocacheLog
Response Codes: 200, 400, 401, 403, 404, 409, 500
Restrictions: Only owner of geocache log may update the log.


Parameters
Argument Type Example Required Description Default
referenceCode path gl100 Yes the identifier of the geocache log -
log body GeocacheLog Yes geocache log to update -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Delete Geocache Log

This method will delete a specified geocache log.

Path: /v1/geocachelogs/{referenceCode}
HTTP Method: DELETE
Response Type: No response body
Response Codes: 204, 400, 401, 403, 409, 500
Restrictions: Only owner of geocache log may delete the log.


Parameters
Argument Type Example Required Description Default
referenceCode path gl100 Yes the identifier of the geocache log -

Get Geocache Log Images

This method will fetch a specified geocache log's images using the reference code

Path: /v1/geocachelogs/{referenceCode}/images
HTTP Method: GET
Response Type: Array of Images
Response Codes: 200, 400, 401, 404, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info.


Parameters
Argument Type Example Required Description Default
referenceCode path gl100 Yes the identifier of the geocache log -
fields query fields=guid,url No partial response fields to return url
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Add Geocache Log Image

This method will add a new image to the specified geocache log. It will return the added image.

Path: /v1/geocachelogs/{referenceCode}/images
HTTP Method: POST
Response Type: Image
Response Codes: 201, 400, 401, 403, 404, 409, 500
Restrictions: Only owner of geocache log may add an image.


Parameters
Argument Type Example Required Description Default
referenceCode path gl1 Yes the identifier of the geocache log -
image body ImageToUpload Yes image to add to log -
fields query fields=guid,url No partial response fields to return url

Delete Geocache Log Image

This method will delete an image to the specified geocache log.

Path: /v1/geocachelogs/{referenceCode}/images/{imageGuid}
HTTP Method: DELETE
Response Type: No response body
Response Codes: 201, 400, 401, 403, 409, 500
Restrictions: Only owner of geocache log may delete an image.


Parameters
Argument Type Example Required Description Default
referenceCode path gl1 Yes the identifier of the geocache log -
imageGuid path fed3b84a-414e-469b-8b84-d731d62a2f9e Yes the identifier of the image -

Get Geocache Log Types

This method will fetch all valid geocache log types

Path: /v1/geocachelogtypes
HTTP Method: GET
Response Type: Array of Geocache Log Types
Response Codes: 200, 401, 500


Trackable Methods

Get Geocache's Trackables

This method will fetch a specified geocache's trackables

Path: /v1/geocaches/{referenceCode}/trackables
HTTP Method: GET
Response Type: Array of Trackables
Response Codes: 200, 400, 401, 404, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info.


Parameters
Argument Type Example Required Description Default
referenceCode path gc25 Yes the identifier of the geocache -
fields query fields=name,referenceCode No partial response fields to return referenceCode
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10
expand query expand=trackablelogs:5 No The fields of the trackable object to expand. The available options are trackablelogs, trackablelog.images, and images. -

Get Trackable

This method will fetch the specified trackable

Path: /v1/trackables/{referenceCode}
HTTP Method: GET
Response Type: Trackable
Response Codes: 200, 400, 401, 404, 500


Parameters
Argument Type Example Required Description Default
referenceCode path tb100 Yes the identifier of the trackable (tb code or tracking number found on the physical object) -
fields query fields=name,referenceCode No partial response fields to return referenceCode
expand query expand=trackablelogs:5 No The fields of the trackable object to expand. The available options are trackablelogs, trackablelog.images, and images. -

Get Trackables

This method will fetch either the requested trackables or the calling user's trackables in their possession.

Path: /v1/trackables
HTTP Method: GET
Response Type: Array of Trackables
Response Codes: 200, 400, 401, 404, 500


Parameters
Argument Type Example Required Description Default
referenceCodes query TB1,TB2 No The reference code or tracking number of the trackables. Do not pass in this param if you want to return user trackables. -
type query type=1 No whether to return the trackables in the user's inventory (1), their collection (2), or their owned trackables (3) 1
fields query fields=name,referenceCode No partial response fields to return referenceCode
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10
expand query expand=trackablelogs:5 No The fields of the trackable object to expand. The available options are trackablelogs, trackablelog.images, and images. -

Get Trackable Images

This method will fetch a specified trackable's images

Path: /v1/trackables/{referenceCode}/images
HTTP Method: GET
Response Type: Array of Images
Response Codes: 200, 400, 401, 404, 500


Parameters
Argument Type Example Required Description Default
referenceCode path tb100 Yes the identifier of the trackable -
fields query fields=name,referenceCode No partial response fields to return referenceCode
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Get Geocoin Types

This method will fetch all valid geocoin types

Path: /v1/trackables/geocointypes
HTTP Method: GET
Response Type: Array of Types
Response Codes: 200, 400, 401, 500


Parameters
Argument Type Example Required Description Default
fields query fields=id,name No partial response fields to return id
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 100 10

Trackable Log Methods

Get Trackable's Logs

This method will fetch a specified trackable's logs

Path: /v1/trackables/{referenceCode}/trackablelogs
HTTP Method: GET
Response Type: Array of Trackable Logs
Response Codes: 200, 400, 401, 404, 500


Parameters
Argument Type Example Required Description Default
referenceCode path tb25 Yes the identifier of the trackable -
fields query fields=name,referenceCode No partial response fields to return referenceCode
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10
expand query expand=images:5 No The fields of the trackable log object to expand. The available options are images. -
logTypes query logTypes=14,75 No comma delimited list of log types to include in results all types

Get Trackable Log

This method will fetch the specified trackable log

Path: /v1/trackablelogs/{referenceCode}
HTTP Method: GET
Response Type: Trackable Log
Response Codes: 200, 400, 401, 404, 500


Parameters
Argument Type Example Required Description Default
referenceCode path tl100 Yes the identifiers of the trackable log -
fields query fields=name,referenceCode No partial response fields to return referenceCode
expand query expand=images:5 No The fields of the trackable log object to expand. The available options are images. -

Create Trackable Log

This method will create a new log to the specified trackable. It will return the created trackable log.

Path: /v1/trackablelogs
HTTP Method: POST
Response Type: Trackable Log
Response Codes: 201, 400, 401, 404, 409, 500


Parameters
Argument Type Example Required Description Default
log body TrackableLog Yes trackable log to create -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Update Trackable Log

This method will update a specified trackable log. It will return the updated trackable log.

Path: /v1/trackablelogs/{referenceCode}
HTTP Method: PUT
Response Type: TrackableLog
Response Codes: 200, 400, 401, 403, 404, 409, 500
Restrictions: Only owner of trackable log may update the log.


Parameters
Argument Type Example Required Description Default
referenceCode path tl100 Yes the identifier of the trackable log -
log body TrackableLog Yes trackable log to update -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Delete Trackable Log

This method will delete a specified trackable log.

Path: /v1/trackablelogs/{referenceCode}
HTTP Method: DELETE
Response Type: No response body
Response Codes: 204, 400, 401, 403, 409, 500
Restrictions: Only owner of trackable log may delete the log.


Parameters
Argument Type Example Required Description Default
referenceCode path tl100 Yes the identifier of the trackable log -

Get Trackable Log Images

This method will fetch a specified trackable log's images

Path: /v1/trackablelogs/{referenceCode}/images
HTTP Method: GET
Response Type: Array of Images
Response Codes: 200, 400, 401, 404, 500


Parameters
Argument Type Example Required Description Default
referenceCode path tl100 Yes the identifier of the trackable log -
fields query fields=name,referenceCode No partial response fields to return url
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Add Trackable Log Image

This method will add a new image to the specified trackable log. It will return the added image.

Path: /v1/trackablelogs/{referenceCode}/images
HTTP Method: POST
Response Type: Image
Response Codes: 201, 400, 401, 403, 404, 409, 500
Restrictions: Only owner of trackable log may add an image.


Parameters
Argument Type Example Required Description Default
referenceCode path tl25 Yes the identifier of the trackable -
image body ImageToUpload Yes image to add to log -
fields query fields=url No partial response fields to return url

Delete Trackable Log Image

This method will delete an image to the specified trackable log.

Path: /v1/trackablelogs/{referenceCode}/images/{imageGuid}
HTTP Method: DELETE
Response Type: No response body
Response Codes: 201, 400, 401, 403, 409, 500
Restrictions: Only owner of trackable log may delete an image.


Parameters
Argument Type Example Required Description Default
referenceCode path tl1 Yes the identifier of the trackable log -
imageGuid path fed3b84a-414e-469b-8b84-d731d62a2f9e Yes the identifier of the image -

Get Trackable Log Types

This method will fetch all valid trackable log types

Path: /v1/trackablelogtypes
HTTP Method: GET
Response Type: Array of Trackable Log Types
Response Codes: 200, 401, 500


Log Draft Methods

Get Log Drafts

This method will fetch the log drafts for the calling user sorted by date logged descending.

Path: /v1/logdrafts
HTTP Method: GET
Response Type: Array of Log Drafts
Response Codes: 200, 400, 401, 404, 500


Parameters
Argument Type Example Required Description Default
fields query fields=name,referenceCode No partial response fields to return referenceCode
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Get Log Draft

This method will fetch the specified log draft

Path: /v1/logdrafts/{referenceCode}
HTTP Method: GET
Response Type: Log Draft
Response Codes: 200, 400, 401, 404, 500
Restrictions: Only owner of log drafts may fetch it.


Parameters
Argument Type Example Required Description Default
referenceCode path ld100 Yes the identifiers of the log draft -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Create Log Draft

This method will create a new log draft. It will return the created log draft.

Path: /v1/logdrafts
HTTP Method: POST
Response Type: Log Draft
Response Codes: 201, 400, 401, 404, 409, 500


Parameters
Argument Type Example Required Description Default
log body LogDraft Yes log draft to create -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Update Log Draft

This method will update a specified log draft. It will return the updated log draft.

Path: /v1/logdrafts/{referenceCode}
HTTP Method: PUT
Response Type: LogDraft
Response Codes: 200, 400, 401, 403, 404, 409, 500
Restrictions: Only owner of log draft may update the log draft.


Parameters
Argument Type Example Required Description Default
referenceCode path ld100 Yes the identifier of the log draft -
log body LogDraft Yes log draft to update -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Delete Log Draft

This method will delete a specified log draft

Path: /v1/logdrafts/{referenceCode}
HTTP Method: DELETE
Response Type: No response body
Response Codes: 204, 400, 401, 409, 500
Restrictions: Only owner of log draft may delete the log draft.


Parameters
Argument Type Example Required Description Default
referenceCode path ld100 Yes the identifier of the log draft -

Promote Log Draft

This method will promote a specified log draft to a geocache log

Path: /v1/logdrafts/{referenceCode}/promote
HTTP Method: POST
Response Type: PromotedLogDraft
Response Codes: 201, 400, 401, 409, 500
Restrictions: Only owner of log draft may promote the log draft.


Parameters
Argument Type Example Required Description Default
referenceCode path ld100 Yes the identifier of the log draft -
draft body LogDraft Yes the log draft to promote to geocache log -

Add Log Draft Image

This method will add an image to a specified log draft

Path: /v1/logdrafts/{referenceCode}/images
HTTP Method: POST
Response Type: Image
Response Codes: 201, 400, 401, 403, 409, 500
Restrictions: Only owner of log draft may add images to the log draft.


Parameters
Argument Type Example Required Description Default
referenceCode path ld100 Yes the identifier of the log draft -
image body PostImage Yes the iamge to upload -
fields query fields=url,guid No partial response fields to return url

User Waypoints Methods

Get Geocache's User Waypoints

This method will fetch a specified geocache's user waypoints for the calling user.

Path: /v1/geocaches/{referenceCode}/userwaypoints
HTTP Method: GET
Response Type: Array of User Waypoints
Response Codes: 200, 400, 401, 404, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Only owner of user waypoints can fetch them.


Parameters
Argument Type Example Required Description Default
referenceCode path gc25 Yes the identifier of the geocache -
includeCorrectedCoordinates query includeCorrectedCoordinates=false No bool to include corrected coordinates in the response false
fields query fields=name,referenceCode No partial response fields to return all fields
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Get User Waypoints

This method will fetch the user waypoints for the calling user.

Path: /v1/userwaypoints
HTTP Method: GET
Response Type: Array of User Waypoints
Response Codes: 200, 400, 401, 404, 500
Restrictions: Only owner of user waypoints can fetch them.


Parameters
Argument Type Example Required Description Default
includeCorrectedCoordinates query includeCorrectedCoordinates=false No bool to include corrected coordinates in the response false
fields query fields=name,referenceCode No partial response fields to return all fields
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Create User Waypoint

This method will create a new user waypoint. It will return the created user waypoint.

Path: /v1/userwaypoints
HTTP Method: POST
Response Type: User Waypoint
Response Codes: 201, 400, 401, 404, 409, 500


Parameters
Argument Type Example Required Description Default
referenceCode path gc25 Yes the identifier of the geocache -
userWaypoint body UserWaypoint Yes user waypoint to create -

Update User Waypoint

This method will update a specified user waypoint. It will return the updated user waypoint.

Path: /v1/userwaypoints/{id}
HTTP Method: PUT
Response Type: User Waypoint
Response Codes: 200, 400, 401, 403, 404, 409, 500
Restrictions: Only owner may update the user waypoint.


Parameters
Argument Type Example Required Description Default
referenceCode path UW123 Yes the identifier of the user waypoint -
log body UserWaypoint Yes user waypoint to update -

Delete User Waypoint

This method will delete a specified user waypoint

Path: /v1/userwaypoints/{id}
HTTP Method: DELETE
Response Type: No response body
Response Codes: 204, 400, 401, 409, 500
Restrictions: Only owner may delete the user waypoint.


Parameters
Argument Type Example Required Description Default
referenceCode path UW123 Yes the identifier of the user waypoint -

Upsert Corrected Coordinates

This method will insert or update corrected coordinates for the specified geocache. It will return the updated user waypoint.

Path: /v1/geocaches/{referenceCode}/correctedcoordinates
HTTP Method: PUT
Response Type: User Waypoint
Response Codes: 200, 400, 401, 403, 404, 409, 429, 500


Parameters
Argument Type Example Required Description Default
referenceCode path GCK25B Yes the identifier of the geocache -
coordinates body Coordinates Yes the corrected coordinates to upsert -

Delete CorrectedCoordinates

This method will delete the calling user's coordinates for the specified geocache

Path: /v1/geocaches/{referenceCode}/correctedcoordinates
HTTP Method: DELETE
Response Type: No response body
Response Codes: 204, 400, 401, 409, 429, 500
Restrictions: Only owner may delete the corrected coordinate.


Parameters
Argument Type Example Required Description Default
referenceCode path GCK25B Yes the identifier of the geocache -

List Methods

Get List

This method will fetch the specified list.

Path: /v1/lists/{referenceCode}
HTTP Method: GET
Response Type: List
Response Codes: 200, 400, 401, 404, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Users may only see their own lists or lists marked public.


Parameters
Argument Type Example Required Description Default
referenceCode path BM1234 Yes identifier of the list (ignore, favorites, or watch can be used as aliases in place of the reference codes to get the calling user's ignore list and watch list). -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Create List

This method will create a new list. It will return the created list.

Path: /v1/lists
HTTP Method: POST
Response Type: List
Response Codes: 201, 400, 401, 403, 404, 409, 422, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Users can only add bookmark lists and have a maximum of 100 bookmark lists.


Parameters
Argument Type Example Required Description Default
list body List Yes list to create -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Update List

This method will update a specified list. It will return the updated list.

Path: /v1/lists/{referenceCode}
HTTP Method: PUT
Response Type: List
Response Codes: 200, 400, 401, 403, 404, 409, 500
Restrictions: Only owner may update the list.


Parameters
Argument Type Example Required Description Default
referenceCode path BM1234 Yes the identifier of the list -
list body List Yes list to update -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Delete List

This method will delete a specified list.

Path: /v1/lists/{referenceCode}
HTTP Method: DELETE
Response Type: No Response body
Response Codes: 200, 400, 401, 403, 404, 409, 500
Restrictions: Only owner may delete the list.


Parameters
Argument Type Example Required Description Default
referenceCode path BM1234 Yes the identifier of the list -

Get List's Geocaches

This method will fetch the geocaches from the specified list.

Path: /v1/lists/{referenceCode}/geocaches
HTTP Method: GET
Response Type: Array of List Geocaches or Lite List Geocaches
Response Codes: 200, 400, 401, 404, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info.


Parameters
Argument Type Example Required Description Default
referenceCode path BM1234 Yes identifier of the list (ignore, favorites, or watch can be used as aliases in place of the reference codes to get the calling user's ignore list and watch list). -
fields query fields=name,referenceCode No partial response fields to return all fields
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10
lite query lite=true No whether the response should be a lite geocaches or not true
expand query expand=geocachelogs:5,trackables:5 false The fields of the geocache object to expand. Cannot be used with lite geocaches. The available options are geocachelogs, trackables, geocachelog.images, userwaypoints, and images. -

Get Zipped Pocket Query

This method will fetch a zipped file of the requested pocket query.

Path: /v1/lists/{referenceCode}/geocaches/zipped
HTTP Method: GET
Response Type: Zip File ("application/zip") with a Content-Disposition of attachment
Response Codes: 200, 400, 401, 404, 500
Restrictions: Only Read for Download pocket queries from the web may be fetched. Pocket queries are a premium member feature.


Parameters
Argument Type Example Required Description Default
referenceCode path PQ1234 Yes identifier of the pocket query -

Add Geocache to List

This method will add the geocache to the specified list.

Path: /v1/lists/{referenceCode}/geocaches
HTTP Method: POST
Response Type: List Item
Response Codes: 200, 400, 401, 404, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Bookmark lists may have a maximum of 1000 geocaches.


Parameters
Argument Type Example Required Description Default
referenceCode path BM1234 Yes identifier of the list (ignore, favorites, or watch can be used as aliases in place of the reference codes to get the calling user's ignore list and watch list). -
geocache body Geocache Yes geocache to add to the list -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Add Geocaches to List

This method will add multiple geocaches to the specified list.

Path: /v1/lists/{referenceCode}/bulkgeocaches
HTTP Method: POST
Response Type: BulkResponse
Response Codes: 200, 400, 401, 403, 404, 409, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Bookmark lists may have a maximum of 1000 geocaches.


Parameters
Argument Type Example Required Description Default
referenceCode path BM1234 Yes identifier of the list (ignore, favorites, or watch can be used as aliases in place of the reference codes to get the calling user's ignore list and watch list). -
geocacheCodes body Array of strings Yes The reference codes of the geocaches to add. -

Remove Geocache from List

This method will remove a specified geocache from the list

Path: /v1/lists/{referenceCode}/geocaches/{geocacheCode}
HTTP Method: DELETE
Response Type: No response body
Response Codes: 204, 400, 401, 409, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Only owner may delete the user waypoint.


Parameters
Argument Type Example Required Description Default
referenceCode path BM1234 Yes identifier of the list (ignore, favorites, or watch can be used as aliases in place of the reference codes to get the calling user's ignore list and watch list). -
geocacheCode query geocacheCode=GC1234 Yes identifier of the geocache -

User Methods

Get User

This method will fetch the information about the user.

Path: /v1/users/{referenceCode}
HTTP Method: GET
Response Type: User
Response Codes: 200, 400, 401, 403, 404, 500
Restrictions: Users may opt out of sharing personal data. See Third Party Data Sharing section for more info.


Parameters
Argument Type Example Required Description Default
referenceCode path PR18 Yes the identifier of the user. Can also use me to fetch the calling user's information -
fields query fields=username,referenceCode No partial response fields to return referenceCode

Get Users

This method will fetch the information about the specified users.

Path: /v1/users
HTTP Method: GET
Response Type: Array of Users
Response Codes: 200, 400, 401, 404, 500
Restrictions: Only referenceCodes will be respected if both are passed in. Users may opt out of sharing personal data. See Third Party Data Sharing section for more info.


Parameters
Argument Type Example Required Description Default
referenceCodes query referenceCodes=PR1,PR2,PR3 No (see restrictions) the identifiers of the users. The max amount of codes allowed is 50. -
usernames query usernames=test1,test2 No (see restrictions) the username of the users. The max amount of usernames allowed is 50. -
fields query fields=username,referenceCode No partial response fields to return referenceCode

Get User Geocache Logs

This method will fetch the geocache logs for the user.

Path: /v1/users/{referenceCode}/geocachelogs
HTTP Method: GET
Response Type: Array of GeocacheLogs
Response Codes: 200, 400, 401, 403, 404, 500
Restrictions: Can only use includeArchived parameter for the calling user. Users may opt out of sharing personal data. See Third Party Data Sharing section for more info.


Parameters
Argument Type Example Required Description Default
referenceCode path PR18 Yes the identifier of the user. Can also use me to fetch the calling user's information -
fields query fields=name,referenceCode No partial response fields to return referenceCode
expand query expand=images:5 No The fields of the geocache log object to expand. The available option is images. -
includeArchived query includeArchived=false No includes archived logs in the results (see restrictions) false
logTypes query logTypes=2,10,11 No the log types to include in the results (see restrictions) all types
afterDate query afterDate=2018-01-01 No filters results to loggedDates after this date (inclusive) all dates included
beforeDate query beforeDate=2018-01-01 No filters results to loggedDates before this date (inclusive) all dates included
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Get User Lists

This method will fetch the lists for the user.

Path: /v1/users/{referenceCode}/lists
HTTP Method: GET
Response Type: Array of Lists
Response Codes: 200, 400, 401, 403, 404, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Users may only see public bookmark lists for other users.


Parameters
Argument Type Example Required Description Default
referenceCode path PR18 Yes the identifier of the user. Can also use me to fetch the calling user's information -
types query types=bm,wl No the type of lists to return. options are fl (favorites list), wl (watch list), il (ignore list), bm (bookmark list), pq (pocket query) bm
fields query fields=name,referenceCode No partial response fields to return referenceCode
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Get User Souvenirs

This method will fetch the awarded souvenirs for the specified user.

Path: /v1/users/{referenceCode}/souvenirs
HTTP Method: GET
Response Type: Array of Souvenirs
Response Codes: 200, 400, 401, 403, 404, 500
Restrictions: Users may opt out of sharing personal data. See Third Party Data Sharing section for more info.


Parameters
Argument Type Example Required Description Default
referenceCode path PR18 Yes the identifier of the user. Can also use me to fetch the calling user's information -
fields query fields=title No partial response fields to return title
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Get User Images

This method will fetch the images for the specified user.

Path: /v1/users/{referenceCode}/images
HTTP Method: GET
Response Type: Array of Images
Response Codes: 200, 400, 401, 403, 404, 500
Restrictions: Users may opt out of sharing personal data. See Third Party Data Sharing section for more info.


Parameters
Argument Type Example Required Description Default
referenceCode path PR18 Yes the identifier of the user. Can also use me to fetch the calling user's information -
fields query fields=name,referenceCode No partial response fields to return url
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10

Friend Methods

Get Friends

This method will fetch the friends of the user.

Path: /v1/friends
HTTP Method: GET
Response Type: Array of Users
Response Codes: 200, 400, 401, 500
Restrictions: Users may opt out of sharing personal data. See Third Party Data Sharing section for more info.


Parameters
Argument Type Example Required Description Default
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10
fields query fields=username,referenceCode No partial response fields to return referenceCode

Get Friend Requests

This method will fetch friend requests for the user.

Path: /v1/friendrequests
HTTP Method: GET
Response Type: Array of FriendRequests
Response Codes: 200, 400, 401, 500


Parameters
Argument Type Example Required Description Default
skip query skip=10 No the number of resources to skip over 0
take query take=0 No how many resources to return. maximum value of 50 10
fields query fields=requested.username,id No partial response fields to return id

Create Friend Request

This method will create a friend request for the user.

Path: /v1/friendrequests
HTTP Method: POST
Response Type: FriendRequest
Response Codes: 200, 400, 401, 403, 404, 409, 500


Parameters
Argument Type Example Required Description Default
friendRequest body FriendRequest Yes friend request to create -
fields query fields=message No partial response fields to return id

Accept Friend Request

This method will accept a friend request.

Path: /v1/friendrequests/{requestId}/accept
HTTP Method: POST
Response Type: No response body
Response Codes: 204, 400, 401, 403, 404, 500
Restrictions: Only the requested user can accept a friend request.


Parameters
Argument Type Example Required Description Default
requestId path 12345 Yes the identifier of the friend request -

Delete Friend Request

This method will deny a friend request and remove the request.

Path: /v1/friendrequests/{requestId}
HTTP Method: DELETE
Response Type: No response body
Response Codes: 204, 400, 401, 403, 404, 500


Parameters
Argument Type Example Required Description Default
requestId path 12345 Yes the identifier of the friend request -

Delete Friend

This method will remove a user as a friend.

Path: /v1/friends/{userCode}
HTTP Method: DELETE
Response Type: No response body
Response Codes: 204, 400, 401, 403, 404, 500


Parameters
Argument Type Example Required Description Default
userCode path PR18 Yes the identifier of the user to remove as a friend -

Utility Methods

Get Reference Code

This method will fetch the reference code from an id.

Path: /v1/utilities/referencecode
HTTP Method: GET
Response Type: string
Response Codes: 200, 400, 401, 500


Parameters
Argument Type Example Required Description Default
id query id=1 Yes the id to convert -
codePrefix query codePrefix=GC Yes the type of reference code to return -

Get Countries

This method will fetch all valid countries

Path: /v1/countries
HTTP Method: GET
Response Type: Array of id and name
Response Codes: 200, 401, 500


Get States

This method will fetch all valid states

Path: /v1/states
HTTP Method: GET
Response Type: Array of id, name, and countryId


Get States By Country

This method will fetch all valid states of a provided country

Path: /v1/countries/{countryId}/states
HTTP Method: GET
Response Type: Array of id, name, and countryId
Response Codes: 200, 401, 500


Parameters
Argument Type Example Required Description Default
countryId path countryId=1 Yes the id of the country -

Get Membership Levels

This method will fetch all valid membership levels

Path: /v1/membershiplevels
HTTP Method: GET
Response Type: Array of id and name
Response Codes: 200, 401, 500


Objects

Geocache

Fields
Name Type Description
referenceCode string uniquely identifies the geocache
name string name of the geocache
difficulty decimal difficulty rating of the geocache between 1.0 and 5.0
terrain decimal terrain rating of the geocache between 1.0 and 5.0
favoritePoints integer number of favorite points awarded to the geocache
trackableCount integer number of trackables currently in the geocache
placedDate datetime date when the cache was placed (if an event, this is the date of the event) in the timezone of the geocache
publishedDate datetime date when the cache was published in the timezone of the geocache
eventEndDate nullable datetime date and time of when an event will end (in the timezone of the geocache). null if an end date doesn't exist or if geocache is not event type.
type (Deprecated) enum type of the geocache (see Geocache Types for more info)
geocacheType Type type of the geocache (see Geocache Types for more info)
size (Deprecated) enum size of the geocache container (see Geocache Sizes for more info)
geocacheSize Size size of the geocache (see Geocache Sizes for more info)
userData UserData user specific information about the geocache
status enum current status of the geocache (see Geocache Statuses for more info)
location Location country and state information about the geocache
postedCoordinates Coordinates latitude and longitude of the geocache
lastVisitedDate nullable datetime datetime of last logged visit to geocache in the timezone of the geocache
ownerCode string owner identifier of the geocache
ownerAlias string display name of owner for geocache
isPremiumOnly boolean whether the geocache can only be viewed by premium members
shortDescription string summary about the geocache
longDescription string details about the geocache
hints string hints/spoilers to help to find the geocache
attributes array of Attributes attributes of the geocache
ianaTimezoneId string timezone of the geocache
relatedWebPage string external web page associated with geocache
url string geocaching.com web page associated with geocache
backgroundImageUrl string user supplied image url used as background image on geocaching.com (will be null if none supplied)
containsHtml bool flag for if the short or long description contains html
findCount integer number of Found It logs on the geocache
owner User information about the owner of the geocache No No
additionalWaypoints array of AdditionalWaypoint other reference waypoints associated with the geocache

Example

{
  "referenceCode": "GCK25B",
  "name": "Geocaching Headquarters",
  "difficulty": 1,
  "terrain": 1,
  "favoritePoints": 4482,
  "trackableCount": 211,
  "placedDate": "2004-07-22T00:00:00.000",
  "publishedDate": "2004-07-22T00:00:00.000",
  "eventEndDate": null,
  "type": "GeocachingHq",
  "geocacheType": {
    "id": 3773,
    "name": "Geocaching HQ",
    "imageUrl": "https://www.geocaching.com/images/wpttypes/3773.gif"
  },
  "size": "Other",
  "geocacheSize": {
    "id": 6,
    "name": "Other"
  },
  "userData": {
    "foundDate": "2016-06-24T12:00:00.000",
    "correctedCoordinates": {
      "latitude": 47,
      "longitude": -122
    },
    "isFavorited": true
  },
  "status": "Active",
  "location": {
    "country": "United States",
    "countryId": 2,
    "state": "Washington",
    "stateId": 48
  },
  "postedCoordinates": {
    "latitude": 47.648967,
    "longitude": -122.348117
  },
  "lastVisitedDate": "2018-11-29T12:00:00.000",
  "ownerCode": "PRA09E",
  "ownerAlias": "Geocaching HQ",
  "isPremiumOnly": false,
  "shortDescription": "Welcome to Geocaching HQ’s Visitor Center!",
  "longDescription": "This cache is only available while the Visitor Center at HQ is open. ...",
  "hints": "Where would you look if you were a pirate?",
  "attributes": [
    {
      "id": 24,
      "name": "Wheelchair accessible",
      "imageUrl": "https://www.geocaching.com/images/attributes/wheelchair-yes.gif",
      "isOn": true
    },
    {
      "id": 13,
      "name": "Available at all times",
      "imageUrl": "https://www.geocaching.com/images/attributes/available-no.gif",
      "isOn": false
    },
    {
      "id": 7,
      "name": "Takes less than an hour",
      "imageUrl": "https://www.geocaching.com/images/attributes/onehour-yes.gif",
      "isOn": true
    },
    {
      "id": 6,
      "name": "Recommended for kids",
      "imageUrl": "https://www.geocaching.com/images/attributes/kids-yes.gif",
      "isOn": true
    },
    {
      "id": 41,
      "name": "Stroller accessible",
      "imageUrl": "https://www.geocaching.com/images/attributes/stroller-yes.gif",
      "isOn": true
    },
    {
      "id": 28,
      "name": "Public restrooms nearby",
      "imageUrl": "https://www.geocaching.com/images/attributes/restrooms-yes.gif",
      "isOn": true
    },
    {
      "id": 26,
      "name": "Public transportation",
      "imageUrl": "https://www.geocaching.com/images/attributes/public-yes.gif",
      "isOn": true
    },
    {
      "id": 27,
      "name": "Drinking water nearby",
      "imageUrl": "https://www.geocaching.com/images/attributes/water-yes.gif",
      "isOn": true
    },
    {
      "id": 14,
      "name": "Recommended at night",
      "imageUrl": "https://www.geocaching.com/images/attributes/night-no.gif",
      "isOn": false
    },
    {
      "id": 38,
      "name": "Campfires",
      "imageUrl": "https://www.geocaching.com/images/attributes/campfires-no.gif",
      "isOn": false
    }
  ],
  "ianaTimezoneId": "America/Los_Angeles",
  "relatedWebPage": "http://geocachinghq.com/schedule/",
  "url": "https://coord.info/GCK25B",
  "backgroundImageUrl": null,
  "containsHtml": true,
  "findCount": 15760,
  "owner": {
    "membershipLevelId": 2,
    "findCount": 0,
    "hideCount": 114,
    "favoritePoints": 1,
    "profileText": "Geocaching HQ is the home base for all Geocaching employees...",
    "url": "https://coord.info/PRA09E",
    "referenceCode": "PRA09E",
    "username": "Geocaching HQ",
    "avatarUrl": "https://img.geocaching.com/user/avatar/f777d091-4a90-406b-a998-70ec06b4f6f1.png"
  },
  "additionalWaypoints": []
}

Lite Geocache

Fields
Name Type Description
referenceCode string uniquely identifies the geocache
name string name of the geocache
difficulty decimal difficulty rating of the geocache between 1.0 and 5.0
terrain decimal terrain rating of the geocache between 1.0 and 5.0
favoritePoints integer number of favorite points awarded to the geocache
trackableCount integer number of trackables currently in the geocache
placedDate datetime date when the cache was placed (if an event, this is the date of the event) in the timezone of the geocache
publishedDate datetime date when the cache was published in the timezone of the geocache
eventEndDate nullable datetime date and time of when an event will end (in the timezone of the geocache). null if an end date doesn't exist or if geocache is not event type.
type (Deprecated) enum type of the geocache (see Geocache Types for more info)
geocacheType Type type of the geocache (see Geocache Types for more info)
size (Deprecated) enum size of the geocache container (see Geocache Sizes for more info)
geocacheSize Size size of the geocache (see Geocache Sizes for more info)
userData UserData user specific information about the geocache
status enum current status of the geocache (see Geocache Statuses for more info)
location Location country and state information about the geocache
postedCoordinates Coordinates latitude and longitude of the geocache
lastVisitedDate nullable datetime datetime of last logged visit to geocache in the timezone of the geocache
ownerCode string owner identifier of the geocache
ownerAlias string display name of owner for geocache
isPremiumOnly boolean whether the geocache can only be viewed by premium members
ianaTimezoneId string timezone of the geocache
relatedWebPage string external web page associated with geocache
url string geocaching.com web page associated with geocache
backgroundImageUrl string user supplied image url used as background image on geocaching.com (will be null if none supplied)
containsHtml bool flag for if the short or long description contains html
owner User information about the owner of the geocache No No

Example

{
  "referenceCode": "GCK25B",
  "name": "Geocaching Headquarters",
  "difficulty": 1,
  "terrain": 1,
  "favoritePoints": 4482,
  "trackableCount": 211,
  "placedDate": "2004-07-22T00:00:00.000",
  "publishedDate": "2004-07-22T00:00:00.000",
  "eventEndDate": null,
  "type": "GeocachingHq",
  "geocacheType": {
    "id": 3773,
    "name": "Geocaching HQ",
    "imageUrl": "https://www.geocaching.com/images/wpttypes/3773.gif"
  },
  "size": "Other",
  "geocacheSize": {
    "id": 6,
    "name": "Other"
  },
  "userData": {
    "foundDate": "2016-06-24T12:00:00.000",
    "correctedCoordinates": {
      "latitude": 47,
      "longitude": -122
    },
    "isFavorited": false
  },
  "status": "Active",
  "location": {
    "country": "United States",
    "countryId": 2,
    "state": "Washington",
    "stateId": 48
  },
  "postedCoordinates": {
    "latitude": 47.648967,
    "longitude": -122.348117
  },
  "lastVisitedDate": "2018-11-29T12:00:00.000",
  "ownerCode": "PRA09E",
  "ownerAlias": "Geocaching HQ",
  "isPremiumOnly": false,
  "ianaTimezoneId": "America/Los_Angeles",
  "relatedWebPage": "http://geocachinghq.com/schedule/",
  "url": "https://coord.info/GCK25B",
  "backgroundImageUrl": null,
  "containsHtml": true,
  "owner": {
    "membershipLevelId": 2,
    "findCount": 0,
    "hideCount": 114,
    "favoritePoints": 1,
    "profileText": "Geocaching HQ is the home base for all Geocaching employees...",
    "url": "https://coord.info/PRA09E",
    "referenceCode": "PRA09E",
    "username": "Geocaching HQ",
    "avatarUrl": "https://img.geocaching.com/user/avatar/f777d091-4a90-406b-a998-70ec06b4f6f1.png"
  }
}

GeocacheLog

Fields
Name Type Description Required for Creation Can Be Updated (By Log Owner)
referenceCode string uniquely identifies the geocache log No No
ownerCode string identifier of the log owner No No
imageCount integer number of images associated with geocache log No No
loggedDate datetime date and time of when user logged the geocache in the timezone of the geocache Yes Yes
text string display text of the geocache log Yes Yes
type (Deprecated) string name of the geocache log type (see Geocache Log Types for more info) No No
geocacheLogType Type type of the geocache log (see Geocache Log Types for more info) Yes (only id field is required) Yes (only id field is required)
updatedCoordinates Coordinates latitude and longitude of the geocache (only used with log type 47 - Update Coordinates) Optional Yes
geocacheCode string identifier of the associated geocache Yes No
geocacheName string name of the associated geocache No No
ianaTimezoneId string timezone of the associated geocache No No
usedFavoritePoint bool if a favorite point was awarded from this log Optional, defaults to false No
isEncoded bool if log was encrypted using ROT13. This field is grandfathered to logs already set to true. New logs cannot be encoded. No No
isArchived bool if the log has been deleted No No
url string geocaching.com web page associated with geocache log No No
owner User information about the owner of the geocache log No No

Example

{
  "referenceCode": "GL5WEA9",
  "ownerCode": "PR27A02",
  "imageCount": 0,
  "loggedDate": "2004-06-02T00:00:00",
  "text": "Example log text.",
  "geocacheLogType": {
    "id": 2,
    "name": "Found It",
    "imageUrl": "https://www.geocaching.com/images/logtypes/2.png"
  },
  "isEncoded": false,
  "isArchived": false,
  "geocacheCode": "GCK25B",
  "geocacheName": "Geocaching Headquarters",
  "ianaTimezoneId": "America/Los_Angeles",
  "usedFavoritePoint": false,
  "url": "https://coord.info/GL5WEa9",
  "owner": {
    "findCount": 326,
    "hideCount": 0,
    "username": "MNofMind",
    "avatarUrl": "https://img-stage.geocaching.com/gcstage/{0}/0640f488-9abe-4c2a-a786-bb75cec84357.gif",
  }
}

Trackable

Fields
Name Type Description
referenceCode string uniquely identifies the trackable
iconUrl string link to image for trackable icon
name string display name of the trackable
imageCount int how many owner images on the trackable
goal string the owner's goal for the trackable
description string text about the trackable
releasedDate date when the trackable was activated
originCountry string where the trackable originated from
ownerCode string identifier about the owner
holderCode string user identifier about the current holder (null if not currently in someone's inventory)
inHolderCollection bool if the trackable is in the holder's collection
currentGeocacheCode string identifier of the geocache if the trackable is currently in one
currentGeocacheName string name of the geocache if the trackable is currently in one
isMissing bool flag is trackable is marked as missing
trackingNumber string unique number used to prove discovery of trackable. only returned if user matches the holderCode
trackableType Type type of the trackable
url string geocaching.com web page associated with trackable
owner User information about the owner of the trackable
holder User information about the holder of the trackable

Example

{
  "referenceCode": "TB1",
  "iconUrl": "http://www.geocaching.com/images/wpttypes/21.gif",
  "name": "Deadly Duck: Envy",
  "goal": "Tell a short story about committing the terrible sin of envy. Nothing incredibly evil. An example may be to envy that Ben & Jerry's pint the person at lunch was digging into.",
  "description": "While traveling north through New Mexico I encountered a vortex where 7 deadly ducks emerged from the gates of hell (not Hell, the flaming sort, but the lowercase hell where all the mischevious critters live).",
  "releasedDate": "2001-08-30T10:27:11",
  "originCountry": "United States",
  "allowedToBeCollected": false,
  "ownerCode": "PR3",
  "owner": {
    "username": "MNofMind",
    "avatarUrl": "https://img-stage.geocaching.com/gcstage/{0}/0640f488-9abe-4c2a-a786-bb75cec84357.gif",
    ...
  },
  "holderCode": null,
  "holder": null,
  "inHolderCollection": false,
  "isMissing": true,
  "trackableType": {
    "id": 21,
    "name": "Travel Bug Dog Tag",
    "imageUrl": "21.gif"
  },
  "trackingNumber": null,  
  "url": "https://coord.info/TB1"
}

TrackableLog

Fields
Name Type Description Required for Creation Can Be Updated (By Log Owner)
referenceCode string uniquely identifies the trackable log No No
ownerCode string reference code of the owner No No
trackableCode string identifier of the related trackable No (if not passed in, trackingNumber is required) No
geocacheCode string identifier of the related geocache Optional No
geocacheName string name of the related geocache if there is one Optional No
loggedDate date when the user logged the trackable Yes Yes
text string display text of the log Yes Yes
imageCount int how many images are associated with the log No No
isRot13Encoded bool flag for if the text is ROT13 encoded Optional, defaults to false Yes
typeId (Deprecated) integer type of the trackable log (see Trackable Log Types for more info) No No
trackableLogType Type type of the trackable log (see Trackable Log Types for more info) Yes (only id field is required) No
coordinates Coordinates latitude and longitude of the trackable log Optional No
trackingNumber string code only found on the trackable itself (only needed for creating a log, this will not be returned with any GET methods) Required for retrieving from geocache, grab it, and discovered it activity types No
url string geocaching.com web page associated with trackable log No No
owner User information about the owner of the trackable log No No

Example

{
  "referenceCode": "TL2A",
  "ownerCode": "PR2E27",
  "owner": {
    "username": "MNofMind",
    "avatarUrl": "https://img-stage.geocaching.com/gcstage/{0}/0640f488-9abe-4c2a-a786-bb75cec84357.gif",
    ...
  },
  "imageCount": 0,
  "trackableCode": "TB1",
  "loggedDate": "2001-09-28T00:00:00",
  "text": "I envy Cache Maru's eTrex Vista, with it's amazing 24M of memory, color screen, and maps, way beyond my eTrex Summit.  Oh Garmin V, when will you come, so someone will envy me...\r\n\r\nI have Envy, given to Denise by jeremy and then given to me.  I bet you envy me now!  I hope to place envy during a Q-13 tv crew cache, stay tuned!",
  "isRot13Encoded": false,
  "trackableLogType": {
    "id": 19,
    "name": "Grab It (Not from a Cache)",
    "imageUrl": "https://www.geocaching.com/images/logtypes/19.png"
  },
  "url": "https://coord.info/TL2A"
}

LogDraft

Fields
Name Type Description Required for Creation Can Be Updated (By Draft Owner)
referenceCode string uniquely identifies the log draft No No
geocacheCode string identifer of the geocache Yes No
geocacheName string name of the geocache No No
logType (Deprecated) string name of the geocache log type (see Geocache Log Types for more info) No No
geocacheLogType Type type of the geocache log (see Geocache Log Types for more info) Yes (only the id field is required) No
note string display text of the log draft Optional Yes
loggedDateUtc datetime when the user logged the geocache in UTC Optional, defaults to current datetime No
imageCount integer number of images associated with draft No No
useFavoritePoint boolean whether to award favorite point when Optional, defaults to false Yes

Example

{
  "referenceCode": "LD7Z53GB",
  "geocacheCode": "GCK25B",
  "geocacheLogType": {
    "id": 2,
    "name": "Found It",
    "imageUrl": "https://www.geocaching.com/images/logtypes/2.png"
  },
  "note": "example draft text",
  "loggedDateUtc": "2017-10-13T16:28:59.51"
}

UserWaypoint

Fields
Name Type Description Required for Creation Can Be Updated (By Waypoint Owner)
referenceCode string uniquely identifies the user waypoint No No
description string text about the waypoint Optional Yes
isCorrectedCoordinates bool whether the user waypoint are corrected coordinates Yes Yes
coordinates Coordinates latitude and longitude of the waypoint Yes Yes
geocacheCode string identifier of the related geocache Yes No

Example

{
    "referenceCode": "UW167H5Q",
    "description": "Coordinate Override",
    "isCorrectedCoordinates": true,
    "coordinates": {
        "latitude": 0.6489666666666667,
        "longitude": -0.3481166666666667
    },
    "geocacheCode": "GCK25B"
}

AdditionalWaypoint

Fields
Name Type Description
name string display name of the waypoint
description string text about the waypoint
typeId integer type of the waypoint (see Waypoint Types for more info)
typeName string display name of the type
prefix string short category prefix of the waypoint type
url string geocaching.com web page associated with the waypoint
coordinates Coordinates latitude and longitude of the waypoint

Example

{
    "name": "GCK25B Parking",
    "coordinates": {
        "latitude": 47.64896666666667,
        "longitude": -122.34811666666667
    },
    "description": "test additional waypoint",
    "typeId": 217,
    "typeName": "Parking Area",
    "prefix": "PK",
    "url": "https://geocaching.com/seek/wpt.aspx?WID=12345"
}

Attribute

Fields
Name Type Description
id integer identifier of the attribute
name string display name of the attribute
isOn boolean flag for if the attribute is a positive or negative (e.g. available 24/7 vs not available 24/7)
imageUrl string link to the image for the attribute

Example

{
   "id": 1,
   "name": "Dogs",
   "isOn": true,
   "imageUrl": "https://www.geocaching.com/images/attributes/dogs-yes.gif"
}

Attribute Type

Fields
Name Type Description
id integer identifier of the attribute
name string display name of the attribute
hasYesOption boolean flag for if the attribute can be set to isOn = true
hasNoOption boolean flag for if the attribute can be set to isOn = false
yesIconUrl string image url for the attribute if isOn = true
noIconUrl string image url for the attribute if isOn = false
notChosenIconUrl string image url for the attribute if not chosen

Example

{
   "id": 1,
   "name": "Dogs",
   "hasYesOption": true,
   "hasNoOption": true,
   "yesIconUrl": "https://www.geocaching.com/images/attributes/dogs-yes.gif",
   "noIconUrl": "https://www.geocaching.com/images/attributes/dogs-no.gif"
}

Location

Fields
Name Type Description
countryId integer id of country
country string display name of country
stateId integer id of state
state string display name of state

Example

{
    "country": "United States",
    "countryId": 2,
    "state": "Washington",
    "stateId": 48
}

Size

Fields
Name Type Description
id integer id of size
name string display name of size

Example

{
    "id": 6,
    "name": "Other"
}

List

Fields
Name Type Description Required for Creation Can Be Updated (By List Owner)
referenceCode string uniquely identifies the list No No
createdDateUtc datetime when the list was created in UTC No No
lastUpdatedDateUtc datetime when the list was last updated in UTC. for pocket queries, this represents the last time the query was generated No No
name string display name of the list Yes Yes
count integer how many geocaches are in the list No No
findCount integer how many of the geocaches in list are found No No
ownerCode string identifier of the user who owns the list No No
description string text about the list No Yes
typeId integer type of the list (see List Types for more info) No (defaults to bookmark list type) No
isShared bool if the list is accessible through a direct link Yes Yes
isPublic bool if the list is accessible to everyone without a direct link Yes Yes
url string geocaching.com web page associated with list (no url returned for pocket query types) No No

Example

{
  "referenceCode": "BM4GC42",
  "lastUpdatedDateUtc": "2017-10-13T17:45:04.603Z",
  "createdDateUtc": "2017-10-13T17:45:04.38Z",
  "count": 1,
  "ownerCode": "PR27A92",
  "name": "HQ Geocaches",
  "description": "to grab the HQ icon",
  "typeId": 2,
  "isPublic": false,
  "isShared": false,
  "url": "https://coord.info/BM4GC42"
}

List Geocache

Fields
Name Type Description
referenceCode string uniquely identifies the geocache
listItemName string user generated name of list item
name string name of the geocache
difficulty decimal difficulty rating of the geocache between 1.0 and 5.0
terrain decimal terrain rating of the geocache between 1.0 and 5.0
favoritePoints integer number of favorite points awarded to the geocache
trackableCount integer number of trackables currently in the geocache
placedDate datetime date when the cache was placed (if an event, this is the date of the event) in the timezone of the geocache
publishedDate datetime date when the cache was published in the timezone of the geocache
type (Deprecated) enum type of the geocache (see Geocache Types for more info)
geocacheType Type type of the geocache (see Geocache Types for more info)
size (Deprecated) enum size of the geocache container (see Geocache Sizes for more info)
geocacheSize Size size of the geocache (see Geocache Sizes for more info)
userData UserData user specific information about the geocache
status enum current status of the geocache (see Geocache Statuses for more info)
location Location country and state information about the geocache
postedCoordinates Coordinates latitude and longitude of the geocache
lastVisitedDate nullable datetime datetime of last logged visit to geocache in the timezone of the geocache
ownerCode string owner identifier of the geocache
ownerAlias string display name of owner for geocache
isPremiumOnly boolean whether the geocache can only be viewed by premium members
shortDescription string summary about the geocache
longDescription string details about the geocache
hints string hints/spoilers to help to find the geocache
attributes array of Attributes attributes of the geocache
ianaTimezoneId string timezone of the geocache
relatedWebPage string external web page associated with geocache
url string geocaching.com web page associated with geocache
containsHtml bool flag for if the short or long description contains html
owner User information about the owner of the geocache No No
additionalWaypoints array of AdditionalWaypoint other reference waypoints associated with the geocache

Example

{
    "referenceCode": "GCK25B",
    "listItemName": "GCHQ!",
    "name": "Geocaching Headquarters"
    ...
}

List Item

Fields
Name Type Description
referenceCode string uniquely identifies the geocache
name string name of the geocache

Example

{
    "referenceCode": "GCK25B",
    "name": "Geocaching Headquarters"
}

BulkResponse

Fields
Name Type Description
successes string array array of identifiers for which the bulk operation was successful
failures BulkFailure array of identifiers and reasons for which the bulk operation was unsuccessful

Example

{
    "successes": [
        "gc1"
    ],
    "failures": [
        {
            "referenceCode": "gc2",
            "message": "gc2 already exists in BM123",
            "statusCode": 409
        }
    ]
}

BulkFailure

Fields
Name Type Description
referenceCode string identifier for which bulk request item was unsuccessful
message string reason for why the bulk operation was unsuccessful
statusCode int HTTP status code for why the bulk operation was unsuccessful

Example

{
    "referenceCode": "gc2",
    "message": "gc2 already exists in BM123",
    "statusCode": 409
}

User

Fields
Name Type Description
referenceCode string uniquely identifies the user
findCount integer how many geocache finds the user has
hideCount integer how many geocache hides the user has
favoritePoints integer how many favorite points the user has avaiable
username string the display username
membershipLevelId integer type of the membership (see Membership Types for more info)
avatarUrl string link to image of the user's profile avatar
bannerUrl string link to image of the user's banner image
url string geocaching.com web page associated with user profile No No
profileText string text from Profile Information section on user profile page
homeCoordinates Coordinates latitude and longitude of the user's home location
geocacheFindCounts Array of GeocacheCount find counts per geocache type for user
geocacheHideCounts Array of GeocacheCount hide counts per geocache type for user
trackableFindCounts Array of TrackableCount find counts per trackable type for user
trackableOwnedCounts Array of TrackableCount owned counts per trackable type for user
geocacheLimits GeocacheLimit how many geocaches/lite geocaches the user has remaining and time to live until limit is refreshed

Example

{
  "referenceCode": "PR27A92",
  "findCount": 326,
  "hideCount": 0,
  "favoritePoints": 18,
  "username": "MNofMind",
  "membershipLevelId": 3,
  "avatarUrl": "https://img-stage.geocaching.com/gcstage/{0}/0640f488-9abe-4c2a-a786-bb75cec84357.gif",
  "homeCoordinates": {
    "latitude": 47.6760654544942,
    "longitude": -122.318150997162
  },
  "geocacheFindCounts": [
    {
      "geocacheType": {
        "id": 3773,
        "name": "Geocaching HQ",
        "imageUrl": "https://www.geocaching.com/images/wpttypes/3773.gif"
      },
      "count": 1
    },
    {
      "geocacheType": {
        "id": 3,
        "name": "Multi-cache",
        "imageUrl": "https://www.geocaching.com/images/wpttypes/3.gif"
      },
      "count": 1
    },
    {
      "geocacheType": {
        "id": 4,
        "name": "Virtual Cache",
        "imageUrl": "https://www.geocaching.com/images/wpttypes/4.gif"
      },
      "count": 2
    },
    {
      "geocacheType": {
        "id": 2,
        "name": "Traditional Cache",
        "imageUrl": "https://www.geocaching.com/images/wpttypes/2.gif"
      },
      "count": 33
    },
    {
      "geocacheType": {
        "id": 11,
        "name": "Webcam Cache",
        "imageUrl": "https://www.geocaching.com/images/wpttypes/11.gif"
      },
      "count": 1
    },
    {
      "geocacheType": {
        "id": 8,
        "name": "Unknown (Mystery) Cache",
        "imageUrl": "https://www.geocaching.com/images/wpttypes/8.gif"
      },
      "count": 7
    }
  ],
  "geocacheHideCounts": [
    {
      "geocacheType": {
        "id": 2,
        "name": "Traditional Cache",
        "imageUrl": "https://www.geocaching.com/images/wpttypes/2.gif"
      },
      "count": 6
    },
    {
      "geocacheType": {
        "id": 3,
        "name": "Multi-cache",
        "imageUrl": "https://www.geocaching.com/images/wpttypes/3.gif"
      },
      "count": 2
    }
  ],
  "trackableFindCounts": [
    {
      "trackableType": {
        "id": 21,
        "name": "Travel Bug Dog Tags",
        "imageUrl": "http://www.geocaching.com/images/wpttypes/21.gif"
      },
      "count": 6
    },
    {
      "trackableType": {
        "id": 22,
        "name": "Moun10Bike Geocoins",
        "imageUrl": "http://www.geocaching.com/images/wpttypes/22.gif"
      },
      "count": 1
    },
    {
      "trackableType": {
        "id": 328,
        "name": "Cache Run Geocoins",
        "imageUrl": "http://www.geocaching.com/images/wpttypes/328.gif"
      },
      "count": 1
    }
  ],
  "trackableOwnedCounts": [
    {
      "trackableType": {
        "id": 21,
        "name": "Travel Bug Dog Tags",
        "imageUrl": "http://www.geocaching.com/images/wpttypes/21.gif"
      },
      "count": 1
    }
  ],
  "geocacheLimits": {
    "liteCallsRemaining": 10000,
    "liteCallsSecondsToLive": null,
    "fullCallsRemaining": 2,
    "fullCallsSecondsToLive": 216000
  }
}

FriendRequest

Fields
Name Type Description Required for Creation
id integer uniquely identifies the friend request No
requestorUserCode string identifier of the user that initiated the friend request No
requestor UserReference user information about the requestor No
requestedUserCode string identifier of the user that received the friend request Yes
requested UserReference user information about the requested user No
message string requestor custom text to go along with the request Yes
isOutgoing boolean flags requests as true if calling user is the requestor No
requestDateUtc datetime the date the request was made in UTC No

Example

{
    "id": 123456,
    "requestorUserCode": "PR123",
    "requestor": {
        "referenceCode": "PR123",
        "username": "fakeusername",
        "avatarUrl": "https://geocaching.com/images/default_avatar.png"
    },
    "requestedUserCode": "PR456",
    "requested": {
        "referenceCode": "PR456",
        "username": "fakeusername2",
        "avatarUrl": "https://geocaching.com/images/default_avatar.png"
    }
    "message": "let's become friends!",
    "isOutgoing": false
}

GeocacheLimit

Fields
Name Type Description
liteCallsRemaining integer number of lite geocaches the user can fetch during the current limit
liteCallsSecondsToLive nullable integer number of seconds until lite geocache limit will be refreshed. if null, no limit has been started yet (limit begins at first lite geocache call)
fullCallsRemaining integer number of non-lite geocaches the user can fetch during the current limit
fullCallsSecondsToLive nullable integer number of seconds until non-lite geocache limit will be refreshed. if null, no limit has been started yet (limit begins at first non-lite geocache call)

Example

{
    "liteCallsRemaining": 10000,
    "liteCallsSecondsToLive": null,
    "fullCallsRemaining": 2,
    "fullCallsSecondsToLive": 216000
}

GeocacheCount

Fields
Name Type Description
GeocacheType Type type information of the geocache
Count integer total count of geocache type

Example

{
  "geocacheType": {
    "id": 3773,
    "name": "Geocaching HQ",
    "imageUrl": "https://www.geocaching.com/images/wpttypes/3773.gif"
  },
  "count": 1
}

TrackableCount

Fields
Name Type Description
TrackableType Type type information of the trackable
Count integer total count of trackable type

Example

{
  "trackableType": {
    "id": 21,
    "name": "Travel Bug Dog Tag",
    "imageUrl": "21.gif"
  },
  "count": 1
}

Souvenir

Fields
Name Type Description
title string display name of the souvenir
description string text about the souvenir
imagePath string link url to the image of the souvenir
thumbImagePath string link url to the thumbnail image of the souvenir
foundDateUtc datetime when the souvenir was awarded in UTC
url string link to souvenir details on www.geocaching.com website

Example

{
    "imagePath": "https://souvenirs.geocaching.com/SouvenirImages/Ni84LzIwMTA/472f96b3-e23b-489b-a0f2-115df3e362f0.png",
    "thumbImagePath": "https://souvenirs.geocaching.com/SouvenirImages/NS8yMy8yMDE4/ad3ee1df-589a-420b-a349-1611ac84bfcf.png",
    "title": "Geocaching Headquarters",
    "description": "Geocaching Headquarters - also known as the \"lily pad\" - moved to the Fremont neighborhood of Seattle in October 2009. The Headquarters cache (GCK25B) is part of the \"Triad\" - one of the ultimate geocaching goals. To complete the Triad, geocachers must log the HQ cache, the original geocache location (GCGV0P) and the Project A.P.E. cache Mission 9: Tunnel of Light (GC1169).",
    "foundDateUtc": "2016-06-25T01:00:00",
    "url": "https://www.geocaching.com/souvenir?guid=3d451b99-0fb3-4d56-9c48-3f3d9e90be02"
}

Image

Fields
Name Type Description
description string text about the image
url string link url to the image
thumbnailUrl string link url to the image with a height of 75px
largeUrl string link url to the image with a larger height
referenceCode string identifier of the related entity (geocache log, trackable log, etc.)
createdDate DateTime date image was uploaded in UTC

Example

{
    "url": "https://someurl/photo",
    "thumbnailUrl": "https://someurl/avatar/photo",
    "largeUrl": "https://someurl/large/photo",
    "referenceCode": "GLXXX",
    "description": "Great Scenery"
}

ImageToUpload

Fields
Name Type Description
description string text about the image
base64ImageData string image data
guid Guid optional unique identifier to prevent duplicate uploads

Example

{
    "base64ImageData": "base64 data string here",
    "description": "Great Scenery"
}

UserData

Fields
Name Type Description
note string personal geocache note only visible to user
isFavorited bool if the user has awarded this geocache a favorite point
foundDate nullable datetime the date the user found the geocache in the timezone of the geocache (null if not found)
dnfDate nullable datetime the date the user logged a DNF on the geocache in the timezone of the geocache (null if no DNF exists)
correctedCoordinates Coordinates latitude and longitude of the user's solved coordinates

Example

{
    "foundDate": "2017-10-03T23:37:53.079Z",
    "dnfDate": "2017-05-03T12:34:26.648Z"
    "correctedCoordinates": {
        "latitude": 0,
        "longitude": 0
    },
    "isFavorited": true,
    "note": "personal cache note here"
}

Coordinates

Fields
Name Type Description
latitude decimal the latitude in decimal format
longitude decimal the longitude in decimal format

Example

{
    "latitude": 47.5,
    "longitude": -122.5
}

UserReference

Fields
Name Type Description
referenceCode string identifier of the user
username string the display username
avatarUrl string source link of user avatar image

Example

{
    "referenceCode": "PRFAKEUSER",
    "username": "fakeusername",
    "avatarUrl": "https://geocaching.com/images/default_avatar.png"
}

Type

Fields
Name Type Description
id integer identifier of the type
name string the name of the type
imageUrl string link to the image of the type

Example

{
    "id": "2",
    "name": "Found It",
    "imageUrl": "https://www.geocaching.com/images/logtypes/2.png"
}

Reference Data

Geocache Types

Id Name
2 Traditional
3 Multi-Cache
4 Virtual
5 Letterbox Hybrid
6 Event
8 Mystery/Unknown
9 Project A.P.E.
11 Webcam
12 Locationless (Reverse) Cache
13 Cache In Trash Out Event
137 Earthcache
453 Mega-Event
1304 GPS Adventures Exhibit
1858 Wherigo
3653 Lost and Found Event Cache
3773 Geocaching HQ
3774 Geocaching Lost and Found Celebration
4738 Geocaching Block Party
7005 Giga-Event

Geocache Statuses

Id Name
1 Unpublished
2 Active
3 Disabled
4 Locked
5 Archived

Geocache Sizes

Id Name
1 Unknown
2 Micro
8 Small
3 Regular
4 Large
5 Virtual
6 Other

Geocache Log Types

Id Name Description
2 Found It found the geocache
3 DNF it Did Not Find (DNF) the geocache
4 Write note Adding a comment to the geocache
5 Archive changing the status of the geocache to archived
7 Needs archiving flagging the geocache as needing to be archived
9 Will attend RSVPing for an event
10 Attended Attended an event (counts as a find)
11 Webcam photo taken Successfully captured a webcam geocache (counts as a find)
12 Unarchive changing the status of the geocache from archived to active
22 Temporarily Disable Listing changing the status of the geocache to disabled
23 Enable Listing changing the status of the geocache from disabled to active
24 Publish Listing changing the status of the geocache from unpublished to active
45 Needs Maintenance flagging a geocache owner that the geocache needs some attention
46 Owner Maintenance announcing that owner maintenance was done
47 Update Coordinates updating the coordinates of the geocache
68 Post Reviewer Note a note left by the reviewer
74 Event Announcement event host announcement to attendees

Trackable Log Types

Id Name
4 Write Note
13 Retrieve It from a Cache
14 Dropped Off
15 Transfer
16 Mark Missing
19 Grab It (Not from a Cache)
48 Discovered It
69 Move to Collection
70 Move to Inventory
75 Visited

List Types

Id Name
1 Pocket Query (pq)
2 Bookmark (bm)
3 Ignore (il)
4 Watch (wl)
5 Favorites (fl)

Membership Types

Id Name
0 Unknown
1 Basic
2 Charter
3 Premium

Additional Waypoint Types

Id Name
217 Parking Area
218 Virtual Stage
219 Physical Stage
220 Final Location
221 Trailhead
452 Reference Point

Change Log

04.15.2019

03.11.2019

11.26.2018

10.08.2018

08.27.2018

07.23.2018

06.18.2018

06.06.2018

Guide to Replacing LiveV6 API

LiveV6 MethodReplacement MethodsNotes
AddFavoritePointToCacheAdd Geocache To Listadd geocache to the user's favorites list
AddGeocachesToBookmarkListAdd Geocache To Listadd geocache to the user's bookmark list
CreateFieldNoteAndPublishCreate Geocache Logto replace the geocache log functionality
CreateFieldNoteAndPublishCreate Log Draft/Add Log Draft Imageto replace the draft (fka field note) functionality
CreateTrackableLogCreate Trackable Log-
DeleteCacheNoteDelete Geocache Note-
DeleteUserWaypointDelete User Waypoint-
GeocodeStringN/Aretired method
GetAnotherUsersProfileGet User-
GetAPILimitsN/Acurrently no replacement
GetAttributeTypesDataN/Acurrently no replacement
GetBookmarkListByGuidGet Listguids will no longer be used for identifiers
GetBookmarkListsByUserIDN/Acurrently no replacement
GetBookmarkListsForUserGet User Listsids will no longer be used for identifiers
GetCacheByTileGuidN/Aretired method
GetCacheIdsFavoritedByUserGet Listrequest favorites list
GetCachesFavoritedByUserGet Listrequest favorites list
GetFullPocketQueryDataGet Listrequest pocket query list
GetGeocacheDataTypesN/Acurrently no replacement
GetGeocacheLogsByCacheCodeGet Geocache's Logs-
GetGeocacheStatusGet Geocacheuse fields parameter to minimize object to statuses
GetGeocacheTypesN/Acurrently no replacement
GetImagesForGeocacheGet Geocache Images-
GetMembershipTypesN/Acurrently no replacement
GetMoreGeocachesN/Aretired method
GetOwnedTrackablesGet Trackables-
GetPocketQueryDataGet List-
GetPocketQueryDataGet User Lists-
GetPocketQueryZippedFileN/Aretired method
GetSiteStatsN/Aretired method
GetTrackableLogsByTBCodeGet Trackable's Logs-
GetTrackablesByTBCodeGet Trackable-
GetTrackablesByTrackingNumberN/Acurrently no replacement
GetTrackablesInCacheGet Geocache's Trackables-
GetTrackableTravelListN/Aretired method
GetUserCredentialsN/Aretired method
GetUserGalleryGet User Images-
GetUsersCacheCountsGet User-
GetUsersCacheNotesGet Geocacheget the userData nested object
GetUsersFavoritePointsGet User-
GetUsersGeocacheLogsN/Acurrently no replacement
GetUsersTrackablesGet User Trackables-
GetUsersTrackablesGet User Trackables-
GetUsersWhoFavoritedCacheN/Acurrently no replacement
GetUserWaypointsGet User Waypoints-
GetWptLogTypesN/Acurrently no replacement
GetYourUserProfileGet User-
GetYourUserProfileGet User-
PingPing/status/ping
RegisterWP7DeviceTileN/Aretired method
RemoveFavoritePointFromCacheRemove Geocache From List-
SaveUserWaypointCreate User Waypoint/ Update User Waypoint-
SearchForGeocachesSearch-
SearchForSouvenirsByPublicGuidN/Acurrently no replacement
UpdateCacheNoteUpsert Geocache Note-
UploadImageToGeocacheLogAdd Geocache Log Image-
UploadImageToTrackableLogAdd Trackable Log Image-
WindowsPhoneTileSearchN/Aretired method