ver. 1958 (4e4db56)
Introduction
Sign up
Examples
Changelog
services/apiref
issue
method
method_index
services/apisrv
installation
installations
stats
services/attrs
attribute
attribute_index
attributes
services/caches
edit
geocache
geocaches
mark
save_personal_notes
services/caches/formatters
garmin
ggz
gpx
services/caches/map
tile
services/caches/search
all
bbox
by_urls
nearest
save
services/caches/shortcuts
search_and_retrieve
services/logs
capabilities
delete
edit
entries
entry
logs
submit
userlogs
services/logs/images
add
delete
edit
services/oauth
access_token
authorize
request_token
services/replicate
changelog
fulldump
info
services/users
by_internal_id
by_internal_ids
by_username
by_usernames
user
users

Retrieve data on a single attribute
:: services/attrs/attribute method

Minimum Authentication: Level 1 (see Authentication Levels)
https://opencache.uk/okapi/services/attrs/attribute

Retrieve data on a single OKAPI geocache-attribute.

OKAPI attributes are identified by an unique ID called an A-code. All OKAPI attributes are shared among all OKAPI servers. Once an attribute is published (e.g. via the attribute_index method), it won't disappear in any of the future OKAPI revisions, nor will its meaning change. Some attributes may get discontinued in the future, but they will remain accessible by their original A-code.
acode required The A-code of the attribute you're interested in.
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.
fields optional

Default value: name

Pipe-separated list of field names which you are interested with. See below for the list of available fields.
forward_compatible optional

Default value: true

By default, OKAPI will return an empty placeholder if you ask for an unknown attribute. If you'd like to catch such errors and handle them differently, then you may change this behavior by setting this parameter to false. Then, OKAPI will return HTTP 400 error response, instead of the placeholder (note that it behaves differently in the attributes method).
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 in the fields parameter. Available fields:

  • acode - string, the A-code. Unique identifier of the attribute.

  • name - plaintext string, name of the attribute (language is selected based on your langpref parameter),

    If you think your language is missing, then feel free to add missing translations directly to OKAPI repository. See here.

  • names - a dictionary of all known names of the attribute, in various languages (ISO 639-1 language code is used as dictionary key).

    If you think your language is missing, then feel free to add missing translations directly to OKAPI repository. See here.

  • description - HTML string, description of the attribute (language is selected based on your langpref parameter),

    If you think your language is missing, then feel free to add missing translations directly to OKAPI repository. See here.

  • descriptions - a dictionary of all known descriptions of the attribute, in various languages (ISO 639-1 language code is used as dictionary key).

    If you think your language is missing, then feel free to add missing translations directly to OKAPI repository. See here.

  • gc_equivs - a list of Geocaching.com (Groundspeak) attributes, which have exactly the same (or a very similar) meaning. Each attribute is described as a dictionary of the following structure:

    • id - ID of the Geocaching.com attribute,
    • inc - integer, either 1 or 0. See Geocaching.com's XSD for details on its meaning,
    • name - the name of the attribute (as it is included in Geocaching.com GPX files).

    Note that one gc_equivs list may have multiple items on it, and that one Geocaching.com ID may be present in many gc_equivs.

  • gc_ocde_equiv - a Groundspeak-like attribute with ID > 100, which may be included in GPX files if there is no gc_equiv for the OC attribute; either null or a dictionary of the following structure:

    • id - Groundspeak-like ID of the attribute,
    • inc - integer, either 1 or 0, to be included in GPX files,
    • name - the name of the attribute to be included in GPX files.

    Note: We cannot guarantee that the ID of these Groundspeak-like attributes will forever stay the same. If you need a unique attribute ID, use the acode instead.

    The naming "ocde_" is for historical reasons. This field is available on all up-to-date OKAPI installations and covers all OC attributes without native GC equivalents. See the caches/formatters/gpx attrs=gc_ocde:attrs option for more explanation.

  • is_locally_used - boolean, indicates if the attribute is currently used by this Opencaching server. Or, to be more specific, true means that the attribute can currently be included in the attr_acodes field of the geocache method in this OKAPI installation.

    Note that this flag can change in time. Some attributes may get introduced into other installations, whereas other attributes may (temporarily or permanently) stop being used. In general, we are aiming towards global unification of all attributes between all OC sites, but this process will take time (and probably it will never be 100% complete).

  • local_icon_url - an URL pointing to an image associated with this particular attribute in the local OC server, or null if the current server does not have any image for this attribute.

    Please note, that each OC server uses a different image set for their attributes. All these images come in various sizes and can change over time. In other words, if you want to use this attribute, then you must always be prepared to receive null, or an image of unexpected dimensions.

  • is_discontinued - boolean, indicates if the attribute is discontinued. This means that it is no longer in use at OC servers which run current OKAPI versions, i.e. geocaches are no longer tagged with this attribute. However, it may still be in use at servers which have not been updated yet to the current OKAPI version.

    Important: This flag can change in time. Discontinued attributes can "come back to life" later. You can never be 100% sure you will not encounter them in OKAPI responses, so this field is purely informative.