rev. 1076
services/apiref
services/apisrv
services/attrs
services/caches
services/caches/formatters
services/caches/map
services/caches/search
services/caches/shortcuts
services/logs
services/oauth
services/replicate
services/users

Search for caches and retrieve formatted results
:: services/caches/shortcuts/search_and_retrieve method

Minimum Authentication: Level 1 (see Authentication Levels)
http://www.opencaching.us/okapi/services/caches/shortcuts/search_and_retrieve

We think that searching and retrieving data are two different things and that's why they were cleanly separated in the documentation (put in separate methods). This was done primarily to keep the docs clean. This method allows you to do a quick search+retrieve task in one request.

All services/caches/search/* methods respond with a list of cache codes. Then you have to use other method (like services/caches/geocaches) to retrieve the names and locations, based on those cache codes. The search_and_retrieve method allows you to do these two steps in one method call.

First, you have to choose both methods and their parameters - one method which returns the cache codes, and the other one, that responds with additional data for the given caches.

search_method required

Name of the search method (begin with "services/").

E.g. services/caches/search/nearest.

search_params required

JSON-formatted dictionary of parameters to be passed on to the search method.

E.g. {"center": "49|19", "status": "Available"}.

retr_method required

Name of the retrieval method (begin with "services/").

E.g. services/caches/geocaches.

retr_params required

JSON-formatted dictionary of parameters to be passed on to the retrieval method.

E.g. {"fields": "name|location|type"}

The method will be called with one additional parameter - cache_codes. These will be the cache codes collected from the results of the search method.

wrap required

Boolean.

  • If true, then results will be wrapped in an additional object, in order to include any additional data received along with the search_method response (i.e. the more value).
  • If false, then this method will return exactly what the retr_method will respond with.
format optional Standard common formatting argument.
callback optional Standard common formatting argument.
Plus required consumer_key argument, assigned for your application.

Returned value:

If wrap is true, then the method will return a dictionary of the following structure:

  • results - anything the retrival method responds with (as long as it's not an error).
  • any extra keys and values received as a response of the search_method (i.e. the more variable).

If wrap is false, then the method will return anything the retrieval methods responds with (along with its HTTP headers).

Example:

search_and_retrieve
?search_method=services/caches/search/bbox
&search_params={"bbox":"49|19|50|20","limit":"1"}
&retr_method=services/caches/geocaches
&retr_params={"fields":"location"}
&wrap=false

Possible output:
{"OP205A": {"location": "49.572417|19.525867"}}

The same example with wrap=true would return:
{"results": {"OP205A": {"location": "49.572417|19.525867"}}, "more": true}