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. Permissions derived from your Access Token will be delegated to both of these methods.

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

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}

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

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