Retrieve geocaches in GPX format

:: services/caches/formatters/gpx method

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!

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.

Default value: false

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.

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

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

Default value: descrefs:nonspoilers

Which images to include (and how to include them). One of the following values:

• none - no images will be included,
• descrefs:thumblinks - all images will be included as "thumbnail" <img> references at the end of each cache description, with a replacement image used for spoilers; the thumbnails are linked to the large images,
• descrefs:nonspoilers - all non-spoiler images will be included as <img> references at the end of each cache description,
• descrefs:all - all images will be included (including spoilers) as <img> references at the end of each cache description,
• ox:all - all images will be included (including spoilers) as Garmin's <ox:image> references.

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.

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:

• desc:text - attributes will be listed (in plain-text) within the cache description (ns_ground has to be true),
• ox:tags - attributes will be listed as Garmin's ox:tag elements (ns_ox has to be true),

• gc:attrs - attributes will be listed as Groundspeak's groundspeak:attribute elements (ns_ground has to be true), compatible with Geocaching.com (see the list here).

  Note that most Opencaching attributes don't have Geocaching.com counterparts. Such attributes cannot be included as gc:attrs and will be ignored.

• gc_ocde:attrs - attributes will be listed as Groundspeak's groundspeak:attribute elements (ns_ground has to be true). Opencaching attributes which have no Geocaching.com counterparts will be included according to an Opencaching.DE convention, which now is implemented at all up-to-date OC sites: They will have IDs > 100.

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.

Default value: desc:auto

This argument controls whether protection area information is included and how it is included.

• desc:text - if the cache (probably) is located within one or more protection areas, e.g. a nature reserve, a list of the protection areas will be included in the cache description.
• desc:auto - protection area information may be included in the cache description, depending on the installation.
• none - no protection area information will be included in the GPX data.

Note that information on protection areas may be incomplete or outdated or completely missing on some installations.

Default value: none

This argument controls whether information on trackables is included and how it is included. One of the following values:

• none - no trackables-data will be included,
• desc:list - trackables will be listed (in plain-text) within the cache description,
• desc:count - total number of trackables will be included (in plain-text) within the cache description,
• gc:travelbugs - trackables will be included as Groundspeak's groundspeak:travelbug elements.

Note: When using "desc:" or "gc:" mode, remember to set ns_ground to true.

Default value: none

This argument controls whether information on recommendations is included and how it is included. One of the following values:

• none - no recommendations-info will be included,
• desc:count - number of recommendations (and founds) will be included (in plain-text) within the cache description.

Note: When using "desc:" mode, remember to set ns_ground to true.

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:

• desc:text - include personal notes as part of the cache description.

• gc:personal_note - include personal notes as <groundspeak:personal_note> element (under <groundspeak:cache> element).

  Warning: This element is not a part of http://www.groundspeak.com/cache/1/0/1 groundspeak schema, but it is a http://www.groundspeak.com/cache/1/0/2 schema element. Using this option will generate formally invalid XML file.

Note: You need to use Level 3 Authentication in order to set it to anything else than "none".

Default value: false

This argument controls if log entries are included. There are three options:

• true - include the latest log entries for each cache; the lpc argument controls the number of included entries,
• user - with Level 3 Authentication, include (only) the latest log entries of your user for each cache. With Level 1 or 2 Authentication, include (only) the latest log entries of the user given in the user_uuid argument. The lpc argument controls the number of included entries,
• false - do not include any log entries.

You must set ns_ground argument to true if you want to use this.

Default value: 10

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.

• true - include additional waypoints as <wpt> elements. They will be handled like separate geocaches, but represented - depending on the application - by special symbols or names.

  Combine this with ns_gsak if you want them to be appear as child waypoints of the geocache instead. Please note that some applications do not properly understand (and will ignore) GSAK child waypoint metadata,

• desc:table - additional waypoints will be listed as a table in the cache description (ns_ground has to be true). Developers may customize the table's appearance by overriding CSS styles for the okapi-alt-wpts class,

• false - do not include additional waypoints.

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'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:

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

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.

• If the type provided doesn't match any alternate waypoints, the default coordinates of the geocache will be used.

• If the type matches exactly one alternate waypoint, then:

  • The lat and lon attributes of the "primary" <wpt> element will be replaced with the location of the matched alternate waypoint,
  • The name of the geocache will be prefixed with the value suppiled in location_change_prefix parameter,
  • The desription of the waypoint will be included in the header of the cache description,
  • The matched alternate waypoint will be removed from the list of alternate waypoins (in order to avoid duplicate locations),
  • Extra alternate waypoint will be created, with the original location of the geocache.
• If the type provided matches multiple alternate waypoints, then the first one will be chosen.

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.