Retrieve information on a single geocache

:: services/caches/geocache method

Default value: en

Pipe-separated list of ISO 639-1 language codes. This indicates the order of preference in which language will be chosen for fields like name and description.

Please note, that you may also access caches descriptions in all available languages. If you want to do this, you should use fields names, descriptions (etc.) instead of name and description (etc.).

Default value: code|name|location|type|status

Pipe-separated list of field names which you are interested with. Selected fields will be included in the response.

Currently available fields:

• code - unique code of the geocache,
• name - name of the geocache,
• names - a dictionary (language code => plain-text string) of names of the geocache (at this time, there will be only one language,) but this may change in future),
• location - location of the cache in the "lat|lon" format (lat and lon are in full degrees with a dot as a decimal point),

• type - cache type. This might be pretty much everything, but there are some predefined types that you might want to treat in a special way (separate icons etc.). Primary types include:

  • Traditional,
  • Multi,
  • Quiz,
  • Virtual.
  • (any other value is valid too)

• status - cache status. Valid cache status codes currently include:

  • Available - Cache is available and ready for search,
  • Temporarily unavailable - Cache is probably unavailable (i.e. in need of maintenance)
  • Archived - Cache is permanently unavailable (moved to the archives).
• url - URL of the cache's web page,

• owner - dictionary of:

  • uuid - geocache owner's user ID,
  • username - name of the user,
  • profile_url - URL of the user profile page,

• distance - float, the distance to a cache, in meters. This requires my_location parameter to be provided.

  Please note, that sometimes it is faster to compute this yourself, on client-side, instead of quering OKAPI.

• bearing - float, the absolute bearing to the cache, measured in degrees from north, or null if it cannot be calculated (i.e. when you are exactly at the target's location). This requires my_location parameter to be provided.

  Please note, that sometimes it is faster to compute this yourself, on client-side, instead of quering OKAPI.

• bearing2 - string, the absolute bearing to the cache, represented as a typical direction string of length of 1 or 2 characters (ex. "N", "NE", "E", "SE", etc.), or "n/a" if it cannot be calculated. This requires my_location parameter to be provided.

  Please note, that sometimes it is faster to compute this yourself, on client-side, instead of quering OKAPI.

• bearing3 - string, the absolute bearing to the cache, represented as a typical directon string of length of 1 or 2 or 3 characters (ex. "N", "NNE", "NE", "ENE", etc.), or "n/a" if it cannot be calculated. This requires my_location parameter to be provided.

  Please note, that sometimes it is faster to compute this yourself, on client-side, instead of quering OKAPI.

• is_found - boolean, true if user already found this cache.

  This field requires you to use the user_uuid parameter (or Level 3 Authentication).

• founds - number of times the geocache was successfully found,
• notfounds - number of times the geocache was not found,
• size - float (between 1 and 5), size rating of the container, or null if geocache does not have a container,
• difficulty - float (between 1 and 5), difficulty rating of the cache,
• terrain - float (between 1 and 5), terrain rating of the cache,

• rating - float (between 1 and 5), an overall rating of the cache, or null when the geocache does not have a sufficient amount of votes to have a rating.

  Please note: some OC installations do not use the rating/voting system. The rating will always be null on such installations.

• rating_votes - number of votes submitted for the rating of this cache.

  Please note: some OC installations do not use the rating/voting system. The rating_votes will always be 0 on such installations.

• recommendations - number of recommendations for this cache,
• req_passwd - boolean; states if this cache requires a password in order to submit a "Found it" log entry,
• description - HTML string, description of the cache,
• descriptions - a dictionary (language code => HTML string) of cache descriptions,
• hint - plain-text string, cache hints/spoilers; in general, hints should not be displayed to the user unless user specifically asks for them,
• hints - a dictionary (language code => plain-text string) of cache hints/spoilers,

• images - list of dictionaries, each dictionary represents one image saved along the cache description; each dictionary has the following structure:

  • uuid - UUID of the image,
  • url - an URL of the image,
  • thumb_url - an URL of a small (thumb) version of the image or null when no thumb is available (e.g. there are no thumbs for spoiler images),
  • caption - plain-text string, caption of the image,
  • unique_caption - plain-text string, to be used as a filename for Garmin's crappy images implementation (currently, they get image caption from the image's filename itself),
  • is_spoiler - boolean, if true then the image is a spoiler image and should not be displayed to the user unless the user explicitly asks for it.

• attrnames - list of names of attributes of the cache; the language will be selected based on the langpref argument.

  Note: currently each of the OC installations has its own set of attributes. That's why we don't reference them by their IDs - we only return them as text. This could change *if* OC installations would begin to use UUIDs for their attributes and synchronize them between all installations.

• latest_logs - a couple of latest log entries in the cache. The format is the same as the one returned by the services/logs/logs method.

  Notice: The number of logs returned can be set with the lpc option.

• my_notes - user's notes on the cache, in plain-text, or null if user hadn't defined any notes.

  This field requires you to use the Level 3 Authentication.

• trackables_count - a total number of trackables hidden within the cache.

• trackables - list of dictionaries, each dictionary represents one trackable hidden within the cache container; each dictionary has the following structure:

  • code - code of the trackable,
  • name - plain text name of the trackable,
  • url - trackable's own webpage address or null, if OKAPI cannot automatically determine this address.

• alt_wpts - list of alternate/additional waypoints associated with this geocache. Each item is a dictionary of the following structure:

  • name - plain-text short name for the waypoint,
  • location - location of the waypoint in the "lat|lon" format (lat and lon are in full degrees with a dot as a decimal point),
  • sym - string, one of globally-recognized waypoint symbol names (such as "Flag, Green" or "Parking Area"),
  • description - plain-text longer description of the waypoint.
• last_found - date and time (ISO 8601) when the geocache was last found or null when it hasn't been yet found,
• last_modified - date and time (ISO 8601) when the geocache was last modified (changed status, attributes, etc.),
• date_created - date and time (ISO 8601) when the geocache was initially created,
• date_hidden - date and time (ISO 8601) when the geocache was first hidden,
• internal_id - internal ID of the cache (do not use this, unless you know what you're doing; use the "code" as an identifier).

Default value: 10

The reference point for cache distance and bearing calculation (typically - the user's location), in the "lat|lon" format. This parameter is required when accessing distance and/or bearing fields.

Use positive numbers for latitudes in the northern hemisphere and longitudes in the eastern hemisphere (and negative for southern and western hemispheres accordingly). These are full degrees with a dot as a decimal point (ex. "54.3|22.3").

User'd ID. Required to access fields like is_found using Level 1 Authentication.

Please note that if you want to access private fields (like my_notes), then this parameter won't help you. You have to use Level 3 Authentication instead.

If you use Level 3 Authentication, you shouldn't use this parameter. Or, to be exact:

• user_uuid will be extracted from the Access Token you use. You don't have to provide it.
• If you provide user_uuid, then it HAS TO match your Access Token. If it doesn't, OKAPI will respond with HTTP 400 error.