post.search

This service can be used to search a list of specified valid providers for image results. Every search, along with all results' metadata, are stored locally within the Snaggr infrastructure and can be referenced at anytime via the get.search service.

Some providers only allow searching via the use of tags. Providing a traditional search phrase may not yield proper results from such providers. To work around this, Snaggr automatically pulls out meaningful words from your search phrase and automatically builds a tag list. This tag list is then accordingly applied to a provider.

To manage these resulting tags, Snaggr provides the tags service.

About

Supported Formats

• XML
• JSON
• PHP

Attributes

Cacheable   - Yes
Cache TTL   - 5 Mins.
Secure      - Yes
Metered     - Yes
Limit       - 1,000 Requests
Limit Cycle - 24 Hrs.

Parameters

key          - (string)  The API key associated with your application. [REQUIRED]
keywords     - (string)  The search phrase to be applied to the selected providers. [REQUIRED]
providers    - (array)  An array containing the search providers to use. [REQUIRED]
adult        - (boolean) If set to '1', Snaggr will attempt to return safe images from supporting providers.
custom_one   - (string)  A field an API user may use to store 3rd-party information.
custom_two   - (string)  A field an API user may use to store 3rd-party information.
custom_three - (string)  A field an API user may use to store 3rd-party information.
cache        - (boolean) If set to '1', the results will be cached.

Example Request

The following POST or GET data will search Flickr, Bing and TweetPhoto for pictures of burgers while displaying the individual result sets within page 2, with a limit of 15 images per page and then cache them:

key          = API_KEY
keywords     = burgers
providers[0] = flickr
providers[1] = bing
providers[2] = tweetphoto
page         = 2
limit        = 15
cache        = 1

Example Responses

Below you will find some examples of what a search response would look like. Although some providers may return provider-specific fields, all providers must return the following:

id      - A 32-character md5 hash of the image's direct url. Snaggr references the image using this hash
source  - The originating domain of the image
title   - Snaggr will attempt to return the title of the image
url     - The direct URL to the original image
thumb   - The direct URL to a thumbnail version
context - The direct URL to the page this image is hosted on

Also note, that within the header block, there is an added attribute representing this search's id. It is located in rsp/search@id if you're using xml. If not, you will find it within the header array under id with json or php.

Files

• post.search.xml
• post.search.json
• post.search.php

Valid URLs

• http://rest.snag.gr/images/post.search.xml
• http://rest.snag.gr/images/post.search.json
• http://rest.snag.gr/images/post.search.php

Helpful Links

• get.providers service
• Supported Providers

Provider-specific details can be found on the providers overview section of this documentation.