ver. 1958 (4e4db56)
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

Search for geocaches
:: services/caches/search/all method

Minimum Authentication: Level 1 (see Authentication Levels)
https://www.opencaching.us/okapi/services/caches/search/all

Search for geocaches using some simple filters. All of them are optional, but you surely want to use at least some of them.

  • If you're looking for a way to keep your geocaching database in sync with ours, have a peek at the replicate module.
  • Usually you will want to use search_and_retrieve method instead of this one. This way, you can get much more data in one request.
type optional

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.

status optional

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

owner_uuid optional

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.

name optional

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.

terrain optional

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.

difficulty optional

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.

size optional

Deprecated. Please use size2 instead - this will allow you to differentiate "nano" vs. "micro" and "none" vs. "other" sizes (details).

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

Note: If you use this parameter, all caches which do not have a container (like Event or Virtual caches) will be excluded from the results. If you want caches with no container included, append "|X" suffix to the value of this parameter (e.g. "3-5|X").

size2 optional

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.

rating optional

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.

min_rcmds optional

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.
min_founds optional

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.

max_founds optional

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

modified_since optional

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

found_status optional

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.
found_by optional

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

not_found_by optional

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

watched_only optional

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

exclude_ignored optional

Default value: false

Deprecated (why?), please use ignored_status instead.

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, caches which the user has marked as ignored will not be included in the result.

ignored_status optional

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.
exclude_my_own optional

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.

with_trackables_only optional

Default value: false

Boolean. If set to true, only caches with at least one trackable will be included in the result.
ftf_hunter optional

Default value: false

Boolean. If set to true, only caches which have not yet been found by anyone will be included.
powertrail_only optional

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.

powertrail_ids optional

Deprecated (why?).

Pipe-separated list of internal geopath IDs. If given, then only the caches which belong to at least one of the referenced geopaths will be included. Only active geopaths are taken into consideration; IDs which reference inactive or nonexistent geopaths will be ignored.

Geopaths are sets of geocaches. Only some Opencaching sites implement this feature. If this site does not implement it, then whenever you use this parameter, you will always receive an empty result.

Note that OKAPI does not and will not expose internal geopath IDs. You should not use them. This parameter was implemented for internal use.

set_and optional

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.

limit optional

Default value: 100

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

offset optional

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.

order_by optional

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.

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 the following structure:

  • results - a list of cache codes,
  • more - boolean, true means that there were more results for your query, but they were not returned because of the limit parameter.