The Google News 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.

Search Class Reference

The Google News Search JavaScript API is a JavaScript library that allows you to embed Google News 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.

Constructor - produces search results by implementing the interface over the Google News Search service. Upon completion of a search, it delivers a collection of objects. The base class is not directly used except where noted.

Constructor Description

The constructor allows you to execute searches and receive results from the News Search service. 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. is implemented in the following methods, static methods, and properties:


Method Description


.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.


.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.


.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.


.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.


.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.


.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.


.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.


.setResultOrder(orderBy) is a method that changes the order of search results, where orderBy has two possible values:

  • indicates that results should be returned in order of their relevance to the search term(s). This is the default value.
  • indicates that results should be returned in order of publication date.

.setResultOrder() has no return value.

.setRestriction(type, value)

.setRestriction(type, value) restricts the set of News Search results based on a value that you specify. You can use this method to restrict results by location, to return query-relevant quotations from prominent people, or to restrict results to specific news topics (such as world news, business news, and others). You specify the restriction using (type, value) as follows:

  • type specifies the type of restriction desired. Currently, is the only supported type for News Search.
  • value supplies the value for The value may be one of the following:
    • topic scopes results to a particular topic. The value of the argument specifies the topic in the current or selected edition:
      • h - specifies the top headlines topic
      • w - specifies the world topic
      • b - specifies the business topic
      • n - specifies the nation topic
      • t - specifies the science and technology topic
      • el - specifies the elections topic
      • p - specifies the politics topic
      • e - specifies the entertainment topic
      • s - specifies the sports topic
      • m - specifies the health topic

      Warning: You cannot use topic in conjunction with either the query argument. If you specify query with topic, the searcher ignores it.

      Topics vary slightly from edition to edition. For more information about targeting specific editions, see the explanation of ned below.

    • ned tells the News Search system which edition of news to pull results from. For example, ned=us specifies the US edition. To find the ned for other editions, review the links on the Languages and Regions page of Google News help. Each of these links ends with a ned id specific to a country or region.

    For example, the following code sequence restricts a news searcher to the business topic in the German edition of Google News:

    searcher = new
      { "topic" : "b", "ned" : "de"});

To return the searcher to its default behavior, clear the restriction by calling this method with no opt_value, as follows: .setRestriction(type).

.setRestriction() has no return value.


.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.

.setSearchCompleteCallback(object, method, opt_arguments?)

.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 newsSearch.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.


.setSiteRestriction(site) restricts the set of news search results to a specific site, where site provides the title of the news site, with individual words separated either by a space or an underscore.

For example, to restrict your news search to the Seattle Times, call newsSearch.setSiteRestriction("Seattle Times").

To clear site restrictions, pass in a value of null.

.setSiteRestriction() has no return value.

Static methods

Static method Description

.getBranding(opt_element?, opt_orientation?)

.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:
    • requests horizontal orientation. This is the default behavior.
    • 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, not on

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.


.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.

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 News 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 News Search API.

Property Description


When a news result has a set of related stories, this URL is available. Otherwise, it is null. When a related set of stories is available, the URL points to a landing page listing the related stories.


Supplies a snippet of content from the news story associated with this search result.


.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 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 News 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.


Indicates the type of result (for example, indicates GnewsResult).


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 News Search API.

// clone the .html node from the result
var node = result.html.cloneNode(true);

// attach the node into my dom


This optional property appears in a result when the system has determined that there is a good image that represents the cluster of news articles related to this result.

Warning: The image relates to the cluster of news articles for this result, not just the primary article. Therefore, you need to be careful to ensure that your user interface doesn't misrepresent the image. If you use this property, you must always display the news source of the article as well as the news source of the image; they are often different. For example, Google News displays the image next to the results with full attribution to the source. The image is hyperlinked to its associated article.

This property is optional. It does not always exist. It's best to check for .image == undefined before interacting with the property. When the property is present, it contains the following sub-properties:

  • .title supplies the title of the article associated with the image.
  • .titleNoFormatting supplies the title as above, but stripped of HTML formatting.
  • .url supplies the URL of this image as it is found in the article.
  • .originalContextUrl supplies the URL of the article that contains this image. The image, when displayed, should normally link through this URL.
  • .publisher supplies the publisher of the news article containing the image. The suggested user interface is to display this under or in close proximity to the image, hyper linked through the .url property from above.
  • .tbUrl supplies the URL of a thumbnail of the image.
  • .tbWidth supplies the width of the image referenced above. The standard size of this image is 80 pixels wide and 50 pixels tall.
  • .tbHeight supplies the height of the image referenced above. The standard size of this image is 80 pixels wide and 50 pixels tall.


This optional property indicates the language of the news story.


Contains the location of the news story. This is a list of locations ordered from most specific to least specific. The components are separated by ",". There may only be one element in the list. A typical value for this property is "Edinburgh,Scotland,UK".


Supplies the published date (rfc-822 format) of the news story referenced by the associated search result.


Supplies the name of the publisher of the news story (e.g., "Reuters").


This property is optional. It only appears in a result when the story also has a set of closely related stories. Each element within the array contains the following subset of properties also documented in this section:

  • .title
  • .titleNoFormatting
  • .unescapedUrl
  • .url
  • .publisher
  • .location
  • .publishedDate


.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 GnewsResult object is produced by It is available in that object's .results[] array.
  • This object is indicated by a .GsearchResultClass value of


Supplies the title of the news story returned as a search result.


Supplies the title, but unlike .title, this property is stripped of HTML markup (such as <b>, <i>, etc.).


Supplies the raw result URL with non-alphanumeric characters. For example:


Provides an encoded URL. For example:


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.