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 |
Search for geocaches
|
|
||||
https://www.opencaching.de/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.
|
||||
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:
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:
Name matching is case-insensitive. Maximum length for the name parameter is 100 characters. Examples:
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:
|
||
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_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. |
||
recommended_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 recommended will be included in the result. |
||
recommended_by | optional |
Pipe-separated list of user IDs. If given, the response will only include geocaches recommended by at least one 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:
|
||
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:
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:
|