ver. 1497 (0b71064)
services/apiref
services/apisrv
services/attrs
services/caches
services/caches/formatters
services/caches/map
services/caches/search
services/caches/shortcuts
services/logs
services/logs/images
services/oauth
services/replicate
services/users

Retrieve information on a single geocache
:: services/caches/geocache method

Minimum Authentication: Level 1 (see Authentication Levels)
https://opencaching.pl/okapi/services/caches/geocache

Retrieve information on a single geocache.

cache_code required Unique code of the geocache
langpref optional

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

fields optional

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. See below for the list of available fields.

attribution_append optional

Default value: full

By default, OKAPI appends the value of attribution_note field to all the cache descriptions. If you would like to display the attribution note separately, you may use this parameter. Use one of the following values:

  • full - OKAPI will append the attribution note to the descriptions of the geocache. The language of the note will match the language of the description (i.e. each value in descriptions may contain attribution notes in a different language).

  • none - OKAPI will not append the attribution note to geocache descriptions. You will need to use the attribution_note instead (which also depends on the langpref parameter).

    Important note: You are still required to display the attribution_note field in some other way.

  • static - OKAPI will append a "static" attribution note to the descriptions of the geocache. This might equal the "full" attribution note, but not necessarilly, since the "full" note may contain a current date (why?), and the "static" note will not. This is implemented primarily for internal use (i.e. the replicate module). Usually you should not use it, because on some installations the static note will not be sufficient to meet the data license requirements.

lpc optional

Default value: 10

Log-entries per cache - the number of logs returned in the latest_logs field. This should be an integer or a special "all" value. Please note, that you must include the latest_logs field in fields in order to see the log entries.
log_fields optional

Default value: uuid|date|user|type|comment

Pipe-separated list of log fields to include in the latest_logs field. For valid field names, see logs/entry method.
my_location optional

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_uuid optional

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.
format optional Standard common formatting argument.
callback optional Standard common formatting argument.
Plus required consumer_key argument, assigned for your application.

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. 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,
    • Event,
    • (any other value is valid too)

    Event is a peculiar type of geocache which is NOT a geocache at all, but it is stored as a geocache in OC database (this design decision is as old as the OC network itself!). 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.

  • 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).
  • 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 only some OC sites provide this information. Other sites will always return false here.

  • 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,
  • 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),

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

    Notice: Only OCPL-based Opencaching installations provide ratings for their geocaches. On OCDE-based installations, this field will always contain null.

    Notice: Currently OCPL exposes 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.

    Notice: Only OCPL-based Opencaching installations provide ratings for their geocaches. On OCDE-based installations, this field will always contain 0.

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

    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, 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),
    • type - string, unique identifier for the type of waypoint; one of the following:

      • parking, 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,
    • 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 - 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. 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).

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

    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. 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 some OC installations this is the date when it was published, while for the other 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.