Retrieve data on a single attribute :: services/attrs/attribute method
|
https://www.opencaching.de/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.
|
|