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.

NewsShow Documentation

Audience

This documentation is designed for people familiar with JavaScript programming and object-oriented programming concepts. There are many JavaScript tutorials available on the Web.

Introduction

The Google NewsShow embeds a news slideshow on your page, letting your users see headlines and previews of Google News Search results, based on queries that you've selected. The NewsShow can be easily added to your page through the use of an iframe or you can call the classes directly for additional customization.

Including the NewsShow on Your Page

To include the NewsShow in your page, you will utilize the Google API loader. The common loader allows you to load all of the AJAX APIs that you need, including the NewsShow. You need to both include the Google APIs script tag and call google.load("elements", "1", {packages : ["newsshow"]}):

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

        google.load("elements", "1", {packages : ["newsshow"]});
        </script>

The first script tag loads the google.load function, which lets you load individual Google APIs. google.load("elements", "1", {packages : ["newsshow"]}) loads Version 1 of the NewsShow element. Currently we're in Version 1, but new versions may be available in the future. See the versioning discussion below for more information. See an example of how to load the NewsShow.

Normally, the language of the user interface will be chosen automatically by the system based on the value of the Accept-Language http header. If this header is not present, a value of en is assumed. However, if you wish to supply a different language, you must do so while loading the NewsShow element. Replace the above google.load("elements", "1", {packages : ["newsshow"]}); with this code:

        var loadOptions = {packages : ["newsshow"]};
	loadOptions.language = "en";
	google.load("elements", "1", loadOptions);

Replace en with your language of choice.

API Updates

The second argument to google.load is the version of the API you are using. Currently the we're in version 1, but new versions may be available in the future.

If we do a significant update to the API in the future, we will change the version number and post a notice on Google Code and the AJAX APIs discussion group. When that happens, we expect to support both versions for at least a month in order to allow you to migrate your code.

The API team periodically updates the API with the most recent bug fixes and performance enhancements. These bug fixes should only improve performance and fix bugs, but we may inadvertently break some API clients. Please use the AJAX APIs discussion group to report such issues.

The NewsShow

google.elements.NewsShow

This object implements the google.elements.NewsShow interface which can display a series of news articles from the Google News service, one after another.

google.elements.NewsShow - Constructor

Constructor Description

google.elements.NewsShow (container, opt_options)

The constructor is used to create an instance of a NewsShow object designed to provide and display search results from the Google News service. The only required parameter is "container", which instructs the NewsShow in which container to display the news articles. The method also accepts an optional parameter which controls the NewsShow's options.

  • container - Containing DIV element by reference or id.
  • opt_options - Optional set of configurable parameters:
    • queryList - This is a list of the query Objects representing the search that will be done to populate the NewsShow. These are the properties available to each query:
      • q - This argument supplies the query, or search expression, that is passed into the searcher. It or topic must be set for each query. See an example of how to use this property.
      • topic - This optional argument tells the news search system to scope search 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
        A topic selection can only be used without a query. If both a query and topic are specified, the query will be ignored. See an example of how to use this property.

        Topics vary slightly from edition to edition. E.g., in African editions like Namibia or Zimbabwe(&ned=en_na, &ned=en_zw) the topic af is available and represents the African topic. In general, if you are viewing an edition of Google News and see a topic of interest, click on the topic header and view the &topic argument in the browser's address bar.

      • rsz - This optional argument supplies the number of results that the application would like to recieve. A value of small indicates a small result set size or 4 results. A value of large indicates a large result set or 8 results. If this argument is not supplied, a value of small is assumed. See an example of how to use this property.
      • ned - This optional argument tells the news search system which edition of news to pull results from. Values include:
        • us - specifies the US edition
        • uk - specifies the UK edition
        • fr_ca - specifies the French Canadian edition
        • etc.
        The best way to understand the available set of editions is to look at the edition links at the bottom of Google News. After clicking on an edition, note the value of &ned argument in the browser's address bar. See an example of how to use this property.
      • scoring - This optional argument tells the news search system how to order results. Results may be ordered by relevance (which is the default) or by date. To select ordering by relevance, do not supply this argument. To select ordering by date, set scoring as scoring=d. See an example of how to use this property.
      Each query must have a "q" or a "topic" defined, but the rest of the properties are optional. The default value includes a small (rsz=small) result set for the following topics: h, b, s, w, e.
    • format - This specifies the dimensions of the NewsShow, valid values are:
      • "728x90"
      • "300x250"
      The default value is "728x90". See an example of how to use this parameter.
    • linkTarget - supplies the target frame that links should open within, valid values include:
      • google.search.Search.LINK_TARGET_BLANK - links will open in a new window,e.g., <A href=... target=_blank...>
      • google.search.Search.LINK_TARGET_SELF - links will open in the same window and frame, e.g., <A href=...target=_self ...>
      • google.search.Search.LINK_TARGET_TOP - links will open in the topmost frame, e.g., <A href=...target=_top ...>
      • google.search.Search.LINK_TARGET_PARENT - links will open in either the topmost frame, or replace the current frame, e.g., <A href=... target=_parent ...>
      • anything-else - links will open in the specified frame or window, e.g., <A href=... target=anything-else ...>
      The default value is google.search.Search.LINK_TARGET_PARENT. See an example of how to use this parameter.
    • deferResumeTime - This specifies the amount of time (in ms) to delay before resuming from the paused state. The default value is 300. See an example of how to use this parameter.
    • deferBootTime - Upon loading, the NewsShow immediately performs the first query and displays the results, then begins executing the remaining queries. The NewsShow will only show results for searches that have been returned within this amount of time (in ms). The deafult value is 2500. For NewsShows with only 1 or 2 queries, this number can be much smaller. See an example of how to use this parameter.
    • displayTime - This specifies the amount of time (in ms) to display each result before transition. The default value is 7500. See an example of how to use this parameter.
    • transitionTime - This specifies the amount of time (in ms) to each transition takes to complete. The default value is 400. See an example of how to use this parameter.

google.elements.NewsShow - Methods

Method Description

.UrlToOptions(opt_url)

This method is used to parse the NewsShow options out of a URL. If no URL is specified, the options will be retrieved from the current document URL. Only options included in the URL are set (except for rsz, which is set to large by default).

  • opt_url - supplies a URL from which to parse parameters
  • returns - an object containing all of the (valid) options contained in the URL (see below for option list), except hl, which cannot be set with this method.

Iframe Solution

The NewsShow can also be embedded onto your page using an iframe (as shown above). For example, place this code into the body of your webpage:

<iframe src="http://www.google.com/uds/modules/elements/newsshow/iframe.html?topic=e,p,s,n&rsz=small"
        frameborder="0" width="728" height="90" marginwidth="0" marginheight="0"></iframe>

The second line contains some parameters adjusting the size and look of the iframe. The first line contains the URL from which to access the NewsShow and some URL arguments to control its behavior. In some cases, an argument is optional. This is indicated with a ? following the name of the argument. In all cases, the value of a CGI argument must be properly escaped (e.g., via the functional equivalent of Javascript's encodeURIComponent() method). This table lists the available URL arguments:

Argument Example Description
q q=Paris%20Hilton This argument supplies the query or queries used to generate the displayed result list. A comma separated list of URL encoded query values are allowed (e.g. &q=hi,bye), as are multiple &q args (e.g. &q=hi&q=bye). This argument or &topic (see below) must be included with at least one value.
topic? topic=b This optional argument supplies the topic or topic used as a query to the News Search. The value of this 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
A comma separated list of topic values are allowed (e.g. &t=h,b), as are multiple &topic args (e.g. &topic=h&topic=b). A topic selection can be used with or without a keyword query Each topic and query (&q) specified will generate results to be displayed subsequently. Note: To use &topic to scope a keyword query, you must implement the JS version.

Topics vary slightly from edition to edition. E.g., in African editions like Namibia or Zimbabwe(&ned=en_na, &ned=en_zw) the topic af is available and represents the African topic. In general, if you are viewing an edition of Google News and see a topic of interest, click on the topic header and view the &topic argument in the browser's address bar.

rsz? rsz=small This optional argument supplies the number of results that the application would like to recieve. A value of small indicates a small result set size or 4 results. A value of large indicates a large result set or 8 results. If this argument is not supplied, a value of large is assumed.
ned? ned=us This optional argument tells the NewsShow which edition of news to pull results from. Values include:
  • us - specifies the US edition
  • uk - specifies the UK edition
  • fr_ca - specifies the French Canadian edition
  • etc.
The best way to understand the available set of editions is to look at the edition links at the bottom of Google News. After clicking on an edition, note the value of &ned argument in the browser's address bar.
hl? hl=en This optional argument supplies the host language of the application making the request. If this argument is not present then the system will choose a value based on the value of the Accept-Language http header. If this header is not present, a value of en is assumed. Note: This argument is not set with the method UrlToOptions.
format? format=728x90 This optional argument specifies the dimensions of the NewsShow, valid values are:
  • "728x90"
  • "300x250"
If this argument is not supplied, a value of 728x90 is assumed.
See an example of how to use the NewsShow in an iframe.