Retrieve information on a single geocache

:: services/caches/geocache method

Returned value:

A dictionary of fields you have selected. Currently available fields:

• code - unique Opencaching 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, one of the type codes that are included in the types field of services/caches/capabilities. Currently there are eight types which are in use at all OKAPI installations:

  • Traditional,
  • Multi,
  • Quiz, also known as "Mystery",
  • Moving, a geocache with changing coordinates,
  • Virtual,
  • Webcam,
  • Other, also dubbed "unknown type"; allows OC users to create special caches which don't fit into the scheme of well-known types,
  • Event, a peculiar type of geocache which is NOT a geocache at all, but it is stored as a geocache in OC database. Just keep in mind, that in case of Event Caches, some fields may have a little different meaning than you would tell by their name.
  • (Types may be added or removed. Your application MUST be prepared for any new types and may handle them as "Other".)

  More types are in use at some installations:

  • Own, a moving geocache which is carried by the owner,
  • Podcast, a geocache with attached MP3 file(s). The MP3 data is not accessible via OKAPI. This type is only in use at Opencaching.US.
  • (Types may be added or removed. Your application MUST be prepared for any new types and may handle them as "Other".)

  There are even more types, but OKAPI maps them to common types (and eventually some attributes), so you won't see them in OKAPI data.

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

  • Available - Cache is available and ready for search,
  • Temporarily unavailable - Cache is unavailable (probably cannot be found) but may be restored,
  • Archived - Cache is permanently unavailable (moved to the archives).

• OCDE needs_maintenance - boolean, true if the geocache is known to be in poor condition, e.g. damaged. Usually there will be further explanations in the log entries.

  Please note that some Opencaching installations don't provide this information; they will always return false.

• url - URL of the cache's web page,

• owner - dictionary of user fields that are selected by the owner_fields option.

• gc_code - Geocaching.com code (GC code) of the geocache or null if the cache is not listed on GC or the GC code is unknown.

  Please note that this information is supplied by cache owners and it is often missing, obsolete or otherwise incorrect.

• 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 querying 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 querying 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 querying OKAPI.

• bearing3 - string, the absolute bearing to the cache, represented as a typical direction 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 querying OKAPI.

• is_found - boolean, true if the user already found this cache. See also found_status parameter of the services/caches/search/all method.

  This field requires you to use the user_uuid parameter (or Level 3 Authentication). Please note, that this will also return true for attended Event Caches.

• is_not_found - boolean, true if the user has submitted "Didn't find it" log entry for this cache.

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

• is_watched - boolean, true if the user is watching this cache. You may consider highlighting such geocaches in some fashion, as the users may use this functionality to temporarily mark geocaches of particular interest (i.e. geocaches they plan to find today).

  This is private data. You will need Level 3 Authentication to access this field.

• is_ignored - boolean, true if the user is ignoring this cache. (See also exclude_ignored parameter of all search methods.)

  This is private data. You will need Level 3 Authentication to access this field.

• founds - number of times the geocache was successfully found (or attended, in case of Event Caches),

• notfounds - number of times the geocache was not found (in case of Event Caches this will always be zero),

• willattends - in case of Event Caches, this is the number of "Will attend" log entries. In case of any other cache type, it will be zero (not null, for backward compatibility),

• watchers - number of users who are watching this cache.

  Note that many watchers are inactive users, especially at the old sites Opencaching.DE and Opencaching.PL (founded 2005/2006). Some of them won't receive watch notifications at all because of obsolete email addresses. So the watchers' counts are somewhat overstated.

• size - deprecated (why?), use size2 instead. Float (between 1 and 5), size rating of the container, or null if geocache does not have a container,

• size2 - string indicating the size of the container, so called "size2 code". One of the following values: 'none', 'nano', 'micro', 'small', 'regular', 'large', 'xlarge', 'other'.

• oxsize - float (between 1 and 5) or null, this is a size rating variant, compatible with the one used by (former) OpenCaching.com site (and many Garmin GPS devices).

  Note: The mapping is undocumented and may change without notice.

  Note: Some of OC's size values cannot be properly mapped to oxsize, i.e. the 'other' size.

• difficulty - float (between 1 and 5), difficulty rating of the cache,
• terrain - float (between 1 and 5), terrain rating of the cache,

• trip_time - float, approximate total amount of time needed to find the cache, in hours; this will usually include the time to reach the cache location and go back (from/to a parking spot, etc.); null if unknown,

• trip_distance - float, approximate total distance needed to find the cache, in kilometers; this will usually include the time to reach the cache location and go back (from/to a parking spot, etc.); null if unknown,

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

  Note: Some installations don't provide ratings for their geocaches; they will always return null for this field. The has_ratings field of services/caches/capabilities tells if ratings are available.

  Note: Currently OC sites expose cache ratings as integers only. OKAPI used floats here for forward-compatibility only. In other words, currently you can get 4.0 or 5.0 here, but not 4.5. This may change in the future though, without notice.

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

  Note: Some installations don't provide ratings for their geocaches; they will always return 0 for this field. The has_ratings field of services/caches/capabilities tells if ratings are available.

• OCPL my_rating - float (between 1 and 5), the rating the user gave for this cache; null if the user did not rate.

  This is private data. You will need Level 3 Authentication to access this field.

  See the notes on the rating field.

• recommendations - number of recommendations for this cache,

• is_recommended - boolean, true if the user recommended this cache.

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

• req_passwd - boolean; states if this cache requires a password in order to submit a "Found it" log entry,
• short_description - a plaintext string with a single line (very short) description of the cache (kind of a "tagline text"),
• short_descriptions - a dictionary (language code => plaintext string) of short cache descriptions,
• description - HTML string, description of the cache; may include additional notices that are prepended or appended to the text, some of them depending on the oc_team_annotation and attribution_append options,
• descriptions - a dictionary (language code => HTML string) of cache descriptions,
• hint - HTML-encoded string, cache hints/spoilers; deprecated (why?), use hint2 instead,
• hints - a dictionary (language code => HTML-encoded string) of cache hints/spoilers; deprecated, use hints2 instead,
• hint2 - plain-text string, cache hints/spoilers; in general, hints should not be displayed to the user unless user specifically asks for them,
• hints2 - 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 - URL of the image,
  • thumb_url - URL of a small (thumb) version of the image,
  • 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,

• OCDE preview_image - On some installations, owners may select one of the images (see above) as a preview image. You are encouraged to display it as a 'teaser' for this cache. On other installations this functionality is disabled and you will always get the null value here.

  The value of preview_image is either null or a dictionary describing an image. The structure of this dictionary is the same as of a single entry on the images list described above.

• attr_acodes - unordered list of OKAPI geocache-attribute IDs (A-codes) with which the cache was tagged. Use the attrs module to retrieve information on these attributes.

• attrnames - if you don't want to dig into attr_acodes just now, then you can use these as a simple alternative. attrnames is an unordered list of names of the attributes with which the cache was tagged; the language will be selected based on the langpref parameter.

• OCPL oc_team_annotation - HTML text containing OC team annotations to the geocache listing. See the oc_team_annotation parameter for more information.

  Notices: The content of this field is not properly localized. It will only partially respond to the langpref parameter and may contain an arbitrary mixture of languages and differently localized data (why?). Some installations don't implement OC team annotations; they currently always return an empty string for this field.

• attribution_note - the proper attribution note for the cache listing according to the local OC site's Data License. By default, this note is also appended to geocache descriptions (see the attribution_append parameter).

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

  Note: The number of logs returned can be set with the lpc option, and the fields to return can be selected by the log_fields 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, unique "codename" 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).

    Note: For waypoints with nonpublic location, "0|0" is returned. It is recommended to hide those null coordinates or show a placeholder like "---". Public waypoints coordinates are never "0|0".

  • type - string, unique identifier for the type of waypoint; one of the following:

    • parking, trailhead, path, stage, physical-stage, virtual-stage, final, poi, other - used by OC itself, for detailed descriptions of these you'll have to refer to external Opencaching documenation,
    • user-coords - extra coordinates supplied by the user who had found the cache (NOT the owner of the cache), most probably pointing to the final location of the cache (e.g. a quiz cache); this type of waypoint is available only in some installations and only if you're using Level 3 Authentication,
    • more types may be added at any moment; unknown types should be treated as other.
  • type_name - string, the human-readable name of the waypoint type, e.g. "Parking area" or "Final location"; the language will be selected based on the langpref argument,

  • gc_type - string, identifier for the type of waypoint as used in Groundspeak applications. Different types may be mapped to the same gc_type, and mappings may change. Use type instead if you need a unique and forward compatible identifier.

  • sym - string, one of commonly recognized waypoint symbol names, originally introduced by Garmin in their devices and GPX files (e.g. "Flag, Green" or "Parking Area").

    These symbol codes are only suggestions. They are understood by Garmin-related software and devices. If you don't know how to display such symbols, you are welcome to use any symbol you'd like in your application.

  • description - plain-text longer description of the waypoint.

• country - deprecated; same as country2, but on some installations the language of the returned country name is undefined (it will not respond to the langpref parameter). Also, null may be returned instead of an empty string if the country is unknown.

• country2 - name of the country the cache is placed in; may be empty ("") if the country is unknown.

  Note: This data is user-supplied and is not validated in any way. Consider using external geocoding services instead.

• state - deprecated; same as region, but null may be returned instead of an empty string if the region is unknown. For some caches, the returned region will not match the country where the cache is placed.

• region - name of the major subnational entity the cache is placed in; may be empty ("") if the entity is unknown. This may be a (federal) state, a province, a region or whatever is the country's most relevant administrative entity below national level.

  Note: On some installations this data is user-supplied and is not validated in any way. Other installations calculate it from cache coordinates but may have problems in border regions. Different OC sites may return different regions for the same geocache. Consider using external geocoding services instead. Also, currently you have no way of knowing in which language it will appear in (but it *may* start to vary on the value of your langpref parameter in the future).

• protection_areas - list of dictionaries, each representing a protection area in which the cache probably is located; each dictionary has the following structure:

  • type - the type of the protection area, e.g. "National Nature Reserve",
  • name - the name of the protection area, e.g. "East Dartmoor Woods and Heaths".

  The types and names currently are in a local language of the OC site but may be translated depending on the langpref parameter in the future.

  Note that this information is not authoritative. It may be outdated or incomplete, and it is completely missing on some OC installations.

• last_found - date and time (ISO 8601) when the geocache was last found or null when it hasn't been yet found.

  Note, that some Opencaching servers don't store the exact times along with the log entries.

• 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 listed at the Opencaching site. For OCDE-based installations this is the date when it was published, while for OCPL installations it is the date when it was originally submitted. These dates differ if the geocache is prepared and then published later.

• date_hidden - date and time (ISO 8601) when:

  • the geocache was first hidden (for physical caches), or
  • the geocache was first published (for virtual caches), or
  • the event takes place (for event caches),
• internal_id - internal ID of the cache (do not use this, unless you know what you're doing; use the "code" as an identifier).

For example, for geocache?cache_code=OP3D96&fields=type query, the result might look something link this:

{"type": "Traditional"}

If given cache code does not exist, the method will respond with an HTTP 400 error.