Image Search Documentation for Yahoo! Search

We’re shutting down this service in April 2011. For further details, please see the Deprecated Services blog post.

Submitting Image Queries

The Image Search Web Service allows you to search the Internet for images.

Request URL

http://search.yahooapis.com/ImageSearchService/V1/imageSearch

Request parameters

See information on constructing REST queries

Parameter Value Description
appid string (required) The application ID. See Application IDs for more information.
query string (required) The query to search for. Use + to include terms, - to exclude terms, and put quotes around "exact phrase".
type all (default), any, or phrase

The kind of search to submit:

  • all returns results with all query terms.
  • any returns results with one or more of the query terms.
  • phrase returns results containing the query terms as a phrase.
results integer: default 10, max 50 The number of results to return.
start integer: default 1 The starting result position to return (1-based). The finishing position (start + results - 1) cannot exceed 1000.
format any (default), bmp, gif, jpeg, png

Specifies the kind of image file to search for.

adult_ok no value or 1 The service filters out adult content by default. Enter a 1 to allow adult content.
coloration any (default), color, bw The service returns only the images of the coloration specified (color or black-and-white).
site string: default no value A domain to restrict your searches to (e.g. www.yahoo.com). You may submit up to 30 values (site=www.yahoo.com&site=www.cnn.com).
output string: xml (default), json, php The format for the output. If json is requested, the results will be returned in JSON format. If php is requested, the results will be returned in Serialized PHP format.
callback string The name of the callback function to wrap around the JSON data. The following characters are allowed: A-Z a-z 0-9 . [] and _. If output=json has not been requested, this parameter has no effect. More information on the callback can be found in the Yahoo! Developer Network JSON Documentation.

Sample Request Url: http://search.yahooapis.com/ImageSearchService/V1/imageSearch?appid=YahooDemo&query=Corvette&results=2

Response fields

The schema document for this service response is located at http://search.yahooapis.com/ImageSearchService/V1/ImageSearchResponse.xsd

Field Description
ResultSet Contains all of the query responses. Has attributes:

  • totalResultsAvailable: The number of query matches in the database.
  • totalResultsReturned: The number of query matches returned. This may be lower than the number of results requested if there were fewer total results available.
  • firstResultPosition: The position of the first result in the overall search.

Result Contains each individual response.
Title The title of the image file.
Summary Summary text associated with the image file.
Url The URL for the image file.
ClickUrl The URL for linking to the image file. See URL linking for more information.
RefererUrl The URL of the web page hosting the content.
FileSize The size of the file in bytes.
FileFormat

One of bmp, gif, jpg, or png.

Height The height of the image in pixels.
Width The width of the image in pixels.
Thumbnail The URL of the thumbnail file and its height and width in pixels.
Publisher The creator of the image file.
Restrictions

Provides any restrictions for this media object. Restrictions include noframe and noinline.

  • Noframe means that you should not display it with a framed page on your site.
  • Noinline means that you should not inline the object in the frame up top (it won't work because the site has some protection based on the "referrer" field).
Copyright The copyright owner.

Sample response

The following is a sample response for the query Madonna:


Rate Limits

The Image Search service is limited to 5,000 queries per IP address per day and to noncommercial use. See information on rate limiting.

Terms of Use

Please see our Usage Policy to learn about acceptable uses and how to request additional queries.

Errors

The Image Search service returns the standard errors. There are no service-specific errors.

Support & Community

The Image Search service is discussed on the yws-search-general mailing list.

Yahoo Groups Discussions