The Google Image Search API has been officially deprecated as of May 26, 2011. It will continue to work as per our deprecation policy, but the number of requests you may make per day may be limited. We encourage you to use the Custom Search API, which now supports image search.

Your application uses the userip parameter (not required, but highly encouraged). This parameter supplies the IP address of the end-user who made the request and validates that you are not making automated requests in violation of the Terms of Service.

Using the JSON interface

The easiest way to start learning about this interface is to try it out. This section shows how to use the curl command line tool to execute sample queries.

Using the callback argument

In addition to this response format, the protocol also supports a classic JSON-P style callback which is triggered by specifying a callback argument. When this argument is present, the JSON object is delivered as an argument to the specified callback.

This command performs a Image Search that is identical to the previous search, except that it has been altered to pass callback. With this argument in place, instead of a JSON object being returned, a Javascript call is returned in the response and the JSON object is passed via the results parameter.

Using the context argument

Finally, the protocol supports a context argument. When both callback and context are specified, the response is encoded as a direct JavaScript call with a signature of: callback(context, results, status, details, unused). Note the slight difference in the following command and response.

This command performs a Image Search that is identical to the previous search, except that it has been altered to pass both callback and context. With these arguments in place, instead of a JSON object being returned, a JavaScript call is returned in the response and the JSON object is passed via the results parameter.

processResults('foo',{
"results": [
... // results array
]
});

Code examples

The following sections contain code snippets that show how to access the Image Search API from Flash, Java, PHP, Python, and Perl.

Warning: You should include the userip parameter, which supplies the IP address of the end-user who made the request and validates that you are not making automated requests in violation of the Terms of Service.

If you have trouble processing the JSON response, visit the JSON.org site, and pay particular attention to the second half of the page where various JSON libraries are referenced. See the JSON reference section below for details on how the Image Search API is made available through the JSON API.

Using Flash

The following code snippet shows how to make a request to the Google Image Search API using Flash. This example uses JSON from the ActionScript 3.0 (AS3) Core Library.

Using Perl

The following code snippet shows how to make a request to the Google Image Search API using Perl. This sample relies on the LWP::UserAgent and JSON modules which you can obtain from CPAN. You may also want to use the URI::Escape module.

JSON reference

Unlike the core JavaScript interface, the JSON interface is exposed through a uniform URL that contains CGI arguments. Your application can use an HTTP stack of its choosing. In order to use the JSON interface:

You must construct a properly formatted URL with all necessary CGI arguments.

You must send an HTTP referer header that accurately identifies your application.

You must process the JSON-encoded response.

Request format

URL base address

The standard URL for the Google Image Search API is:

https://ajax.googleapis.com/ajax/services/search/images

URL arguments

This section describes the arguments that can be used for Image Search requests.

The value of a CGI argument must always be properly escaped. This can be done via the functional equivalent of JavaScript's encodeURIComponent() method.

Required URL arguments

The following table lists the required URL arguments.

Argument

Example

Description

q

q=fuzzy%20monkey

This argument supplies the query, or search expression, that is passed into the searcher.

v

v=1.0

This argument supplies protocol version number. The only valid value at this point in time is 1.0.

Optional URL arguments

The following table lists the optional URL arguments.

Argument

Example

Description

as_filetype

as_filetype=jpg

Restricts image search to one of the following specific file types:

as_filetype=jpg restricts results to JPG images

as_filetype=png restricts results to PNG images

as_filetype=gif restricts results to GIF images

as_filetype=bmp restricts results to BMP images

as_rights

as_rights=cc_publicdomain

This optional argument tells the image search system to restrict the search to images labeled with the given licenses, where rights can be one or more of:

as_rights=cc_publicdomain restricts search results to images with the publicdomain label.

as_rights=cc_attribute restricts search results to images with the attribute label.

as_rights=cc_sharealike restricts search results to images with the sharealike label.

as_rights=cc_noncommercial restricts search results to images with the noncomercial label.

as_rights=cc_nonderived restricts search results to images with the nonderived label.

These restrictions can be used together, both positively or negatively. For instance, to emulate the commercial use with modification license, set the following:

Note: Images returned with this filter may still have conditions on the license for use. Please remember that violating copyright is strictly prohibited by the API Terms of Service. For more details, see this article.

as_sitesearch

as_sitesearch=photobucket.com

Tells the image search system to restrict the search to images within the specified domain,such as as_sitesearch=photobucket.com.

Note: This method restricts results to images found on pages at the given URL.

callback

callback=foo

This argument alters the standard response format. When supplied, instead of producing a simple JSON-encoded object, the system produces a JavaScript function call response where the value of callback specifies the name of the function called in the response.

This argument supplies the host language of the application making the request. If hl is present in the URL, it will be used. Otherwise, if the Accept-Language HTTP header is present, it will be used. If neither is specified, a value of en is assumed.

imgc

imgc=gray

This optional argument tells the image search system to restrict the search to images of the specified colorization, where colorization can be one of:

imgc=gray restricts results to grayscale images.

imgc=color restricts results to color images.

imgcolor (experimental)

imgcolor=black

Restricts results to images that contain a specified color predominantly:

imgcolor=black

imgcolor=blue

imgcolor=brown

imgcolor=gray

imgcolor=green

imgcolor=orange

imgcolor=pink

imgcolor=purple

imgcolor=red

imgcolor=teal

imgcolor=white

imgcolor=yellow

imgsz

imgsz=icon

Restricts the search to images of the specified size, where size can be one of:

This argument supplies an integer from 1–8 indicating the number of results to return per page.

safe

safe=active

Specifies the search safety level, which may be one of the following:

safe=active enables the highest level of safe search filtering.

safe=moderate enables moderate safe search filtering (default).

safe=off disables safe search filtering.

start

start=4

This argument supplies the start index of the first search result. Each successful response contains a cursor object (see below) which includes an array of pages. The start property for a page may be used as a valid value for this argument. For reference, a sample cursor object is shown below:

This argument supplies the IP address of the end-user on whose behalf the request is being made. Requests that include it are less likely to be mistaken for abuse. In choosing to utilize this parameter, please be sure that you're in compliance with any local laws, including any laws relating to disclosure of personal information being sent.

Response format

Basic query

There are two major variations in the response format. When the callback and context arguments are not supplied, the response format is a simple JSON object:

In the JSON fragment above, note that the responseData property contains a results array and an optional cursor.

cursor

.cursor is an optional property that is present once a search completes successfully. When present, the property specifies how an application can request additional search results for the current query term, the estimated result count, the current page, and the URL for a search results page. The property has the following structure:

pages[] supplies an array used by start in order to iterate through all available results. Each entry in the array is an object with the following structure:

start supplies the value that will be used in the &start URL argument to request a bundle of results

Note: The Image Searcher supports a maximum of 8 result pages. When combined with subsequent requests, a maximum total of 64 results are available. It is not possible to request more than 64 results.

results[]

.results[] contains an array of search result objects, one for each result. Each time a search executes, this property is cleared, and each time a search completes, the array is populated. If there are no results to report, the .length property of this array will be set to 0. Therefore, results will never be null, and you can always safely check for results.length == 0.

The GimageResult object is produced by google.search.ImageSearch. It is available in that object's .results[] array.

This object is indicated by a .GsearchResultClass value of google.search.ImageSearch.RESULT_CLASS.

Results array: guaranteed fields

The results array always contains the parameters listed in this section, even if the value is empty.

Property

Description

content

Supplies a brief snippet of information from the page associated with the image result.

contentNoFormatting

Supplies the same information as .content, only stripped of HTML formatting.

GsearchResultClass

Indicates the type of result (for example, google.search.ImageSearch.RESULT_CLASS indicates GimageResult).

height

Supplies the height of the image in pixels.

html

Supplies the root of an HTML element that may be cloned and attached somewhere into the application's DOM hierarchy. We expect that this is the primary property that applications will use, typically by cloning this node and attaching it to the DOM hierarchy.

We expect applications to control styling, as well as which elements are displayed, using CSS. For instance, we expect the following fragment to be common across all applications that wish to copy and paste search results delivered through the Image Search API.

// clone the .html node from the result
var node = result.html.cloneNode(true);
// attach the node into my domcontainer.appendChild(node);

originalContextUrl

Supplies the URL of the page containing the image.

tbHeight

Supplies the height, in pixels, of the image thumbnail.

tbUrl

Supplies the URL of a thumbnail image.

tbWidth

Supplies the width, in pixels, of the image thumbnail.

title

Supplies the title of the image, which is usually the base filename (for example, monkey.png.

titleNoFormatting

Supplies the page title associated with the search result, but unlike .title, this property is stripped of HTML markup (e.g., <b>, <i>, etc.).

unescapedUrl

Supplies the raw URL (containing non-alphanumeric characters) to an image in the result set. For example:

Context argument

The context argument must always be specified in conjunction with the callback argument. If the application supplies both callback and context arguments, the response is encoded as a JavaScript procedure call. In this mode of operation:

The value of callback becomes the procedure call target.

The value of context is passed as the first argument.

The value of responseData from above is passed as the second argument.