News Search (Deprecated)

JSON Developer's Guide

The Google News Search API JSON interface can be used to write news query applications in any language that can handle a JSON-encoded result set with embedded status codes.

Note: The Google News Search API must be used for user-generated searches. Automated or batched queries of any kind are strictly prohibited.

Contents

  1. Audience
  2. Application requirements
  3. Using the JSON interface
    1. Sending a basic query
    2. Using the callback argument
    3. Using the context argument
  4. Code examples
    1. Using Flash
    2. Using Java
    3. Using PHP
    4. Using Python
    5. Using Perl
  1. JSON reference
    1. Request format
      1. URL base address
      2. URL arguments
    2. Response format
      1. Basic query
      2. Callback argument
      3. Context argument

Audience

The Google News Search JSON interface, and this guide, are provided for Flash developers, and all other developers who need to access News Search from other Non-JavaScript environments.

Application requirements

Applications that use this interface must abide by all existing Terms of Service. Most importantly, you must correctly identify yourself in your requests.

Query inputs and results must display "Powered by Google" branding, as described by .getBranding.

Requests can only be made on behalf of an end user. All results must be displayed.

Applications MUST always include a valid and accurate HTTP referer header in their requests.

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.

Sending a basic query

curl -e http://www.my-ajax-site.com \
'https://ajax.googleapis.com/ajax/services/search/news?v=1.0&q=barack%20obama'

This command performs a news search (/ajax/services/search/news) for Barack Obama (q=barack%20obama). The response has a Content-Type of text/javascript; charset=utf-8.

{"responseData": {
 "results": [
  {
   "GsearchResultClass": "GnewsSearch",
   "clusterUrl": "http://news.google.com/news/story?ncl\u003ddHLAgXM_3xkk1UMqmBLIxMHMlfAEMu0026hl\u003den\u0026ned\u003dus",
   "content": "By MIRIAM JORDAN President \u003cb\u003eBarackObama\u003c/b\u003e enjoys a higher approval rating among Hispanics than among the general electorate, according to a new poll, \u003cb\u003e...\u003c/b\u003e",
   "unescapedUrl": "http://online.wsj.com/article/SB10001424052748703580904575132022909364834.html?mod\u003dgooglenews_wsj",
   "url": "http%3A%2F%2Fonline.wsj.com%2Farticle%2FSB10001424052748703580904575132022909364834.html%3Fmod%3Dgooglenews_wsj",
   "title": "Poll Notes Concern Among Hispanic Voters on Immigration",
   "titleNoFormatting": "Poll Notes Concern Among Hispanic Voters on Immigration",
   "location": "",
   "publisher": "Wall Street Journal",
   "publishedDate": "Fri, 19 Mar 2010 13:26:35 -0700",
   "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-0-0\u0026fd\u003dS\u0026url\u003dhttp://online.wsj.com/article/SB10001424052748703580904575132022909364834.html%3Fmod%3Dgooglenews_wsj\u0026cid\u003d17593726372699\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNE3uhgwmOvcJSd444eShCYZvNxjnw",
   "language": "en",
   "image": {
    "url": "http://media3.washingtonpost.com/wp-dyn/content/photo/2010/03/19/PH2010031900383.jpg",
    "tbUrl": "http://nt3.ggpht.com/news/tbn/3xVeEFy849oJ",
    "originalContextUrl": "http://www.washingtonpost.com/wp-dyn/content/article/2010/03/19/AR2010031900381.html",
    "publisher": "Washington Post",
    "tbWidth": 80,
    "tbHeight": 54
   },
   "relatedStories": [
    {
     "unescapedUrl": "http://www.washingtonpost.com/wp-dyn/content/article/2010/03/19/AR2010031901566.html",
     "url": "http%3A%2F%2Fwww.washingtonpost.com%2Fwp-dyn%2Fcontent%2Farticle%2F2010%2F03%2F19%2FAR2010031901566.html",
     "title": "Latinos press \u003cb\u003eObama\u003c/b\u003e to deliver immigration reform",
     "titleNoFormatting": "Latinos press Obama to deliver immigration reform",
     "location": "",
     "publisher": "Washington Post",
     "publishedDate": "Fri, 19 Mar 2010 09:18:17 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-0-1\u0026fd\u003dS\u0026url\u003dhttp://www.washingtonpost.com/wp-dyn/content/article/2010/03/19/AR2010031901566.html\u0026cid\u003d17593726372699\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNEaln8We-E_DOZ_uiy0c11QnhJung",
     "language": "en"
    },
    {
     "unescapedUrl": "http://abcnews.go.com/Business/wireStory?id\u003d10144730",
     "url": "http%3A%2F%2Fabcnews.go.com%2FBusiness%2FwireStory%3Fid%3D10144730",
     "title": "PROMISES, PROMISES: \u003cb\u003eObama\u003c/b\u003e in Immigration Dance",
     "titleNoFormatting": "PROMISES, PROMISES: Obama in Immigration Dance",
     "location": "",
     "publisher": "ABC News",
     "publishedDate": "Fri, 19 Mar 2010 00:49:30 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-0-2\u0026fd\u003dS\u0026url\u003dhttp://abcnews.go.com/Business/wireStory%3Fid%3D10144730\u0026cid\u003d17593726372699\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNEYoIVgKYkEat0-8L9DmD2ZwNRxBQ",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.pressdemocrat.com/article/20100319/NEWS/3191099/1348",
     "url": "http%3A%2F%2Fwww.pressdemocrat.com%2Farticle%2F20100319%2FNEWS%2F3191099%2F1348",
     "title": "\u003cb\u003eObama\u003c/b\u003e backs new congressional \u0026#39;blueprint\u0026#39; for immigration law",
     "titleNoFormatting": "Obama backs new congressional \u0026#39;blueprint\u0026#39; for immigration law",
     "location": "",
     "publisher": "Santa Rosa Press Democrat",
     "publishedDate": "Fri, 19 Mar 2010 09:04:25 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-0-3\u0026fd\u003dS\u0026url\u003dhttp://www.pressdemocrat.com/article/20100319/NEWS/3191099/1348\u0026cid\u003d17593726372699\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNFQmLI5y3j1s0KESoC3f8nbkpYZnA",
     "language": "en"
    },
    {
     "unescapedUrl": "http://blogs.wsj.com/washwire/2010/03/19/sen-graham-immigration-will-be-casualty-of-health-bill/",
     "url": "http%3A%2F%2Fblogs.wsj.com%2Fwashwire%2F2010%2F03%2F19%2Fsen-graham-immigration-will-be-casualty-of-health-bill%2F",
     "title": "Sen. Graham: \u0026#39;Immigration Will Be Casualty of Health Bill\u0026#39;",
     "titleNoFormatting": "Sen. Graham: \u0026#39;Immigration Will Be Casualty of Health Bill\u0026#39;",
     "location": "",
     "publisher": "Wall Street Journal (blog)",
     "publishedDate": "Fri, 19 Mar 2010 14:00:12 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-0-4\u0026fd\u003dS\u0026url\u003dhttp://blogs.wsj.com/washwire/2010/03/19/sen-graham-immigration-will-be-casualty-of-health-bill/\u0026cid\u003d17593726372699\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNGD2kkQJD-PmwMk04MelzMJWMDySA",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.google.com/hostednews/ap/article/ALeqM5hrL7yuyUVclkim1xKb98eQ35qHxQD9EHA1780",
     "url": "http%3A%2F%2Fwww.google.com%2Fhostednews%2Fap%2Farticle%2FALeqM5hrL7yuyUVclkim1xKb98eQ35qHxQD9EHA1780",
     "title": "\u003cb\u003eObama\u003c/b\u003e backs senators immigration overhaul outline",
     "titleNoFormatting": "Obama backs senators immigration overhaul outline",
     "location": "",
     "publisher": "The Associated Press",
     "publishedDate": "Thu, 18 Mar 2010 15:19:43 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-0-5\u0026fd\u003dS\u0026url\u003dhttp://www.google.com/hostednews/ap/article/ALeqM5hrL7yuyUVclkim1xKb98eQ35qHxQD9EHA1780\u0026cid\u003d17593726372699\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNEPE-SDaHQkuQtaN8N5Yqiqyqf8Ng",
     "language": "en"
    },
    {
     "unescapedUrl": "http://rawstory.com/news/afp/US_health_overhaul_would_doom_immig_03192010.html",
     "url": "http%3A%2F%2Frawstory.com%2Fnews%2Fafp%2FUS_health_overhaul_would_doom_immig_03192010.html",
     "title": "US health overhaul would doom immigration plan: senator",
     "titleNoFormatting": "US health overhaul would doom immigration plan: senator",
     "location": "",
     "publisher": "Raw Story",
     "publishedDate": "Fri, 19 Mar 2010 13:59:41 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-0-6\u0026fd\u003dS\u0026url\u003dhttp://rawstory.com/news/afp/US_health_overhaul_would_doom_immig_03192010.html\u0026cid\u003d17593726372699\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNE0eh8KrbPhl3ikj9-_NL_CdGmtZg",
     "language": "en"
    }
   ]
  },
  {
   "GsearchResultClass": "GnewsSearch",
   "clusterUrl": "http://news.google.com/news/story?ncl\u003ddqqF9LoG7f1UpYMtbeIU6_12F9KTM\u0026hl\u003den\u0026ned\u003dus",
   "content": "President \u003cb\u003eBarack Obama\u003c/b\u003e would give federal authorities the power to block unreasonable rate hikes. President \u003cb\u003eBarack Obama\u003c/b\u003e delivers remarks on health \u003cb\u003e...\u003c/b\u003e",
   "unescapedUrl": "http://abcnews.go.com/Business/wireStory?id\u003d10150795",
   "url": "http%3A%2F%2Fabcnews.go.com%2FBusiness%2FwireStory%3Fid%3D10150795",
   "title": "Final Health Bill Omits Some of \u003cb\u003eObama\u0026#39;s\u003c/b\u003e Promises",
   "titleNoFormatting": "Final Health Bill Omits Some of Obama\u0026#39;s Promises",
   "location": "",
   "publisher": "ABC News",
   "publishedDate": "Fri, 19 Mar 2010 13:15:07 -0700",
   "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-1-0\u0026fd\u003dS\u0026url\u003dhttp://abcnews.go.com/Business/wireStory%3Fid%3D10150795\u0026cid\u003d17593727320867\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNHKi4kgGfSrGAWKxVKKv52pYYlMcw",
   "language": "en",
   "image": {
    "url": "http://a.abcnews.com/images/Politics/apg_obama_health_congress_100319_mn.jpg",
    "tbUrl": "http://nt0.ggpht.com/news/tbn/APcDaPD-2JsJ",
    "originalContextUrl": "http://abcnews.go.com/WN/monday-morning-state-americas-health-care-world-news/story?id\u003d10146233",
    "publisher": "ABC News",
    "tbWidth": 80,
    "tbHeight": 60
   },
   "relatedStories": [
    {
     "unescapedUrl": "http://www.reuters.com/article/idUSN1915103720100319",
     "url": "http%3A%2F%2Fwww.reuters.com%2Farticle%2FidUSN1915103720100319",
     "title": "\u003cb\u003eObama\u003c/b\u003e optimistic on weekend healthcare vote",
     "titleNoFormatting": "Obama optimistic on weekend healthcare vote",
     "location": "",
     "publisher": "Reuters",
     "publishedDate": "Fri, 19 Mar 2010 09:13:32 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-1-1\u0026fd\u003dS\u0026url\u003dhttp://www.reuters.com/article/idUSN1915103720100319\u0026cid\u003d17593727320867\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNH42J0Z1-UiaA_dfQmezghogxmIXA",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.washingtonpost.com/wp-dyn/content/article/2010/03/19/AR2010031900368.html",
     "url": "http%3A%2F%2Fwww.washingtonpost.com%2Fwp-dyn%2Fcontent%2Farticle%2F2010%2F03%2F19%2FAR2010031900368.html",
     "title": "\u003cb\u003eObama\u003c/b\u003e to Dems: Our fates are tied to health bill",
     "titleNoFormatting": "Obama to Dems: Our fates are tied to health bill",
     "location": "",
     "publisher": "Washington Post",
     "publishedDate": "Fri, 19 Mar 2010 00:50:48 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-1-2\u0026fd\u003dS\u0026url\u003dhttp://www.washingtonpost.com/wp-dyn/content/article/2010/03/19/AR2010031900368.html\u0026cid\u003d17593727320867\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNGXgOMBfyHiAPQ5pmNPJxzcDUa2Nw",
     "language": "en"
    },
    {
     "unescapedUrl": "http://news.bbc.co.uk/2/hi/americas/8577142.stm",
     "url": "http%3A%2F%2Fnews.bbc.co.uk%2F2%2Fhi%2Famericas%2F8577142.stm",
     "title": "\u003cb\u003eObama\u003c/b\u003e hails \u0026#39;historic\u0026#39; healthcare reform vote",
     "titleNoFormatting": "Obama hails \u0026#39;historic\u0026#39; healthcare reform vote",
     "location": "",
     "publisher": "BBC News",
     "publishedDate": "Fri, 19 Mar 2010 10:49:58 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-1-3\u0026fd\u003dS\u0026url\u003dhttp://news.bbc.co.uk/2/hi/americas/8577142.stm\u0026cid\u003d17593727320867\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNE98u__eD_Ku1Rob4qz_p1C156vVA",
     "language": "en"
    },
    {
     "unescapedUrl": "http://news.blogs.cnn.com/2010/03/19/obama-health-care-is-about-the-american-people/",
     "url": "http%3A%2F%2Fnews.blogs.cnn.com%2F2010%2F03%2F19%2Fobama-health-care-is-about-the-american-people%2F",
     "title": "\u003cb\u003eObama\u003c/b\u003e pushes \u0026#39;historic vote,\u0026#39; GOP leader vows to prevent it",
     "titleNoFormatting": "Obama pushes \u0026#39;historic vote,\u0026#39; GOP leader vows to prevent it",
     "location": "",
     "publisher": "CNN (blog)",
     "publishedDate": "Fri, 19 Mar 2010 08:39:00 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-1-4\u0026fd\u003dS\u0026url\u003dhttp://news.blogs.cnn.com/2010/03/19/obama-health-care-is-about-the-american-people/\u0026cid\u003d17593727320867\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNGJTqiFXdMfct93cTFZzAIhL2GcQw",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.businessweek.com/news/2010-03-19/obama-lobbies-for-support-as-health-care-vote-nears-update1-.html",
     "url": "http%3A%2F%2Fwww.businessweek.com%2Fnews%2F2010-03-19%2Fobama-lobbies-for-support-as-health-care-vote-nears-update1-.html",
     "title": "\u003cb\u003eObama\u003c/b\u003e Lobbies for Support as Health-Care Vote Nears",
     "titleNoFormatting": "Obama Lobbies for Support as Health-Care Vote Nears",
     "location": "",
     "publisher": "BusinessWeek",
     "publishedDate": "Fri, 19 Mar 2010 09:31:20 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-1-5\u0026fd\u003dS\u0026url\u003dhttp://www.businessweek.com/news/2010-03-19/obama-lobbies-for-support-as-health-care-vote-nears-update1-.html\u0026cid\u003d17593727320867\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNHGFwsgJO0JGRjFN4vRTWEKLG-wdQ",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.marketwatch.com/story/obama-to-push-health-care-bill-ahead-of-key-vote-2010-03-19",
     "url": "http%3A%2F%2Fwww.marketwatch.com%2Fstory%2Fobama-to-push-health-care-bill-ahead-of-key-vote-2010-03-19",
     "title": "\u003cb\u003eObama\u003c/b\u003e pushes health-care bill ahead of key vote",
     "titleNoFormatting": "Obama pushes health-care bill ahead of key vote",
     "location": "",
     "publisher": "MarketWatch",
     "publishedDate": "Fri, 19 Mar 2010 08:24:04 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-1-6\u0026fd\u003dS\u0026url\u003dhttp://www.marketwatch.com/story/obama-to-push-health-care-bill-ahead-of-key-vote-2010-03-19\u0026cid\u003d17593727320867\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNEULlTJZXUvDFVur2M2qPQsbiSaAg",
     "language": "en"
    }
   ]
  },
  {
   "GsearchResultClass": "GnewsSearch",
   "clusterUrl": "http://news.google.com/news/story?ncl\u003dd0m6ToHRyEIglNMIlaZxUpGcR2AyM\u0026hl\u003den\u0026ned\u003dus",
   "content": "A plan for the House Democratic caucus to meet with President \u003cb\u003eBarack Obama\u003c/b\u003e Saturday in the East Room of the White House has been changed. \u003cb\u003e...\u003c/b\u003e",
   "unescapedUrl": "http://blogs.wsj.com/washwire/2010/03/19/change-of-venue-obama-to-make-pitch-on-capitol-hill/",
   "url": "http%3A%2F%2Fblogs.wsj.com%2Fwashwire%2F2010%2F03%2F19%2Fchange-of-venue-obama-to-make-pitch-on-capitol-hill%2F",
   "title": "Change of Venue: \u003cb\u003eObama\u003c/b\u003e to Make Pitch on Capitol Hill",
   "titleNoFormatting": "Change of Venue: Obama to Make Pitch on Capitol Hill",
   "location": "",
   "publisher": "Wall Street Journal (blog)",
   "publishedDate": "Fri, 19 Mar 2010 14:12:26 -0700",
   "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-2-0\u0026fd\u003dS\u0026url\u003dhttp://blogs.wsj.com/washwire/2010/03/19/change-of-venue-obama-to-make-pitch-on-capitol-hill/\u0026cid\u003d17593728737966\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNHYCG9yd2OjQT0DsRuH39We1TSFEg",
   "language": "en",
   "image": {
    "url": "http://media.kansascity.com/smedia/2010/03/17/21/70-Obama.sff.embedded.prod_affiliate.81.jpg",
    "tbUrl": "http://nt3.ggpht.com/news/tbn/_xzIDlmLExwJ",
    "originalContextUrl": "http://www.kansascity.com/2010/03/17/1819341/obama-appears-on-fox-news-long.html",
    "publisher": "Kansas City Star",
    "tbWidth": 80,
    "tbHeight": 51
   },
   "relatedStories": [
    {
     "unescapedUrl": "http://www.washingtonpost.com/wp-dyn/content/article/2010/03/19/AR2010031901852.html",
     "url": "http%3A%2F%2Fwww.washingtonpost.com%2Fwp-dyn%2Fcontent%2Farticle%2F2010%2F03%2F19%2FAR2010031901852.html",
     "title": "\u003cb\u003eObama\u003c/b\u003e heads to Hill on Sat. as health vote looms",
     "titleNoFormatting": "Obama heads to Hill on Sat. as health vote looms",
     "location": "",
     "publisher": "Washington Post",
     "publishedDate": "Fri, 19 Mar 2010 10:51:52 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-2-1\u0026fd\u003dS\u0026url\u003dhttp://www.washingtonpost.com/wp-dyn/content/article/2010/03/19/AR2010031901852.html\u0026cid\u003d17593728737966\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNGVp5KnNU-N72GmwgwiT8RQjx27mg",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.nasdaq.com/aspx/stock-market-news-story.aspx?storyid\u003d201003191447dowjonesdjonline000600\u0026title\u003dus-house-demssenreid-to-meet-obama-at-white-house-saturday",
     "url": "http%3A%2F%2Fwww.nasdaq.com%2Faspx%2Fstock-market-news-story.aspx%3Fstoryid%3D201003191447dowjonesdjonline000600%26title%3Dus-house-demssenreid-to-meet-obama-at-white-house-saturday",
     "title": "US House Dems, Sen. Reid To Meet \u003cb\u003eObama\u003c/b\u003e At White House Saturday",
     "titleNoFormatting": "US House Dems, Sen. Reid To Meet Obama At White House Saturday",
     "location": "",
     "publisher": "NASDAQ",
     "publishedDate": "Fri, 19 Mar 2010 11:53:27 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-2-2\u0026fd\u003dS\u0026url\u003dhttp://www.nasdaq.com/aspx/stock-market-news-story.aspx%3Fstoryid%3D201003191447dowjonesdjonline000600%26title%3Dus-house-demssenreid-to-meet-obama-at-white-house-saturday\u0026cid\u003d17593728737966\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNGyKQTON6YOQaJ6MWjzCAX440tZnA",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.rollcall.com/news/44384-1.html",
     "url": "http%3A%2F%2Fwww.rollcall.com%2Fnews%2F44384-1.html",
     "title": "House Democratic Caucus Heading to Meet With \u003cb\u003eObama\u003c/b\u003e on Saturday",
     "titleNoFormatting": "House Democratic Caucus Heading to Meet With Obama on Saturday",
     "location": "",
     "publisher": "Roll Call (subscription)",
     "publishedDate": "Fri, 19 Mar 2010 11:04:53 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-2-3\u0026fd\u003dS\u0026url\u003dhttp://www.rollcall.com/news/44384-1.html\u0026cid\u003d17593728737966\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNECC4f4fcdCaVRRnJTMzNsyOfPVbg",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.upi.com/Top_News/US/2010/03/19/Obama-to-host-Mexican-President-Calderon/UPI-95231269011896/",
     "url": "http%3A%2F%2Fwww.upi.com%2FTop_News%2FUS%2F2010%2F03%2F19%2FObama-to-host-Mexican-President-Calderon%2FUPI-95231269011896%2F",
     "title": "\u003cb\u003eObama\u003c/b\u003e to host Mexican President Calderon",
     "titleNoFormatting": "Obama to host Mexican President Calderon",
     "location": "",
     "publisher": "UPI.com",
     "publishedDate": "Fri, 19 Mar 2010 08:19:57 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-2-4\u0026fd\u003dS\u0026url\u003dhttp://www.upi.com/Top_News/US/2010/03/19/Obama-to-host-Mexican-President-Calderon/UPI-95231269011896/\u0026cid\u003d17593728737966\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNEtqkK5hzFfCodXc8PyLF2FskqhhQ",
     "language": "en"
    },
    {
     "unescapedUrl": "http://blogs.abcnews.com/politicalpunch/2010/03/the-presidential-planner-12.html",
     "url": "http%3A%2F%2Fblogs.abcnews.com%2Fpoliticalpunch%2F2010%2F03%2Fthe-presidential-planner-12.html",
     "title": "The Presidential Planner",
     "titleNoFormatting": "The Presidential Planner",
     "location": "",
     "publisher": "ABC News (blog)",
     "publishedDate": "Fri, 19 Mar 2010 04:00:13 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-2-5\u0026fd\u003dS\u0026url\u003dhttp://blogs.abcnews.com/politicalpunch/2010/03/the-presidential-planner-12.html\u0026cid\u003d17593728737966\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNGrnJLP8sJQW3KJoCmmqmP4CqxK8Q",
     "language": "en"
    },
    {
     "unescapedUrl": "http://blog.taragana.com/business/2010/03/19/obama-bringing-democratic-lawmakers-to-white-house-saturday-on-eve-of-close-health-care-vote-43308/",
     "url": "http%3A%2F%2Fblog.taragana.com%2Fbusiness%2F2010%2F03%2F19%2Fobama-bringing-democratic-lawmakers-to-white-house-saturday-on-eve-of-close-health-care-vote-43308%2F",
     "title": "\u003cb\u003eObama\u003c/b\u003e bringing Democratic lawmakers to White House Saturday on eve of close \u003cb\u003e...\u003c/b\u003e",
     "titleNoFormatting": "Obama bringing Democratic lawmakers to White House Saturday on eve of close ...",
     "location": "",
     "publisher": "Gaea Times (blog)",
     "publishedDate": "Fri, 19 Mar 2010 11:41:44 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-2-6\u0026fd\u003dS\u0026url\u003dhttp://blog.taragana.com/business/2010/03/19/obama-bringing-democratic-lawmakers-to-white-house-saturday-on-eve-of-close-health-care-vote-43308/\u0026cid\u003d17593728737966\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNEJvCsacSoyX8KNPAzM9ywzsW9G4Q",
     "language": "en"
    }
   ]
  },
  {
   "GsearchResultClass": "GnewsSearch",
   "clusterUrl": "http://news.google.com/news/story?ncl\u003dduRPvRQcoSFkZJM-iRbrb68ddhq7M\u0026hl\u003den\u0026ned\u003dus",
   "content": "In Indonesia, the presidential spokesman says, \u0026quot;The delay of President \u003cb\u003eObama\u0026#39;s\u003c/b\u003e visit to Indonesia is related to urgent internal matters, so we understand. \u003cb\u003e...\u003c/b\u003e",
   "unescapedUrl": "http://www.salon.com/news/politics/war_room/2010/03/19/noonan_obama",
   "url": "http%3A%2F%2Fwww.salon.com%2Fnews%2Fpolitics%2Fwar_room%2F2010%2F03%2F19%2Fnoonan_obama",
   "title": "Peggy Noonan isn\u0026#39;t inviting \u003cb\u003eBarack Obama\u003c/b\u003e to her birthday party",
   "titleNoFormatting": "Peggy Noonan isn\u0026#39;t inviting Barack Obama to her birthday party",
   "location": "",
   "publisher": "Salon",
   "publishedDate": "Fri, 19 Mar 2010 12:31:21 -0700",
   "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-3-0\u0026fd\u003dS\u0026url\u003dhttp://www.salon.com/news/politics/war_room/2010/03/19/noonan_obama\u0026cid\u003d17593726360755\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNHVnR8zXqJDvEZupJD8v6pthiK3qQ",
   "language": "en",
   "image": {
    "url": "http://media.kansascity.com/smedia/2010/03/16/09/549-Obamas_Indonesia.sff.embedded.prod_affiliate.81.jpg",
    "tbUrl": "http://nt3.ggpht.com/news/tbn/g8RaEpHXxWUJ",
    "originalContextUrl": "http://www.kansascity.com/2010/03/15/1814641/obamas-asia-trip-more-about-influence.html",
    "publisher": "Kansas City Star",
    "tbWidth": 57,
    "tbHeight": 80
   },
   "relatedStories": [
    {
     "unescapedUrl": "http://www.csmonitor.com/World/Asia-Pacific/2010/0319/Indonesia-disappointed-after-Barack-Obama-delays-trip",
     "url": "http%3A%2F%2Fwww.csmonitor.com%2FWorld%2FAsia-Pacific%2F2010%2F0319%2FIndonesia-disappointed-after-Barack-Obama-delays-trip",
     "title": "Indonesia disappointed after \u003cb\u003eBarack Obama\u003c/b\u003e delays trip",
     "titleNoFormatting": "Indonesia disappointed after Barack Obama delays trip",
     "location": "",
     "publisher": "Christian Science Monitor",
     "publishedDate": "Fri, 19 Mar 2010 08:54:46 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-3-1\u0026fd\u003dS\u0026url\u003dhttp://www.csmonitor.com/World/Asia-Pacific/2010/0319/Indonesia-disappointed-after-Barack-Obama-delays-trip\u0026cid\u003d17593726360755\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNHTo1eRxUOVRiupTXTLP6OIQqT1WQ",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.reuters.com/article/idUSTRE62H3PL20100319",
     "url": "http%3A%2F%2Fwww.reuters.com%2Farticle%2FidUSTRE62H3PL20100319",
     "title": "Indonesia says understands \u003cb\u003eObama\u003c/b\u003e trip delay",
     "titleNoFormatting": "Indonesia says understands Obama trip delay",
     "location": "",
     "publisher": "Reuters",
     "publishedDate": "Fri, 19 Mar 2010 01:16:29 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-3-2\u0026fd\u003dS\u0026url\u003dhttp://www.reuters.com/article/idUSTRE62H3PL20100319\u0026cid\u003d17593726360755\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNGCAjJesHBIKwA5OQBdTZXHxFvquw",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.latimes.com/news/nationworld/politics/wire/sns-ap-us-obama-indonesia,0,23439.story",
     "url": "http%3A%2F%2Fwww.latimes.com%2Fnews%2Fnationworld%2Fpolitics%2Fwire%2Fsns-ap-us-obama-indonesia%2C0%2C23439.story",
     "title": "His trip put off by health care debate, \u003cb\u003eObama\u003c/b\u003e assures Indonesians he will \u003cb\u003e...\u003c/b\u003e",
     "titleNoFormatting": "His trip put off by health care debate, Obama assures Indonesians he will ...",
     "location": "",
     "publisher": "Los Angeles Times",
     "publishedDate": "Thu, 18 Mar 2010 22:06:24 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-3-3\u0026fd\u003dS\u0026url\u003dhttp://www.latimes.com/news/nationworld/politics/wire/sns-ap-us-obama-indonesia,0,23439.story\u0026cid\u003d17593726360755\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNGlRYDZNbmOrBhJmpb02piX-sbSNw",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www.straitstimes.com/BreakingNews/SEAsia/Story/STIStory_504385.html",
     "url": "http%3A%2F%2Fwww.straitstimes.com%2FBreakingNews%2FSEAsia%2FStory%2FSTIStory_504385.html",
     "title": "\u003cb\u003eObama\u003c/b\u003e risks losing chance to build ties",
     "titleNoFormatting": "Obama risks losing chance to build ties",
     "location": "",
     "publisher": "Straits Times",
     "publishedDate": "Fri, 19 Mar 2010 14:50:04 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-3-4\u0026fd\u003dS\u0026url\u003dhttp://www.straitstimes.com/BreakingNews/SEAsia/Story/STIStory_504385.html\u0026cid\u003d17593726360755\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNFq5F12HCwwg_BFs0eNqFaZWMH7Pw",
     "language": "en"
    },
    {
     "unescapedUrl": "http://www1.voanews.com/english/news/asia/Indonesians-React-to-Postponement-of-US-Presidents-Trip-With-Disappointment-Support-88541577.html",
     "url": "http%3A%2F%2Fwww1.voanews.com%2Fenglish%2Fnews%2Fasia%2FIndonesians-React-to-Postponement-of-US-Presidents-Trip-With-Disappointment-Support-88541577.html",
     "title": "Indonesians React to Postponement of \u003cb\u003eObama\u0026#39;s\u003c/b\u003e Trip With Disappointment, Support",
     "titleNoFormatting": "Indonesians React to Postponement of Obama\u0026#39;s Trip With Disappointment, Support",
     "location": "",
     "publisher": "Voice of America",
     "publishedDate": "Fri, 19 Mar 2010 04:59:17 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-3-5\u0026fd\u003dS\u0026url\u003dhttp://www1.voanews.com/english/news/asia/Indonesians-React-to-Postponement-of-US-Presidents-Trip-With-Disappointment-Support-88541577.html\u0026cid\u003d17593726360755\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNG4YczK9pc_LhHtL0yTRDWzikWZEw",
     "language": "en"
    },
    {
     "unescapedUrl": "http://english.ntdtv.com/ntdtv_en/ns_asia/2010-03-19/761757247967.html",
     "url": "http%3A%2F%2Fenglish.ntdtv.com%2Fntdtv_en%2Fns_asia%2F2010-03-19%2F761757247967.html",
     "title": "\u003cb\u003eObama\u003c/b\u003e Delays Trip to Indonesia",
     "titleNoFormatting": "Obama Delays Trip to Indonesia",
     "location": "",
     "publisher": "NTDTV",
     "publishedDate": "Fri, 19 Mar 2010 10:23:14 -0700",
     "signedRedirectUrl": "http://news.google.com/news/url?sa\u003dT\u0026ct\u003dus/0-3-6\u0026fd\u003dS\u0026url\u003dhttp://english.ntdtv.com/ntdtv_en/ns_asia/2010-03-19/761757247967.html\u0026cid\u003d17593726360755\u0026ei\u003dE_ejS_CcBoqQrQOwv8qgAw\u0026usg\u003dAFQjCNHDyzocNKHbLDg4WamlTfdYcUh2Dg",
     "language": "en"
    }
   ]
  }
 ],
 "cursor": {
  "pages": [
   {
    "start": "0",
    "label": 1
   },
   {
    "start": "4",
    "label": 2
   },
   {
    "start": "8",
    "label": 3
   },
   {
    "start": "12",
    "label": 4
   },
   {
    "start": "16",
    "label": 5
   },
   {
    "start": "20",
    "label": 6
   },
   {
    "start": "24",
    "label": 7
   },
   {
    "start": "28",
    "label": 8
   }
  ],
  "estimatedResultCount": "176523",
  "currentPageIndex": 0,
  "moreResultsUrl": "http://news.google.com/nwshp?oe\u003dutf8\u0026ie\u003dutf8\u0026source\u003duds\u0026q\u003dBarack+Obama\u0026hl\u003den\u0026start\u003d0"
 }
}
, "responseDetails": null, "responseStatus": 200}

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.

curl -e http://www.my-ajax-site.com \
'https://ajax.googleapis.com/ajax/services/search/news?v=1.0&q=barack%20obama&callback=processResults'

This command performs a News 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.

processResults({"responseData": {
  "results": [
    ...            // results array
   ]
}});

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.

curl -e http://www.your-site-here.com \
'https://ajax.googleapis.com/ajax/services/search/news?v=1.0& \
q=barack%20obama&callback=processResults&context=foo'

This command performs a News 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 News 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 News Search API is made available through the JSON API.

Using Flash

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

Note: This example works for Flex and AIR. For Flash, please use HTTP Client for AS3.

var service:HTTPService = new HTTPService();
service.url = 'https://ajax.googleapis.com/ajax/services/search/news';
service.request.v = '1.0';
service.request.q = 'barack%20obama';
service.resultFormat = 'text';
service.addEventListener(ResultEvent.RESULT, onServerResponse);

// Make sure to set 'allowScriptAccess' to 'sameDomain' or 'always' in your
// HTML include and import flash.external.ExternalInterface in this AS file.
if (ExternalInterface.available) {
try {
  service.headers['Referer'] = ExternalInterface.call("window.location.href.toString");
} catch (ignored:Error) {
  service.headers['Referer'] = "http://www.example.com";
}
}

service.addEventListener(ResultEvent.RESULT, onServerResponse);
service.send();

private function onServerResponse(event:ResultEvent):void {
  try {
    var json:Object = JSON.decode(event.result as String);
    // now have some fun with the results...
  } catch(ignored:Error) {
  }
}

Using Java

The following code snippet shows how to make a request to the Google News Search API using Java. This example uses the JSON library from json.org.

URL url = new URL("https://ajax.googleapis.com/ajax/services/search/news?" +
                  "v=1.0&q=barack%20obama&userip=INSERT-USER-IP");
URLConnection connection = url.openConnection();
connection.addRequestProperty("Referer", /* Enter the URL of your site here */);

String line;
StringBuilder builder = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
while((line = reader.readLine()) != null) {
 builder.append(line);
}

JSONObject json = new JSONObject(builder.toString());
// now have some fun with the results...

Using PHP

The following code snippet shows how to make a request to the Google News Search API using PHP. This sample assumes PHP 5.2. For older installations of PHP, refer to this comment.

$url = "https://ajax.googleapis.com/ajax/services/search/news?" .
       "v=1.0&q=barack%20obama&userip=INSERT-USER-IP";

// sendRequest
// note how referer is set manually
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_REFERER, /* Enter the URL of your site here */);
$body = curl_exec($ch);
curl_close($ch);

// now, process the JSON string
$json = json_decode($body);
// now have some fun with the results...

Using Python

The following code snippet shows how to make a request to the Google News Search API using Python. This sample assumes Python 2.4 or higher. You may need to download and install simplejson.

import urllib2
import simplejson

url = ('https://ajax.googleapis.com/ajax/services/search/news?' +
       'v=1.0&q=barack%20obama&userip=INSERT-USER-IP')

request = urllib2.Request(url, None, {'Referer': /* Enter the URL of your site here */})
response = urllib2.urlopen(request)

# Process the JSON string.
results = simplejson.load(response)
# now have some fun with the results...

Using Perl

The following code snippet shows how to make a request to the Google News 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.

#!/usr/bin/perl

my $url = "https://ajax.googleapis.com/ajax/services/search/news?" +
          "v=1.0&q=barack%20obama&userip=INSERT-USER-IP";

# Load our modules
# Please note that you MUST have LWP::UserAgent and JSON installed to use this
# You can get both from CPAN.
use LWP::UserAgent;
use JSON;

# Initialize the UserAgent object and send the request.
# Notice that referer is set manually to a URL string.
my $ua = LWP::UserAgent->new();
$ua->default_header("HTTP_REFERER" => /* Enter the URL of your site here */);
my $body = $ua->get($url);

# process the json string
my $json = from_json($body->decoded_content);

# have some fun with the results
my $i = 0;
foreach my $result (@{$json->{responseData}->{results}}){
 $i++;
 print $i.". " . $result->{titleNoFormatting} . "(" . $result->{url} . ")\n";
 # etc....
}
if(!$i){
 print "Sorry, but there were no results.\n";
}

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 News Search API is:

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

URL arguments

This section describes the arguments that can be used for News 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=barack%20obama

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

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.

callbackFunction(
  {"responseData" : {
      "results" : [],
      "cursor" : {}
    },
    "responseDetails" : null | string-on-error,
    "responseStatus" : 200 | error-code
});

context

context=bar

This argument is related to the callback argument. When both are supplied, the value of context alters the normal response format associated with callback. The new format is:

callbackFunction(
  contextValue,    // the context arg value
  responseObject,  // the collection of results and cursor
  responseStatus,  // 200 on success, non-200 on failure
  errorDetails)    // error string for non-200 response

hl

hl=fr

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.

ned

ned=us

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.

rsz

rsz=4

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

scoring

scoring=d

This optional argument tells the News Search system to order results by date instead of the default ordering by relevance.

To order results by date, specify scoring=d.

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:

"cursor": {
  "pages": [[
    { "start": "0", "label": 1 },
    { "start": "4", "label": 2 },
    { "start": "8", "label": 3 },
    { "start": "12","label": 4 } ]],
  "estimatedResultCount": "48758",
  "currentPageIndex": 0,
  "moreResultsUrl": "http://www.google.com/search..."
}

topic

topic=h

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

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

userip

userip=192.168.0.1

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:

{
  "responseData" : {
    "results" : [],
    "cursor" : {}
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
}

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

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

clusterUrl

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.

content

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

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

GsearchResultClass

Indicates the type of result (for example, google.search.NewsSearch.RESULT_CLASS indicates GnewsResult).

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

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

// attach the node into my dom
container.appendChild(node);

image{}

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.

language

This optional property indicates the language of the news story.

location

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

publishedDate

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

publisher

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

relatedStories

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[]

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

title

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

titleNoFormatting

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

unescapedUrl

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

http://www.informationweek.com/news/software/
open_source/showArticle.jhtml?articleID\u003d223900277

url

Provides an encoded URL. For example:

http%3A%2F%2Fwww.informationweek.com%2Fnews%2Fsoftware%2
    Fopen_source%2FshowArticle.jhtml%3FarticleID%3D223900277.

The responseStatus property contains a value of 200 on success and a non-200 HTTP error status code on failure. If there is a failure, responseDetails contains a diagnostic string.

Callback argument

Applications can use the callback argument as follows to request a JavaScript callback.

callback({
  "responseData" : {
    "results" : [],
    "cursor" : {}
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
});

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.
  • The response status is passed as the third argument.
  • The final argument is either null or a diagnostic string.
processResults(for',{
 "results": [[
  {
   ...
  },
  {
   ...
  },
  ...
 ]],
 "cursor": {
  "pages": [[
   ...
  ]],
  "estimatedResultCount": "n",
  "currentPageIndex": n,
  "moreResultsUrl": "..."
 }
}
, 200 | error-code, null | string-on-error)

Troubleshooting

If you encounter problems with your code:

  • Look for typos. Remember that JavaScript is a case-sensitive language.
  • Use a JavaScript debugger. In Firefox, you can use the JavaScript console or the Firebug. In IE, you can use the Microsoft Script Debugger.
  • If you need to examine the JSON string returned from the server, you can use JSON Lint to make a single, long string human readable.
  • Search the API 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.