Google Image Search API (Deprecated)

Image Search Developer's Guide

The Google Image Search JavaScript API is a JavaScript library that allows you to embed Google Image Search in your web pages and other web applications. For Flash, and other non-JavaScript environments, the API exposes a raw interface that returns JSON-encoded results that are easily processed by most languages and runtimes. Read more in the JSON Developer's Guide.

This API is constantly evolving based on the active contributions of our users. Please join us in helping to shape the API and features by participating in the Google Search API discussion group.

Table of Contents

  1. Introduction
    1. Browser compatibility
    2. Audience
    3. The "Hello World" of Image Search
  2. Getting started
    1. Load the JavaScript API and search module
  3. Building a basic application
    1. Execute a search
    2. Call the search completion handler
    3. Register a handler for intialization
    4. Add Google branding
    1. Handle search results
      1. Result properties
      2. Result styling
  1. Configuring optional methods
    1. Set an additional query term
    2. Specify the size of the result set
    3. Return the current result set size
    4. Clear the current search results
    5. Create or regenerate the .html property
    6. Clear the current search results
    7. Prevent the searcher from generating the .html property
    8. Request additional search parameters
    9. Request a specific results page
    10. Create an array of search results
    11. Set a site restriction
    12. Set an additional restriction
  2. Troubleshooting

Introduction

This developer's guide provides a basic model for using the Google Image Search API, along with granular explanations of the API's configurable JavaScript components. You can use this guide to configure Image Search on your page.

Browser compatibility

The Google Image Search API currently supports Firefox 1.5+, IE6+, Safari, Opera 9+, and Chrome.

Audience

This documentation is intended for developers who wish to add Google Image Search functionality to their pages using the Image Search API.

The "Hello World" of Image Search

The following example creates an instance of Image Search on your page. This Image Search instance is controlled by a text input field and clear button to clear search results after a search.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Google Search API Sample</title>
    <script src="https://www.google.com/jsapi"></script>
    <script type="text/javascript">

      google.load('search', '1');

      var imageSearch;

      function addPaginationLinks() {
      
        // To paginate search results, use the cursor function.
        var cursor = imageSearch.cursor;
        var curPage = cursor.currentPageIndex; // check what page the app is on
        var pagesDiv = document.createElement('div');
        for (var i = 0; i < cursor.pages.length; i++) {
          var page = cursor.pages[i];
          if (curPage == i) { 

          // If we are on the current page, then don't make a link.
            var label = document.createTextNode(' ' + page.label + ' ');
            pagesDiv.appendChild(label);
          } else {

            // Create links to other pages using gotoPage() on the searcher.
            var link = document.createElement('a');
            link.href="/image-search/v1/javascript:imageSearch.gotoPage("+i+');';
            link.innerHTML = page.label;
            link.style.marginRight = '2px';
            pagesDiv.appendChild(link);
          }
        }

        var contentDiv = document.getElementById('content');
        contentDiv.appendChild(pagesDiv);
      }

      function searchComplete() {

        // Check that we got results
        if (imageSearch.results && imageSearch.results.length > 0) {

          // Grab our content div, clear it.
          var contentDiv = document.getElementById('content');
          contentDiv.innerHTML = '';

          // Loop through our results, printing them to the page.
          var results = imageSearch.results;
          for (var i = 0; i < results.length; i++) {
            // For each result write it's title and image to the screen
            var result = results[i];
            var imgContainer = document.createElement('div');
            var title = document.createElement('div');
            
            // We use titleNoFormatting so that no HTML tags are left in the 
            // title
            title.innerHTML = result.titleNoFormatting;
            var newImg = document.createElement('img');

            // There is also a result.url property which has the escaped version
            newImg.src="/image-search/v1/result.tbUrl;"
            imgContainer.appendChild(title);
            imgContainer.appendChild(newImg);

            // Put our title + image in the content
            contentDiv.appendChild(imgContainer);
          }

          // Now add links to additional pages of search results.
          addPaginationLinks(imageSearch);
        }
      }

      function OnLoad() {
      
        // Create an Image Search instance.
        imageSearch = new google.search.ImageSearch();

        // Set searchComplete as the callback function when a search is 
        // complete.  The imageSearch object will have results in it.
        imageSearch.setSearchCompleteCallback(this, searchComplete, null);

        // Find me a beautiful car.
        imageSearch.execute("Subaru STI");
        
        // Include the required Google branding
        google.search.Search.getBranding('branding');
      }
      google.setOnLoadCallback(OnLoad);
    </script>

  </head>
  <body style="font-family: Arial;border: 0 none;">
    <div id="branding"  style="float: left;"></div><br />
    <div id="content">Loading...</div>
  </body>
</html>

Getting started

Load the JavaScript API and search module

To begin using the Image Search API, include the following script in the header of your web page.

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

Next, load the Google search module with google.load(module, version), where:

  • module calls the specific API module you wish to use on your page (in this case, search).
  • version is the version number of the module you wish to load (in this case, 1).
<script type="text/javascript">
  google.load("search", "1");
</script>

You can find out more about google.load in the Google Loader developer's guide.

When we do a significant update to the API, we will increase the version number and post a notice on the Search API discussion group. Take note of any required code changes when this occurs, and update your URLs to the new version when they are compliant.

The Google API team will also periodically update the API with recent bug fixes and performance enhancements without requiring a version update. For the most part, these fixes should remain transparent to you, but we may inadvertently break some API clients. Please use the Search API discussion group to report such issues.

Building a basic application

The google.search.ImageSearch constructor initializes the Image Search service so you can execute Image Search queries and display results. The methods and properties described below apply to all objects that inherit from this base class. Each of those objects may supply additional interfaces as well.

Execute a search

.execute(query) initiates a new search, where query supplies the search term(s).

This method populates the object with the corresponding set of results, and calls the registered .setSearchCompleteCallback() handler.

.execute() has no return value.

Call the search completion handler

.setSearchCompleteCallback(object, method, opt_arguments?) registers an object and method to notify when a search completes, where:

  • object supplies an application-level object that defines the context in which to call the specified method.
  • method supplies the search completion handler function, which checks for results and appends them to HTML nodes.
  • opt_arguments allows you to optionally pass in a list of arguments, in order, to the specified method. If you choose to use opt_arguments, you must pass in a list (null is also acceptable).

    For example, if you call this method as imageSearch.setSearchCompleteCallback(handler, handler.method, [[1, 2, 3]);, then you execute handler.method(1, 2, 3); when the search completes.

In this API, the calls are asynchronous. Therefore, you can't block on the return and then use the results. Rather, you have to use a callback, which will execute a method upon the return of the results.

.setSearchCompleteCallback() has no return value.

Register a handler for intialization

.setOnLoadCallback(callback) is a static function that registers the specified handler function to be called once the page containing this call loads, where callback is a required function called when the containing document is loaded and the API is ready for use (e.g., after onLoad). This function is implemented on the google namespace (i.e., google.setOnLoadCallback(callback);)

.setOnLoadCallback() has no return value.

Note: Previous documentation recommended that you use the body element's onload attribute (<body onload="OnLoad()">). While this is a fine way to go when you are in complete control of the page and all code loaded by the page, this approach can cause problems with some runtimes that destroy your body.onload handler. setOnLoadCallback() does not have these problems, and therefore is the recommended method of registering a callback that calls your code when the API is fully loaded and ready for use.

Add Google branding

.getBranding(opt_element?, opt_orientation?) is a static helper function that returns a "powered by Google" HTML DOM branding node to your application, and optionally attaches it to your document as the only child of the specified optional element. The purpose of this method is to ensure that your application has a simple way to comply with branding requirements.

The branding node, by default, is designed for a horizontal orientation and works well underneath a search form, above or below a collection of results, etc.

  • opt_element is an optional argument which, if supplied, specifies the HTML DOM node that will be populated with a "powered by Google" branding element.
  • opt_orientation - an optional argument which, if supplied, specifies the orientation of the branding node. Valid values include:
    • google.search.Search.HORIZONTAL_BRANDING requests horizontal orientation. This is the default behavior.
    • google.search.Search.VERTICAL_BRANDING requests vertical orientation.

.getBranding() returns a "powered by Google" HTML DOM node that you can attach or clone onto your document.

You must call .getBranding() on google.search.Search, not on google.search.ImageSearch.

Warning! This API requires displaying attribution near any API input boxes and the display of results, indicating that it is "Powered by Google". If you choose not to use .getBranding(), you are obligated to provide this branding yourself.

Handling search results

Result objects are produced using a JSON encoding of server search requests. Consequently, we have chosen not to implement formal JavaScript objects, and instead dynamically create these objects from their serialized form.

While there is no formal implementation of the objects, they exist, and we document them as if there was a backing JavaScript implementation. The impact of all this is minimal. All that it means is that there is no named constructor. For each result, it's as if the system called new Object() and then set formal properties on that object. These properties are documented below.

Important note: Maximum number of search results

The Google Image Search API allows a maximum of 64 results on 8 pages. There is no way to get more than 64 results.

Result properties

Here are the basic properties allowing you to handle results from the Image Search API.

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 dom
container.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:

http://farm2.static.flickr.com/1104/1434841504_edc671e65c.jpg?v\u003d0

url

Provides the encoded URL to an image file in the result set. For example:

http://farm2.static.flickr.com/1104/1434841504_edc671e65c.jpg%3Fv%3D0

visibleUrl

Supplies a shortened version of the URL associated with the result, typically displayed in green and stripped of a protocol and path.

width

Supplies the width of the image in pixels.

Result styling

The .html property discussed above is built with CSS styling in mind. As a result, each piece of semantic information is enclosed in HTML markup with an appropriate set of class markers. This allows you to use this HTML in conjunction with your own custom CSS rules that style the HTML to meet your needs.

The following fragment of HTML illustrates the structure of a Image Search result's .html property. The purpose of this skeleton is to show you the major structural components work, so that you can alter the styling and display of a result. For instance, if you want to suppress the "snippet", a CSS rule of #mysearcher .gs-imageResult .gs-snippet { display : none; } would do the trick.

Each search result is enclosed in a div element marked with a generic search result class of gs-result, as well as a class specific to the result type (e.g., gs-imageResult). This structure allows you to easily define generic CSS rules that are applied to all results, as well as type-specific rules.

<div class="gs-result gs-imageResult">
  <div class="gs-image-box">
    <!-- img is hyperlinked to the original content url -->
    <a class="gs-image">
      <!-- Note explicit sizing is set during thumbnail scaling -->
      <img class="gs-image"/>
    </a>
  </div>
  <div class="gs-text-box">
    <div class="gs-snippet"></div>
    <div class="gs-size"></div>
    <div class="gs-visibleUrl"></div>
  </div>
</div>

Configuring optional methods

Set an additional query term

.setQueryAddition(term) sets (or clears) an optional, additional query term that is appended to all queries flowing through the searcher, where term supplies the additional term. Applications typically use this API to provide alternative results with mild variations from the original search term.

To clear an existing query addition, call either .setQueryAddition(null) or .setQueryAddition('').

.setQueryAddition() has no return value.

Specify the size of the result set

.setResultSetSize(num) specifies the size of the result set, where num supplies the number of results to display per page, from 1-8.

.setResultSetSize() has no return value.

Return the current result set size

.getResultSetSize() has no arguments and returns an integer from 1–8 indicating the current result set size (which is established by .setResultSetSize(). It allows you to determine the result set size returned by the search.

Create or regenerate the .html property

.createResultHtml(result) allows the caller to either create or re-generate the .html property of the specified result, where result supplies a result object.

If the result has no .html property, this call creates one. One circumstance requiring you to create an .html property is if the caller had previously used .setNoHtmlGeneration().

.createResultHtml() has no return value.

Clear the current search results

.clearResults() resets the searcher, clearing all of the results of the previous search. This method is implicitly called prior to executing a new search.

.clearResults() has no arguments and no return value.

Prevent the searcher from generating the .html property

.setNoHtmlGeneration() stops your application from generating an .html property, leaving you with only the raw properties valid in a result. This property is useful for optimizing your application, if you want to handle rendering of the results yourself.

.setNoHtmlGeneration() has no arguments and no return value.

Request additional search parameters

.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
    • label supplies a text label associated with the entry (for example, "1", "2", "3", or "4")
  • estimatedResultCount supplies the estimated number of results that match the current query. This value will not necessarily match the similar value that is visible on the Google.com search properties.
  • currentPageIndex supplies the index into the pages array of the current set of results.
  • moreResultsUrl supplies a URL to a Google-hosted search page that contains additional search 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.

Request a specific results page

.gotoPage(page) requests a specific page of search results after an initial search completes, where page supplies the page number of the results that the application wants. Numbering of results pages begins at 0, and the searcher returns the first page by default.

If you specify a page number that is out of range, or if the underlying searcher has no .cursor property, no operation is performed.

.gotoPage() has no return value.

Create an array of search 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.

Set a site restriction

.setSiteRestriction(site) restricts the set of image search results to images found on pages at the given URL. To restrict to www.photobucket.com, simply call this method passing in a value of "www.photobucket.com". To clear site restrictions, pass in a value of null.

.setSiteRestriction() has no return value.

The following snippet demonstrates how to restrict results to "photobucket.com".

var siteSearch = new google.search.ImageSearch();
siteSearch.setSiteRestriction("photobucket.com");

Set an additional restriction

.setRestriction(type, opt_value) specifies or clears a restriction on the set of results returned by this searcher. In order to establish a restriction, you need to specify both type and opt_value as described below. To clear a restriction, supply a valid value for type and either specify null for the value of opt_value, or do not supply the opt_value argument.

This API currently supports the following restriction types:

  • google.search.Search.RESTRICT_SAFESEARCH restricts results to images based on one of the following opt_value options:
    • google.search.Search.SAFESEARCH_STRICT filters for both explicit text and explicit images.
    • google.search.Search.SAFESEARCH_MODERATE filters for explicit images (the default behavior).
    • google.search.Search.SAFESEARCH_OFF turns off Safe Search filtering.

    The following code snippet demonstrates how to turn off safe search filtering:

    var searcher = new google.search.ImageSearch();
    searcher.setRestriction(
      google.search.Search.RESTRICT_SAFESEARCH,
      google.search.Search.SAFESEARCH_OFF
    );

  • google.search.ImageSearch.RESTRICT_IMAGESIZE restricts results to images with certain pixel dimensions based on one of the following opt_values:
    • google.search.ImageSearch.IMAGESIZE_SMALL returns small images, icons.
    • google.search.ImageSearch.IMAGESIZE_MEDIUM returns medium-sized images.
    • google.search.ImageSearch.IMAGESIZE_LARGE returns large images.
    • google.search.ImageSearch.IMAGESIZE_EXTRA_LARGE returns extra-large images.

    The following code snippet demonstrates how to retrieve only icon-sized images:

    var searcher = new google.search.ImageSearch();
    searcher.setRestriction(
      google.search.ImageSearch.RESTRICT_IMAGESIZE,
      google.search.ImageSearch.IMAGESIZE_SMALL);

  • google.search.ImageSearch.RESTRICT_COLORIZATION restricts results to images with certain colorization. Valid optional values for this type are as follows:
    • google.search.ImageSearch.COLORIZATION_GRAYSCALE returns only grayscale images
    • google.search.ImageSearch.COLORIZATION_COLOR returns only color images

    The following code snippet demonstrates how to retrieve only grayscale images:

    var searcher = new google.search.ImageSearch();
    searcher.setRestriction(
      google.search.ImageSearch.RESTRICT_COLORIZATION,
      google.search.ImageSearch.COLORIZATION_GRAYSCALE
    );

  • google.search.ImageSearch.RESTRICT_COLORFILTER returns images containing the specified color predominantly. Valid values for this type are as follows:
    • google.search.ImageSearch.COLOR_BLACK
    • google.search.ImageSearch.COLOR_BLUE
    • google.search.ImageSearch.COLOR_BROWN
    • google.search.ImageSearch.COLOR_GRAY
    • google.search.ImageSearch.COLOR_GREEN
    • google.search.ImageSearch.COLOR_ORANGE
    • google.search.ImageSearch.COLOR_PINK
    • google.search.ImageSearch.COLOR_PURPLE
    • google.search.ImageSearch.COLOR_RED
    • google.search.ImageSearch.COLOR_TEAL
    • google.search.ImageSearch.COLOR_WHITE
    • google.search.ImageSearch.COLOR_YELLOW

    The following code snippet demonstrates how to filter on the color red:

    var searcher = new google.search.ImageSearch();
    searcher.setRestriction(
      google.search.ImageSearch.RESTRICT_COLORFILTER,
      google.search.ImageSearch.COLOR_RED
    );

  • google.search.ImageSearch.RESTRICT_FILETYPE restricts images to a certain filetype (such as JPG) using one of the following opt value options:
    • google.search.ImageSearch.FILETYPE_JPG returns only jpeg images.
    • google.search.ImageSearch.FILETYPE_PNG returns only png images.
    • google.search.ImageSearch.FILETYPE_GIF returns only gif images.
    • google.search.ImageSearch.FILETYPE_BMP returns only bmp images.

    The following code snippet demonstrates how to retrieve only images of type PNG:

    var searcher = new google.search.ImageSearch();
    searcher.setRestriction(
      google.search.ImageSearch.RESTRICT_FILETYPE,
      google.search.ImageSearch.FILETYPE_PNG
    );

  • google.search.ImageSearch.RESTRICT_IMAGETYPE (experimental) restricts results to images of certain types. Valid optional values for this type are as follows:
    • google.search.ImageSearch.IMAGETYPE_FACES returns images with faces in them.
    • google.search.ImageSearch.IMAGETYPE_PHOTO returns photos.
    • google.search.ImageSearch.IMAGETYPE_CLIPART returns clipart images.
    • google.search.ImageSearch.IMAGETYPE_LINEART returns images of line drawings.

    The following code snippet demonstrates how to retrieve face images:

    var searcher = new google.search.ImageSearch();
    searcher.setRestriction(
      google.search.ImageSearch.RESTRICT_IMAGETYPE,
      google.search.ImageSearch.IMAGETYPE_FACES
    );

  • google.search.ImageSearch.RESTRICT_RIGHTS restricts results to images that are labeled with certain licenses. Valid optional values for this type are as follows:
    • google.search.ImageSearch.RIGHTS_REUSE restricts search results to images labeled for reuse
    • google.search.ImageSearch.RIGHTS_COMERCIAL_REUSE restricts search results to images labeled for commercial reuse
    • google.search.ImageSearch.RIGHTS_MODIFICATION restricts search results to images labeled for reuse with modification
    • google.search.ImageSearch.RIGHTS_COMMERCIAL_MODIFICATION restricts search results to images labeled for commercial reuse with modification

    The following code snippet demonstrates how to retrieve only images labeled for reuse with modification.

    var searcher = new google.search.ImageSearch();
    searcher.setRestriction(google.search.ImageSearch.RESTRICT_RIGHTS,
                            google.search.ImageSearch.RIGHTS_MODIFICATION);

    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 Use. For more details, see this article.

  • The following slightly-more-complete example demonstrates how to search for JPG face images of Carmen Electra, in grayscale:

    var searcher = new google.search.ImageSearch();
    searcher.setRestriction(
      google.search.ImageSearch.RESTRICT_IMAGETYPE,
      google.search.ImageSearch.IMAGETYPE_FACES
    );
    searcher.setRestriction(
      google.search.ImageSearch.RESTRICT_FILETYPE,
      google.search.ImageSearch.FILETYPE_JPG
    );
    searcher.setRestriction(
      google.search.ImageSearch.RESTRICT_COLORIZATION,
      google.search.ImageSearch.COLORIZATION_GRAYSCALE
    );
    searcher.execute('Carmen Electra');

.setRestriction() has no return value.

Troubleshooting

If you encounter problems with your code:

  • Look for typos. Remember that JavaScript is a case-sensitive language.
  • Use a JavaScript debugger. Google Chrome has a full set of developer tools. In Firefox, you can use the JavaScript console or the Firebug. In IE, you can use the Microsoft Script Debugger.
  • Search the discussion group. If you can't find a post that answers your question, post your question to the group along with a link to a web page that demonstrates the problem.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.