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 and requires 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 and 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.

Example code_verifier and code_challenge:
Code verifier (random string (ASCII characters) using the unreserved characters [A-Z][a-z][0-9]["-",".","_","~"]):
mg828Je82M441flIEEVQOm420IfdI_06v2u9HM212kgM7anId9Am_FF42m2aPE93n35M1HFxQMsy6ZvMNfq

Code challenge (base64-url encoded SHA256 hash):
qJCP3nUndZTovT_1mYcjMeNRTmdflWclG8vf7shmv28

Requirements: In order to utilize OAuth 2.0, partners need to provide Geocaching HQ with the application's staging and production redirect uris. The redirect uri passed in during the authorization process will be verified against the known uris by matching exactly. 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 Yes 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". defaults to "plain".
state No consumer provided code to mitigate XSRF attacks.
signup No optional boolean parameter to take logged out users directly to the signup page instead of the login page.
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&code_challenge=qJCP3nUndZTovT_1mYcjMeNRTmdflWclG8vf7shmv28
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=qJCP3nUndZTovT_1mYcjMeNRTmdflWclG8vf7shmv28
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 for this specific method 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 Yes the secret generated for implementing PKCE
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 for this specific method 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. If geocache data is request and the limit has been reached, the API will return a 403 (Forbidden) response.

Trackable Discovery Limits

Users are limited to 500 trackable discoveries per 24 hours per API license (500 discovered logs per user/license combination). If a user has surpassed the limit, the API will return a 403 (Forbidden) response.

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

To give users greater control of their data and in the interest of providing additional privacy settings, users now have the ability to opt-out of sharing their personal data with API Authorized Developers in their account settings. If a user has not authorized the sharing of their personal data, the API will either throw a 403 Forbidden exception or return only the reference code and opted-out user as the username with the reference code also returned as part of a comma delimited list of strings in the header named x-opted-out.

User Privacy Settings

In addition to third party data sharing control, users may also control who can see certain pieces of information from their profile/account. If an API call violates these settings, a 403 Forbidden may be thrown or the data being restricted will return null in the response. There's additional information about these privacy settings under the section for Get User Privacy Settings.

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

Sorting

Sorting is supported on methods that specify a query string parameter named sort. The syntax for using query sorts is the name (or alias) of the available option and a plus (+) or minus (-) sign to denote ascending or descending order. If sorting by distance, the coordinates to use for the sorting can be denoted by adding a colon (:) and coordinates ([47,-122]) to the end of the plus or minus. Available sorting options can be found at the method documentation.

Example: dist+:[47,-122]
Example: name-

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
Response Codes: 200, 400, 401, 403, 404, 429, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Opted-out users will filter out profile details. See Third Party Data Sharing for more details.


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, geotours, 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
Response Codes: 200, 400, 401, 403, 429, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Opted-out users will filter out profile details. See Third Party Data Sharing for more details.


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, geotours, and images. -

Verify Final Coordinates

This method will check the specified geocache using to validate if the final coordinates match.

Path: /v1/geocaches/{referenceCode}/finalcoordinates
HTTP Method: POST
Response Type: N/A
Response Codes: 204, 400, 401, 403, 429, 500
Restrictions: The geocache must be published, non-archived, a mystery type, and opted in to use the native geocaching solution checker (if not true will return 403 Forbidden). Basic members trying to verify against a premium only geocache will return a 403 Forbidden response. Solution checking is throttled the same as the website (ten guesses in ten minutes for a user on a single geocache) and if exceeded will return a 429 response. This method will return 204 if the coordinates match or a 400 if the coordinates do not match.


Parameters
Argument Type Example Required Description Default
referenceCode query referenceCode=GCK25B Yes the identifier of the geocache -
coordinates body Coordinates Yes The latitude and longitude in decimal format to verify -
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, geotours, 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
Response Codes: 200, 400, 401, 403, 404, 429, 500
Restrictions: Geocache log images from opted-out users will not be included. See Third Party Data Sharing for more details.


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, 429, 500
Restrictions: Only owner may update the note. Geocache notes are a premium member only feature. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 403, 409, 429, 500
Restrictions: Only owner may delete the geocache note. Geocache notes are a premium member only feature. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 429, 500


Get Geocache Sizes

This method will fetch all valid geocache sizes

Path: /v1/geocachesizes
HTTP Method: GET
Response Type: Array of Geocache Sizes
Response Codes: 200, 401, 429, 500


Get Geocache Statuses

This method will fetch all valid geocache statuses

Path: /v1/geocachestatuses
HTTP Method: GET
Response Type: Array of strings
Response Codes: 200, 401, 429, 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, 429, 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, 403, 404, 429, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Opted-out users will filter out profile details. See Third Party Data Sharing for more details.


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
sort query sort="newest" No How to order the geocache logs. The options are newest, greatstory, or helpful. All sorts are in descending order. Greatstory and helpful sorts are based on log upvote data. newest
logtypes query logTypes=2,10,11 No The log types to include in the results (see restrictions). all types included

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, 429, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Opted-out users will filter out profile details. See Third Party Data Sharing for more details.


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. -

Get Geocache Log Upvotes

This method will fetch the upvote counts and calling user details about the specified geocache logs using the reference code

Path: /v1/geocachelogs/upvotes
HTTP Method: GET
Response Type: Array of Geocache Log Upvote data
Response Codes: 200, 400, 401, 404, 429, 500


Parameters
Argument Type Example Required Description Default
referenceCodes query GL100,GL101 Yes comma delimited string of the identifiers of the geocache log -
fields query fields=geocachelogcode,upvotetypecounts No partial response fields to return geocachelogcode

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, 403, 404, 409, 422, 429, 500
Restrictions: Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 429, 500
Restrictions: Only owner of geocache log may update the log. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 429, 500
Restrictions: Only owner of geocache log may delete the log. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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

Add Geocache Log Upvote

This method will add an upvote to a specified geocache log.

Path: /v1/geocachelogs/{referenceCode}/upvotes/{upvoteTypeId}
HTTP Method: POST
Response Type: GeocacheLogUpvoteData
Response Codes: 201, 400, 401, 403, 429, 500
Restrictions: Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


Parameters
Argument Type Example Required Description Default
referenceCode path GL100 Yes the identifier of the geocache log -
upvoteTypeId path 1 Yes the identifier of the geocache log upvote type -
fields query fields=geocachelogcode,upvotetypecounts No partial response fields to return geocachelogcode

Delete Geocache Log Upvote

This method will remove an upvote from a specified geocache log.

Path: /v1/geocachelogs/{referenceCode}/upvotes/{upvoteTypeId}
HTTP Method: DELETE
Response Type: No response body
Response Codes: 204, 400, 401, 403, 429, 500
Restrictions: Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


Parameters
Argument Type Example Required Description Default
referenceCode path GL100 Yes the identifier of the geocache log -
upvoteTypeId path 1 Yes the identifier of the geocache log upvote type -

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, 403, 404, 429, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 429, 500
Restrictions: Only owner of geocache log may add an image. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 429, 500
Restrictions: Only owner of geocache log may delete an image. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 429, 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, 403, 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
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, 429, 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, 429, 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 Journeys

This method will fetch the requested trackable's journey/travel history.

Path: /v1/trackables/{referenceCode}/journeys
HTTP Method: GET
Response Type: Array of Journeys
Response Codes: 200, 400, 401, 403, 404, 429, 500


Parameters
Argument Type Example Required Description Default
referenceCode path TB1 Yes The reference code of the trackables. -
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 1000 100

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, 429, 500
Restrictions: Opted-out users will filter out profile details. See Third Party Data Sharing for more details.


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
Restrictions: Opted-out users will filter out profile details. See Third Party Data Sharing for more details.


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. -

Get User's Trackable Log

This method will fetch the calling user's trackable logs ordered by newest logs descending.

Path: /v1/trackablelogs
HTTP Method: GET
Response Type: Array of Trackable Logs
Response Codes: 200, 400, 401, 403, 429, 500
Restrictions: Method only works with calling user. Opted-out users will return a Forbidden response. See Third Party Data Sharing for more details.


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=referenceCode,text,url 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, 403, 404, 409, 500
Restrictions: Users may only discover 500 trackables per 24 hours per API license key. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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

Bulk Create Trackable Logs

This method will bulk create trackable logs on the specified geocache.

Path: /v1/geocaches/{referenceCode}/bulktrackablelogs
HTTP Method: POST
Response Type: BulkResponse
Response Codes: 204, 400, 401, 404, 429, 500
Restrictions: Maximum of 50 logs may be created in bulk. Users may only discover 500 trackables per 24 hours per API license key. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


Parameters
Argument Type Example Required Description Default
referenceCode query referenceCode=GCK25B Yes the identifier of the geocache -
logs body array of TrackableLogs Yes trackable logs to create -
fields query fields=name,state 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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 403, 404, 500
Restrictions: Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 429, 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, 403, 404, 409, 500
Restrictions: Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


Parameters
Argument Type Example Required Description Default
referenceCode path ld100 Yes the identifier of the log draft -
image body PostImage Yes the image 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, 429, 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, 403, 404, 409, 500
Restrictions: Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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
Restrictions: Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 403, 404, 429, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Users may only see their own lists or lists marked public. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 403, 404, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, geotours, and images. -

Response Type: Array of List Geocaches or Lite List Geocaches
Response Codes: 200, 400, 401, 403, 404, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Users may opt out of sharing personal data, which include lists.


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, 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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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 ListGeocache 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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 403, 409, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info. Only owner may delete the user waypoint. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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, 429, 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. Requesting non-public log types will return 403 Forbidden status. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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
geocacheCode query geocacheCode=GCK25B No filters results to a single geocache if provided all geocaches 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. Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details.


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: Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details. This endpoint may also be restricted by user privacy settings. See User Privacy Settings for more details.


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: Opted-out user will return a 403 Forbidden status. See Third Party Data Sharing for more details. This endpoint may also be restricted by user privacy settings. See User Privacy Settings for more details.


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

Get Favorited Users by Geocache

This method will fetch the users that have favorited the specified geocache.

Path: /v1/geocaches/{referenceCode}/favoritedby
HTTP Method: GET
Response Type: Array of Users
Response Codes: 200, 400, 401, 403, 404, 429, 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 GCK25B Yes the identifier of the geocache -
fields query fields=username,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 Privacy Settings

This method will fetch a user's privacy settings

Path: GET /v1/users/{referenceCode}/privacysettings
HTTP Method: GET
Response Type: Dictionary <string, object> (See User Privacy Settings)
Response Codes: 200, 400, 401, 403, 404, 429, 500


Parameters
Argument Type Example Required Description Default
referenceCode path PR18 Yes the reference code of the user -

Get Opted-out Users

This method will fetch the user reference codes that have opted-out of sharing their data with third party applications.

Path: /v1/optedoutusers
HTTP Method: GET
Response Type: Array of strings
Response Codes: 200, 400, 401, 403, 404, 429, 500
Restrictions: This method is throttled to one call per 24 hours per API license (30 calls per 24 hours in staging).


Parameters
Argument Type Example Required Description Default
updatedSinceUtc query 2020-01-01 Yes filters the results to users that have opted-out after this UTC DateTime -

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, 429, 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 -

Get Friends' Geocache Logs By Geocache

This method will fetch the geocache logs of friends for a specified geocache.

Path: /v1/friends/geocaches/{referenceCode}/geocachelogs
HTTP Method: GET
Response Type: Array of GeocacheLogs
Response Codes: 200, 400, 401, 404, 429, 500


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
logTypes query logTypes=2,10,11 No Comma delimited list of log types to filter results. Defaults to returning all log types. -
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

GeoTour Methods

Get GeoTour

This method will fetch the specified GeoTour.

Path: /v1/geotours/{referenceCode}
HTTP Method: GET
Response Type: GeoTour
Response Codes: 200, 400, 401, 403, 404, 429, 500


Parameters
Argument Type Example Required Description Default
referenceCode path GT29 Yes the identifier of the geotour -
fields query fields=name,referenceCode No partial response fields to return referenceCode

Get GeoTours

This method will fetch a paginated array of GeoTours.

Path: /v1/geotours
HTTP Method: GET
Response Type: array of GeoTours
Response Codes: 200, 400, 401, 403, 429, 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 20
sort query sort=name+ false How to sort the returned geotours. See sorts for options. unsorted
fields query fields=name,referenceCode No partial response fields to return referenceCode

GeoTours Sorting Options
Name Alias Example Description
distance dist dist+:[47,-122] sort by distance, coordinates must be added to the sort value
name N/A name+ sort by the geotour name alphabetically

Get Geocaches on a GeoTour

This method will fetch a paginated array of geocaches that belong to specified GeoTour.

Path: /v1/geotours/{referenceCode}/geocaches
HTTP Method: GET
Response Type: Array of Geocaches or Lite Geocaches
Response Codes: 200, 400, 401, 403, 404, 429, 500


Parameters
Argument Type Example Required Description Default
referenceCode path GT29 Yes the identifier of the geotour -
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 20
sort query sort=name+ false How to sort the returned resources. See sorts for options. geotour+
lite query lite=false false Whether the results should come back as lite geocaches or full geocaches true
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, geotours, and images. -
fields query fields=name,referenceCode No partial response fields to return referenceCode

GeoTour Geocache Sorting Options
Name Alias Example Description
distance dist dist+:[47,-122] sort by distance, coordinates must be added to the sort value
cachename name name+ sort by the geocache name alphabetically
favorites fav fav- sort by the amount of favorite points on the geocache
geotour gt gt+ sort by the order specified on the GeoTour

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, 429, 500
Restrictions: Basic members restriction applies. See Membership Restrictions section for more info.


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


Adventure Methods

Get Adventure

This method will fetch a specified adventure and its stages using the guid.

Path: /v1/adventures/{adventureGuid}
HTTP Method: GET
Response Type: AdventureStages
Response Codes: 200, 400, 401, 403, 404, 429, 500
Restrictions: Only available to premium members. Private adventures will not be returned. Only the first stage of a sequential adventure will be shown, all stages will be shown for non-sequential. Users must complete stages in the Adventure Lab app.


Parameters
Argument Type Example Required Description Default
adventureGuid path 12345678-ABCD-1234-EFGH-123456HIJKLM Yes the identifier of the adventure -

Get Adventure Start Location

This method will fetch the start location of a specified adventure along with ratings information and count of stages.

Path: /v1/adventures/anon/{adventureGuid}
HTTP Method: GET
Response Type: AdventureStart
Response Codes: 200, 400, 401, 403, 404, 429, 500
Restrictions: Private adventures will not be returned. Users must complete stages in the Adventure Lab app.


Parameters
Argument Type Example Required Description Default
adventureGuid path 12345678-ABCD-1234-EFGH-123456HIJKLM Yes the identifier of the adventure -

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).
isLocked boolean If the geocache is locked and unable to be logged.
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.
owner User Information about the owner of the geocache. No No
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. Tip: It is recommended to always treat user inputted values as potentially containing HTML.
premiumFavoriteScore integer Percentage score for favorite points per premium member finds. Tip: This score is calculated in realtime so fetching this field in bulk calls may cause an adverse affect on performance.
additionalWaypoints array of AdditionalWaypoints Other reference waypoints associated with the geocache.
findCount integer Number of Found It logs on the geocache.
hasSolutionChecker bool Flag for if the native solution checker is used on the website

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,
    "ignored": false,
    "watched": false
  },
  "status": "Active",
  "isLocked": false,
  "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?",
  "premiumFavoriteScore": 41,
  "additionalWaypoints": [],
  "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,
  "hasSolutionChecker": false,
  "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"
  }
}

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)
isLocked boolean if the geocache is locked and unable to be logged
location Location country and state information about the geocache
postedCoordinates Coordinates latitude and longitude of the geocache
attributes array of Attributes. Attributes 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
hasSolutionChecker bool flag for if the native solution checker is used on the website
premiumFavoriteScore integer Percentage score for favorite points per premium member finds
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,
    "ignored": false,
    "watched": false
  },
  "status": "Active",
  "isLocked": false,
  "location": {
    "country": "United States",
    "countryId": 2,
    "state": "Washington",
    "stateId": 48
  },
  "postedCoordinates": {
    "latitude": 47.648967,
    "longitude": -122.348117
  },
  "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
    }
  ],
  "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,
  "hasSolutionChecker": false,
  "premiumFavoriteScore": 41,
  "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
geocacheType Type type 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
upvoteTypeCounts array of UpvoteTypeCount geocache log upvote counts and calling user upvote data 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",
  "geocacheType": {
    "id": 3773,
    "name": "Geocaching HQ",
    "imageUrl": "https://www.geocaching.com/images/wpttypes/3773.gif"
  },
  "ianaTimezoneId": "America/Los_Angeles",
  "usedFavoritePoint": false,
  "url": "https://coord.info/GL5WEa9",
  "upvoteTypeCounts": [
    {
      "upvoteTypeId": 1,
      "upvoteTypeName": "GreatStory",
      "count": 0,
      "upvotedByUser": false
    },
    {
      "upvoteTypeId": 2,
      "upvoteTypeName": "Helpful",
      "count": 0,
      "upvotedByUser": false
    }
  ],
  "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 gallery images on the trackable (owner images plus trackable log images)
goal string the owner's goal for the trackable
description string text about the trackable
releasedDate date when the trackable was activated
originCountry (deprecated, use originLocation instead) string where the trackable originated from
originLocation Location 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
kilometersTraveled decimal distance the trackable has traveled in kilometers
milesTraveled decimal distance the trackable has traveled in miles
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
lastDiscoveredDate nullable datetime the most recent discovered log date for the calling user or null if it has never been discovered

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/avatar/0640f488-9abe-4c2a-a786-bb75cec84357.gif",
    ...
  },
  "holderCode": null,
  "holder": null,
  "inHolderCollection": false,
  "isMissing": true,
  "milesTraveled": 0,
  "kilometersTraveled: 0",
  "trackableType": {
    "id": 21,
    "name": "Travel Bug Dog Tag",
    "imageUrl": "21.gif"
  },
  "trackingNumber": null,
  "lastDiscoveredDate": "2001-09-01T00:00:00",
  "url": "https://coord.info/TB1"
}

Journey

Fields
Name Type Description
trackableLogCode string uniquely identifies the trackable log
geocacheCode string uniquely identifies the geocache
trackableLogType Type type of the trackable log (see Trackable Log Types for more info)
loggedDate datetime The date when the journey was logged on the trackable
coordinates Coordinates latitude and longitude of the trackable log

Example

{
  "trackableLogCode": "TL12345",
  "geocacheCode": "GC12345",
  "trackableLogType":{
    "id": 14,
    "name": "Dropped Off",
    "imageUrl": "https://www.geocaching.com/images/logtypes/14.png"
  }
  "loggedDate": "2001-09-28T00:00:00",
  "coordinates": {
    "latitude": 47.648967,
    "longitude": -122.348117
  }
}

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

Example

{
    "referenceCode": "GCK25B",
    "listItemName": "GCHQ!",
    "listItemDescription" "First stop on Seattle trip.",
    "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
trackableFindCount integer how many trackable finds the user has
trackableOwnedCount integer how many trackable the user owns
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)
joinedDateUtc nullable datetime datetime indicating when the user account was created
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
profileText string text from Profile Information section on user profile page. This may return null if the user privacy setting (ShowAboutInfo) is not set to public. Tip: This user generated field can be very large so fetching in bulk calls may cause an adverse affect on performance.
homeCoordinates Coordinates latitude and longitude of the user's home location
isFriend boolean if the user is a friend of the calling user
souvenirCount integer total number of awarded souvenirs
awardedFavoritePoints integer total number of favorites points from owned geocaches
optedInFriendSharing boolean if the user has opted to to share geocaching activity with friends
geocacheFindCounts Array of GeocacheCount Find counts per geocache type for user. Tip: Find counts are calculated in realtime so fetching this field in bulk calls may cause an adverse affect on performance.
geocacheHideCounts Array of GeocacheCount Hide counts per geocache type for user. Tip: Find counts are calculated in realtime so fetching this field in bulk calls may cause an adverse affect on performance.
trackableFindCounts Array of TrackableCount Find counts per trackable type for user. Tip: Find counts are calculated in realtime so fetching this field in bulk calls may cause an adverse affect on performance.
trackableOwnedCounts Array of TrackableCount Owned counts per trackable type for user. Tip: Find counts are calculated in realtime so fetching this field in bulk calls may cause an adverse affect on performance.
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,
  "trackableFindCount": 24,
  "trackableOwnedCount": 20,
  "favoritePoints": 18,
  "username": "MNofMind",
  "membershipLevelId": 3,
  "joinedDateUtc": "2008-05-27 11:39:56.880",
  "avatarUrl": "https://img-stage.geocaching.com/gcstage/{0}/0640f488-9abe-4c2a-a786-bb75cec84357.gif",
  "homeCoordinates": {
    "latitude": 47.6760654544942,
    "longitude": -122.318150997162
  },
  "isFriend": false,
  "optedInFriendSharing": true,
  "souvenirCount": 42,
  "awardedFavoritePoints", 0,
  "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
  }
}

GeoTour

Fields
Name Type Description
referenceCode string uniquely identifies the GeoTour
name string display name of the GeoTour
description string information about the GeoTour
postedCoordinates Coordinates latitude and longitude of the GeoTour
geocacheCount integer how many geocaches are part of the GeoTour
url string geocaching.com web page associated with the GeoTour
coverImageUrl string image url of the cover of the GeoTour
logoImageUrl string image url of the logo of the GeoTour
favoritePoints integer number of favorite points awarded to geocaches on the GeoTour
sponsor Sponsor the sponsor organizing the GeoTour

Example

{
  "referenceCode": "GT29",
  "name": "HQ",
  "description": "Enjoy \"The Geocacher's Guide to the Center of Our Universe.\" Created for the Block Party by Geocaching HQ employees, this GeoTour takes you to our favorite spots in Seattle's Fremont neighborhood. The caches are within walking distance and are available year-round. Print a passport to keep track of progress.",
  "postedCoordinates": {
    "latitude": 47.64948,
    "longitude": -122.34775
  },
  "geocacheCount": 9,
  "url": "https://www.geocaching.com/play/geotours/HQ",
  "coverImageUrl": "https://img.geocaching.com/geotours/cover/7d29be9a-1df4-495d-b98e-346388c4389a.png",
  "logoImageUrl": "https://img.geocaching.com/geotours/logo/0f28454a-e295-41e9-863d-6fda3febf43a.png",
  "favoritePoints": 13096,
  "sponsor": {
    "name": "Geocaching HQ",
    "relatedWebPage": "http://www.geocaching.com/travel/",
    "relatedWebPageText": "Make your own GeoTour"
  }
}

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
id integer unique id of the souvenir
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
name string name of the image
description string text about the image
ownerCode string identifier of the image owner
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
capturedDate DateTime date image was taken

Example

{
    "description": "Great Scenery",
    "ownerCode": "PR12345",
    "url": "https://someurl/photo",
    "thumbnailUrl": "https://someurl/avatar/photo",
    "largeUrl": "https://someurl/large/photo",
    "referenceCode": "GLXXX",
    "capturedDate": 2021-05-21T07:00:00
}

ImageToUpload

Fields
Name Type Description
name string name of the image
description string text about the image
base64ImageData string image data
guid Guid optional unique identifier to prevent duplicate uploads
capturedDate DateTime date image was taken

Example

{
    "base64ImageData": "base64 data string here",
    "description": "Great Scenery",
    "capturedDate": 2021-05-26T07:00:00
}

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
ignored bool if the user has added this geocache to their ignore list
watched bool if the user has added this geocache to their watch list
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,
    "ignored": false,
    "watched": false,
    "note": "personal cache note here"
}

GeocacheLogUpvoteData

Fields
Name Type Description
geocacheLogCode string identifier of the geocache log
upvoteTypeCounts array of UpvoteTypeCount geocache log upvote counts broken down by type

Example

{
    "geocacheLogCode": "GLFNH417",
    "upvoteTypeCounts": [
      {
        "upvoteTypeId": 1,
        "upvoteTypeName": "GreatStory",
        "count": 0,
        "upvotedByUser": false
      },
      {
        "upvoteTypeId": 2,
        "upvoteTypeName": "Helpful",
        "count": 0,
        "upvotedByUser": false
      }
    ]
  }

UpvoteTypeCount

Fields
Name Type Description
upvoteTypeId integer identifier of the geocache log upvote type
upvoteTypeName string name of the geocache log upvote type
count integer number of upvotes on the geocache log
upvotedByUser boolean if the calling user has added the upvote of this type to the geocache log

Example

{
    "upvoteTypeId": 1,
    "upvoteTypeName": "GreatStory",
    "count": 10,
    "upvotedByUser": false
}

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"
}

Adventure

Fields
Name Type Description
id guid Identifier of the adventure.
keyImageUrl string An image URL that captures the theme of the Adventure.
title string The display name of the adventure.
location coordinates Latitude and longitude of the adventure.
ratingsAverage decimal Average of adventure ratings.
ratingsTotalCount integer Number of adventure ratings.
stagesTotalCount integer Number of stages in adventure.
dynamicLink string External link to Adventure on the official app/website.
isOwned bool If the Adventure is owned by the requesting user.
isCompleted bool If the Adventure is completed by the requesting user.
adventureType string Adventure type (Sequential/Nonsequential)

Example

{
    "id": "6930bdb4-10b7-4210-9e09-f96f26e8842b",
    "keyImageUrl" : "https://img.geocaching.com/12345.jpg",
    "title": "Test adventure",
    "location": {
        "latitude": 47.6062166666667,
        "longitude": -122.332066666667
    },
    "ratingsAverage": 5.0,
    "ratingsTotalCount": 10,
    "stagesTotalCount": 5,
    "dynamicLink": "https://adventurelab.page.link/testlink",
    "isOwned": false,
    "isCompleted": false
}

Adventure Stages

Fields
Name Type Description
id string the guid of the adventure
firebaseDynamicLink string the firebase dynamic link for the adventure
stages array of stages array of adventure stages (only first is returned if adventure is non-sequential)

Example

{
    "id": "12345678-ABCD-1234-EFGH-123456HIJKLM",
    "firebaseDynamicLink": "https://adventurelab.page.link/ABCD",
    "stages": [
        {
        "id": "87654321-DCBA-4321-HGFE-654321MLKJIH",
        "title": "Dropped Off",
        "stageImageUrl": "https://gsmediadata.blob.core.windows.net/mediacontainer/73847284-shif-4dfc-7dh3-193hd74kamn2",
        "isComplete": false,
        "description": "This is the stage description",
        "location": {
            "latitude": 45.1234,
            "longitude": 122.6789
            }
        }
    ]
}

Adventure Start

Fields
Name Type Description
id string the guid of the adventure
title string the adventure's title
location coordinates coordinates of the adventure's start location
ratingsAverage decimal Average of adventure ratings.
ratingsTotalCount integer Number of adventure ratings.
stagesTotalCount integer Number of stages in adventure.

Example

{
    "id": "12345678-9123-4567-8912-3456789123456",
    "title": "Curry Plaza",
    "location": {
        "latitude": 47.6489666666667,
        "longitude": -122.348116666667
    },
    "ratingsAverage": 2,
    "ratingsTotalCount": 1,
    "stagesTotalCount": 2
}

Stage Search Model

Fields
Name Type Description
Take int Number of hits to take, return.
RadiusInMeters double? Search radius in meters.
Origin GeoLocation The origin location to search.
ExcludedAdventures string[] A list of adventure guids to exclude child stages from the results.
ExcludeOwned boolean true to exclude results that are owned by the requesting user; otherwise, false.
ExcludeCompleted boolean true to exclude results that are completed by the requesting user; otherwise, false.
ExcludeUnplayable boolean true to exclude sequential stages that are unplayable by the requesting user; otherwise, false.
AdventureTypes string[] A list of adventure types to filter by when searching. If null, all adventure types will be returned.

Example

{
    "take": 10,
    "radiusInMeters": 20,
    "origin": {
        "latitude": 45.1234,
        "longitude": 122.6789
    },
    "excludedAdventures": [ "12345678-ABCD-1234-EFGH-123456HIJKLM" ],
    "excludeOwned": false,
    "excludeCompleted": false,
    "excludeUnPlayable": false,
    "adventureTypes": [ "sequential" ]
}

Stage Search Response

Fields
Name Type Description
StageGuid guid The guid of the stage.
Location GeoLocation The location of the stage.
Title string The title of the stage.
KeyImageUrl string The Url to the stage's key image.
IsComplete boolean Whether the calling user has completed the stage or not.
Adventure StageAdventure StageAdventure The adventure the stage belongs to.

Example

{
    "stageGuid": "12345678-ABCD-1234-EFGH-123456HIJKLM",
    "location": {
        "latitude": 45.1234,
        "longitude": 122.6789
        }
    },
    "title": "Dropped Off",
    "keyImageUrl": "https://gsmediadata.blob.core.windows.net/mediacontainer/73847284-shif-4dfc-7dh3-193hd74kamn2",
    "isComplete": false,
    "adventure": {
        "id": "12345678-ABCD-1234-EFGH-123456HIJKLM",
        "adventureType": "sequential"
    }
}

Stage Adventure

Fields
Name Type Description
Id guid The Guid identifier of the stage's adventure.
AdventureType string Adventure type (Sequential/Nonsequential)

Example

{
    "id": "12345678-ABCD-1234-EFGH-123456HIJKLM",
    "adventureType": "sequential"
}

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 Community Celebration Event
3773 Geocaching HQ
3774 Geocaching HQ Celebration
4738 Geocaching HQ 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 Didn't find 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
6 Permanently Archived changing the status of the geocache to archived (deprecated)
7 Needs Archived 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 (reviewer only)
18 Post Reviewer Note (deprecated) adding a reviewer comment to the geocache
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 (reviewer only)
24 Publish Listing changing the status of the geocache from unpublished to active (reviewer only)
25 Retract Listing retracting the geocache (admin only)
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 (reviewer only)
74 Announcement event host announcement to attendees
76 Submit for Review submitting a geocache to be published

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

Additional Waypoint Visibility Types

Id Name
0 Visible
1 Hide Coordinates
2 Hidden

Geocache Log Upvote Types

Id Name
1 GreatStory
2 Helpful

Geocache Log Sorts

Name Description
newest Descending sort on logs by creation
greatstory Descending sort on logs by log upvote counts of log upvote type id 1
helpful Descending sort on logs by log upvote counts of log upvote type id 2

User Privacy Settings

Setting Name Possible Values
ShowJoinDate int (1 = private, 2 = friends, 3 = public)
ShowLastVisitedDate int (1 = private, 2 = friends, 3 = public)
ShowHomeLocation int (1 = private, 2 = friends, 3 = public)
ShowAboutInfo int (1 = private, 2 = friends, 3 = public)
ShowGeocachesFound int (1 = private, 2 = friends, 3 = public)
ShowTrackables int (1 = private, 2 = friends, 3 = public)
ShowSouvenirs int (1 = private, 2 = friends, 3 = public)
ShowGallery int (1 = private, 2 = friends, 3 = public)
ShowStatistics int (1 = private, 2 = friends, 3 = public)

Change Log

06.24.2024

04.01.2024

11.06.2023

03.07.2022

02.02.2022

11.01.2022

05.24.2021

10.15.2020

09.28.2020

06.22.2020

04.06.2020

01.02.2020

09.02.2019

08.05.2019

06.24.2019

04.15.2019

03.11.2019

11.26.2018

10.08.2018

08.27.2018

07.23.2018

06.18.2018

06.06.2018