Search for geocaches

:: services/caches/search/all method

Pipe-separated list of cache type codes. If given, the results will be limited to the given cache types. For a list of known types, see the services/caches/geocache type field.

Note: If you want to include all cache types except the given ones, prepend your list with the "-" sign.

Default value: Available

Pipe-separated list of status codes. Only caches matching any of the given statuses will be included in the response. There are three primary status codes:

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

More statuses are in use at OC sites and may be implemented in future OKAPI versions (see discussion).

Pipe-separated list of user IDs. If given, the list of returned caches will be limited to those owned by the given users.

Note: User ID and Username are two different things!

Note: If you want to include all caches except the ones owned by the given users, prepend your list with the "-" sign.

UTF-8 encoded string - the name (or part of the name) of the cache.

Allowed wildcard characters:

• asterisk ("*") will match any string of characters,
• underscore ("_") will match any single character.

Name matching is case-insensitive. Maximum length for the name parameter is 100 characters.

Examples:

• "name=the *" returns caches which name starts with "the " (or "The ", etc.),
• "name=water tower" returns caches which have exactly that name (case insensitive),
• "name=*water tower*" will match caches like "Beautiful Water Tower II",
• "name=*tower_" will match "Water Towers" but will not match "Water Tower".

Note: Cache code and name are two different things - if you want to find a cache by its code, use the services/caches/geocache method.

Default value: 1-5

A string "X-Y", where X and Y are integers between 1 and 5, and X <= Y. Only caches with terrain rating between these numbers (inclusive) will be returned.

Default value: 1-5

A string "X-Y", where X and Y are integers between 1 and 5, and X <= Y. Only caches with difficulty rating between these numbers (inclusive) will be returned.

Pipe-separated list of "size2 codes". Only matching caches will be included. The codes are: 'none', 'nano', 'micro', 'small', 'regular', 'large', 'xlarge', 'other'.

Note: If you want to include all cache sizes except the given ones, prepend your list with the "-" sign.

A string "X-Y", where X and Y are integers (why not floats?) between 1 and 5, and X <= Y. Only caches with an overall rating between these numbers (inclusive) will be returned (1 - poor, 5 - excellent).

Note: If you use this parameter, then caches with "not enough" votes will be excluded from results. The definition of "not enough" may vary. If you want such "insufficiently rated" caches to be included, then append "|X" suffix to the value of this parameter (e.g. "3-5|X").

Note: Not all Opencaching installations provide ratings for their geocaches. The has_ratings field of services/apisrv/installation tells if ratings are available. If not, this parameter will be ignored.

There are two possible value-types for this argument:

• Integer N. If N given, the result will contain only those caches which have at least N recommendations.
• Integer N with a percent sign appended (e.g. "20%"). The result will contain only those caches which have at last N% ratio of recommendations/founds. Please note, that this is useful only with conjunction with min_founds parameter.

Integer N. If N given, the result will contain only those caches which have been found at least N times. Useful if you want to skip "unverified" caches.

Integer N. If N given, the result will contain only those caches which have been found at most N times. Useful for FTF hunters.

A date and time string. This should be in ISO 8601 format (currently any format acceptable by PHP's strtotime function also will do, but most of them don't handle time zones properly, try to use ISO 8601!).

If given, the list of returned geocaches will be limited to those which were created or modified since that date. (Note: currently caches do not get "modified" when user makes a log entry.)

Default value: either

Note: This parameter may be used only for requests signed with an Access Token (you will need to use Level 3 Authentication).

Should be one of the following:

• found_only - only caches found by the user will be returned,
• notfound_only - only caches not found by the user will be returned,
• either - all caches will be returned.

Pipe-separated list of user IDs. If given, the response will only include geocaches found by at least one of the given users.

Pipe-separated list of user IDs. If given, the response will only include geocaches not found by any of the given users.

Default value: false

Note: This parameter may be used only for requests signed with an Access Token (you will need to use Level 3 Authentication).

Boolean. If set to true, only caches which the user has recommended will be included in the result.

Pipe-separated list of user IDs. If given, the response will only include geocaches recommended by at least one of the given users.

Default value: false

Note: This parameter may be used only for requests signed with an Access Token (you will need to use Level 3 Authentication).

Boolean. If set to true, only caches which the user has marked as watched will be included in the result. This might be used to temporarily mark geocaches of particular interest (e.g. "all the caches I plan to find today").

Default value: either

Note: This parameter may be used only for requests signed with an Access Token (you will need to use Level 3 Authentication).

Should be one of the following:

• ignored_only - only caches which the user has marked as ignored will be returned,
• notignored_only - only caches which the user has not marked as ignored will be returned,
• either - all caches will be returned.

Default value: false

Note: This parameter may be used only for requests signed with an Access Token (you will need to use Level 3 Authentication). See owner_uuid parameter if you don't want to use OAuth.

Boolean. If set to true, caches which the user is an owner of will not be included in the result.

Default value: false

Default value: false

Default value: false

Boolean. If set to true, only caches which belong to at least one active geopath will be included.

Geopaths are sets of geocaches. All of the caches need to be found to complete the geopath. Only some Opencaching sites implement this feature. If this site does not implement it, and you will set this parameter to true, then you will always receive an empty result.

Note: The parameter name "powertrail_only" is historical. Geopaths can be powertrails, but need not to be. Any caches of active geopaths will be included that match the other search criteria.

ID of a set previously created with the search/save method. If given, the results are ANDed together with this set.

If you want to simply retrieve the contents of set, then please note the default value of the status parameter! You may want to override it in order to include unavailable and/or archived geocaches within the set.

Default value: 100

Integer in range 1..500. Maximum number of cache codes returned.

Default value: 0

An offset, the amount of items to skip at the beginning of the result. Combined with limit allows pagination of the result set. Please note, that the sum of offset and limit still cannot exceed 500. You MAY NOT use this method to list all the caches, it is for searching only. Have a peek at the replicate module if you need all the caches.

Pipe separated list of fields to order the results by. Prefix the field name with a '-' sign to indicate a descending order.

Currently, fields which you can order by include: code, name, founds, rcmds, rcmds%, date_created, date_hidden (tell us if you want more).

Examples:

• to order by cache name use "order_by=name" or "order_by=+name",
• to have the most recommended caches in front, use "order_by=-rcmds%",
• multicolumn sorting is also allowed, ex. "order_by=-founds|+name"

Note: For most other methods (like bbox and nearest), the default order is by the distance from the center. If you supply custom order_by parameter, then we will try to order by your preference first, and then by the distance later.