Search parameters

The first step is to choose the parameters for the photos search - such as search by tag, search by lat/long, search by license (or combinations). There are lots of parameters that may be chosen and some of the values are strings, some are numbers and some are from allowed sets (such as license IDs or photo type).

The flickcurl_search_params struct is used to store these parameters and the reference documentation contains all the details on the restrictions. This structure has fields for all of the API search parameters that are not specifically about the list of photos result - such as format, number of results and paging (see below).

There are, however, several constraints on the fields used in a search - some fields are cause expensive (i.e. slow) queries and the web service requires them to be used with additional fields added to make the query sufficiently selective. The restrictions are recorded in the API documentation for the flickcurl_search_params struct as well as in the documentation for the search API calls.

Once the search parameters are chosen, they must be put into a flickcurl_search_params struct. This struct must be initialised to default values with flickcurl_search_params_init() which initialises the struct from a previously allocated piece of memory (or on the stack).

The following code fragment initialises the search parameters to their defaults using the variable params which is stored on the stack. This is freed when the program execution leaves the current block or function. Then the code sets three search parameters - the user_id set to me which makes the search return photos only for the calling user, sets the tags field to "kitten" to perform a tag search and then sets the sort to interestingness-desc which asks that the results are sorted by interestingness with the most interesting kitten photos that the caller took first in the results.

  flickcurl_search_params params;

  params.user_id = "me";
  params.tags = "kitten";
  params.sort = "interestingness-desc";