ver. 1926 (dbed1d0) 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 geocaches in GPX format
|
|
||||
https://www.opencaching.de/okapi/services/caches/formatters/gpx | ||||
Produces a standards-compliant Geocaching GPX file. Unlike the services/caches/geocaches method responses, GPX files cannot contain names and descriptions in separate multiple languages. This method will attempt to choose the best language based on your preference (see langpref argument). Remember that a full-blown GPX file is much larger than a basic one. This method can produce many various types of GPX files. The simplest list of waypoints takes ~50 times less space than the same list with cache descriptions and log entries included. Note, that GPX files may contain unvalidated HTML. |
||||
cache_codes | required |
Pipe-separated list of cache codes which you are interested in. No more than 500 codes are allowed. This CAN be an empty string (it will result in an empty, but valid, GPX file). All invalid cache codes will be skipped without any notice! |
||
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 GPX entities. |
||
ns_ground | optional |
Default value: false Boolean. If true then the response will include Groundspeak's GPX extension. This namespace declares an extra <cache> element used by geocaching.com and many others. This namespace was initially associatied with geocaching.com, but now seems to be used in every geocaching GPX file. You probably want to have it. |
||
ns_oc | optional |
Default value: false Boolean. If true then the response will include the Opencaching GPX extension. The GPX files will contain an additional <oc:cache> element for each geocache, which contains Opencaching-specific information about the geocache. If latest_logs is set to true, then it will also contain Opencaching-specific information about log entries. The Opencaching GPX extension was introduced by OKAPI and is expected to be included in most OC sites' native GPX files. |
||
ns_gsak | optional |
Default value: false Boolean. If true then the response will include GSAK GPX extension. This namespace declares an extra <wptExtension> element, which allows including "waypoint inheritance" information (parent-child relations) via its <Parent> element. This in turn allows us to include "alternate waypoints" in the response. This feature was once supported by GSAK application only, but currently many applications recognize it. As far as we know, it became a "de facto" standard for expressing "alternate waypoints". |
||
ns_ox | optional |
Default value: false Boolean. If true then the response will include Garmin's OpenCaching.com GPX extension. This namespace declares an extra <opencaching> element used by Garmin's (former) OpenCaching.com site. The element includes information on cache difficulty, ratings, tags and images. OpenCaching.com no longer exists, but its XML namespace is still used by many applications (and not only the Garmin ones, e.g. see here). |
||
images | optional |
Default value: descrefs:nonspoilers Which images to include (and how to include them). One of the following values:
Note: When using "descrefs:" mode, remember to set ns_ground to true. The default value is "descrefs:nonspoilers" for compatibilty reasons, but for most applications "descrefs:thumblinks" will be the better choice. Note: When using "ox:" mode, remember to set ns_ox to true. You must also include JPEG files along the GPX for this to work properly - see services/caches/formatters/garmin for more information. In the future, more generic ways of including images in GPX files may emerge. |
||
attrs | optional |
Default value: desc:text This argument controls whether cache attributes are included and how they are included. Pipe-separated list consisting of any set of the following values:
If you don't want any attributes to be included, you must set the attrs parameter to none. Using an empty string won't work this way - it will trigger the default (desc:text) to be selected, for backward-compatibility. |
||
protection_areas | optional |
Default value: desc:auto This argument controls whether protection area information is included and how it is included.
Note that information on protection areas may be incomplete or outdated or completely missing on some installations. |
||
trackables | optional |
Default value: none This argument controls whether information on trackables is included and how it is included. One of the following values:
Note: When using "desc:" or "gc:" mode, remember to set ns_ground to true. |
||
recommendations | optional |
Default value: none This argument controls whether information on recommendations is included and how it is included. One of the following values:
Note: When using "desc:" mode, remember to set ns_ground to true. |
||
my_notes | optional |
Default value: none Allows you to include personal user's notes on each cache. This parameter takes either none (default value), or pipe separeted list of the following values:
Note: You need to use Level 3 Authentication in order to set it to anything else than "none". |
||
latest_logs | optional |
Default value: false This argument controls if log entries are included. There are three options:
You must set ns_ground argument to true if you want to use this. |
||
lpc | optional |
Default value: 10 Log-entries per cache - the number of log entries included in each returned cache. This should be an integer or a special "all" value. Please note, that the ns_ground and latest_logs arguments must be set to true in order for the logs to be included. |
||
alt_wpts | optional |
Default value: false This argument controls if additional (alternate) waypoints are included in the response and how they are included. These are all places associated with the cache.
|
||
mark_found | optional |
Default value: false Boolean. If true then all caches which are already found, will be marked appropriately (i.e. with an "found cache" symbol). This field requires you to use the user_uuid parameter (or Level 3 Authentication). |
||
user_uuid | optional |
User'd ID. Required to mark found caches using Level 1 Authentication. If you use Level 3 Authentication, you shouldn't use this parameter. Or, to be exact:
|
||
location_source | optional |
Default value: default-coords If you supply a value, then it must be prefixed with alt_wpt:, and should match one of alternate waypoint types documented in the alt_wpts field returned by services/caches/geocache method. If the type doesn't match, it will be ignored. By default, the lat and lon attributes of the <wpt> element will return the default coordinates of the cache, as supplied by the owner of the cache. This option allows you to replace these coordinates with other set of coordinates, loaded from the alt_wpts field mentioned above. This may have some advantages in some scenarios. For example, if your user is driving a car, he might be more interested in the coordinates of the nearest suitable parking spot than in the coordinates of the geocache itself. If you set location_source to alt_wpt:parking then you'll be pre-fetching parking locations (if provided) without the need of loading all other alternate waypoints in your requests. Other use case: setting this to alt_wpt:user-coords allows personalized results in some OC installations.
|
||
location_change_prefix | optional |
Default value: # Prefix to be added to the geocache name, in case its location has been changed due to the location_source parameter matching any of the alternate waypoints. |
||
Plus required consumer_key argument, assigned for your application. | ||||
Returned value: GPX file. All invalid cache codes will be skipped without any notice! |