Google Feed API

JSON Developer's Guide for the Google Feed API

You can use the Google Feed JSON interface to write feed applications in any language that can handle a JSON-encoded result set with embedded status codes.

Contents

  1. Audience
  2. Application requirements
  3. Using the JSON interface
    1. Sending a basic query
      1. Find feed
      2. Load feed
    2. Using the callback argument
      1. Find feed
      2. Load feed
    3. Using the context argument
      1. Find feed
      2. Load feed
  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 addresses
        2. URL arguments
          1. Required URL arguments
          2. Optional URL arguments
  1. JSON reference, cont.
    1. Result objects
      1. Basic
      2. JSON
      3. XML
      4. Mixed
      5. FindResult
    2. Response format
      1. Basic query
        1. Find feed
        2. Load feed
      2. Callback argument
        1. Find feed
        2. Load feed
      3. Context argument
        1. Find feed
        2. Load feed
  2. Troubleshooting

Audience

The Google Feed JSON interface, and this guide, are provided for Flash developers, and all other developers who need to access the Feed API 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.

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

We highly encourage you to include 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.

This section describes how to send basic queries using both Find Feed and Load Feed. The following table lists the base URLs for these searchers.

Searcher Base Url Explanation
Find Feed https://ajax.googleapis.com/ajax/services/feed/find Searches for feeds based on keywords supplied as the query argument.
Load Feed https://ajax.googleapis.com/ajax/services/feed/load Searches for feeds based on a feed URL supplied as the query argument.

Sending a basic query

The following examples use the curl command line tool to return feed results for queries relevant to the find feed and load feed methods, respectively.

Find feed

Command
curl -e http://www.my-ajax-site.com \
'https://ajax.googleapis.com/ajax/services/feed/find?v=1.0&q=Official%20Google%20Blogs'
Result
{
    "responseData": {
        "query": "Official Google Blogs",
        "entries": [
            {
                "url": "http://googleblog.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eOfficial Google Blog\u003c/b\u003e",
                "contentSnippet": "Jun 24, 2010 \u003cb\u003e...\u003c/b\u003e \u003cb\u003eOfficial\u003c/b\u003e weblog, with news of new products, events and glimpses of life inside \u003cbr\u003e  \u003cb\u003eGoogle\u003c/b\u003e.",
                "link": "http://googleblog.blogspot.com/"
            },
            {
                "url": "http://googlepress.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eGoogle Blog\u003c/b\u003e Directory",
                "contentSnippet": "\u003cb\u003eGoogle Blog\u003c/b\u003e Directory About our \u003cb\u003eblogs\u003c/b\u003e. Whether it\u0026#39;s a product or feature launch \u003cbr\u003e  or a cool new \u003cb\u003e...\u003c/b\u003e \u003cb\u003eBlogs\u003c/b\u003e by Category. \u003cb\u003eGoogle\u003c/b\u003e-wide. Products. Ads. Developer \u003cb\u003e...\u003c/b\u003e",
                "link": "http://www.google.com/press/blogs/directory.html"
            },
            {
                "url": "http://blog.google.org/feeds/posts/default",
                "title": "\u003cb\u003eOfficial google\u003c/b\u003e.org \u003cb\u003eBlog\u003c/b\u003e",
                "contentSnippet": "We will keep posting updates to the \u003cb\u003eGoogle\u003c/b\u003e China \u003cb\u003eblog\u003c/b\u003e as more information and \u003cbr\u003e  tools become available. Please visit this page for updated resources. \u003cb\u003e...\u003c/b\u003e",
                "link": "http://blog.google.org/"
            },
            {
                "url": "http://blog.google.org/feeds/posts/default",
                "title": "\u003cb\u003eOfficial google\u003c/b\u003e.org \u003cb\u003eBlog\u003c/b\u003e: Seeing the forest through the cloud",
                "contentSnippet": "Dec 10, 2009 \u003cb\u003e...\u003c/b\u003e For example, in \u003cb\u003eGoogle\u003c/b\u003e Earth today, you can fly to Rondonia, Brazil and easily \u003cbr\u003e  observe the advancement of deforestation over time, \u003cb\u003e...\u003c/b\u003e",
                "link": "http://blog.google.org/2009/12/seeing-forest-through-cloud.html"
            },
            {
                "url": "http://googlewebmastercentral.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eOfficial Google\u003c/b\u003e Webmaster Central \u003cb\u003eBlog\u003c/b\u003e",
                "contentSnippet": "Jun 21, 2010 \u003cb\u003e...\u003c/b\u003e The \u003cb\u003eofficial\u003c/b\u003e weblog on \u003cb\u003eGoogle\u003c/b\u003e crawling and indexing, and on webmaster tools, \u003cbr\u003e  including the Sitemaps facility.",
                "link": "http://googlewebmastercentral.blogspot.com/"
            },
            {
                "url": "http://googledocs.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eOfficial Google\u003c/b\u003e Docs \u003cb\u003eBlog\u003c/b\u003e",
                "contentSnippet": "Jun 17, 2010 \u003cb\u003e...\u003c/b\u003e Labels: \u003cb\u003eGoogle\u003c/b\u003e Apps \u003cb\u003eBlog\u003c/b\u003e, sharing. The ability to share my \u003cb\u003eGoogle\u003c/b\u003e Docs is \u003cbr\u003e  crucial to my productivity. My teammates and I often add comments \u003cb\u003e...\u003c/b\u003e",
                "link": "http://googledocs.blogspot.com/"
            },
            {
                "url": "http://blogoscoped.com/rss.xml",
                "title": "\u003cb\u003eGoogle\u0026#39;s Blogs\u003c/b\u003e \u0026#39;n More",
                "contentSnippet": "Below posts are mostly from the corporate blogs by Google, Yahoo and Microsoft. \u003cbr\u003e  You can also \u0026gt;\u0026gt; Search \u003cb\u003eofficial Google blogs\u003c/b\u003e. \u003cb\u003e...\u003c/b\u003e",
                "link": "http://blogoscoped.com/google/"
            },
            {
                "url": "http://googlereader.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eOfficial Google\u003c/b\u003e Reader \u003cb\u003eBlog\u003c/b\u003e",
                "contentSnippet": "Last year we announced that we wanted to hear your wish list for features in \u003cbr\u003e  \u003cb\u003eGoogle\u003c/b\u003e Reader, and one of most highly requested features was the ability to \u003cb\u003e...\u003c/b\u003e",
                "link": "http://googlereader.blogspot.com/"
            },
            {
                "url": "http://analytics.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eGoogle\u003c/b\u003e Analytics \u003cb\u003eBlog\u003c/b\u003e",
                "contentSnippet": "\u003cb\u003eOfficial\u003c/b\u003e weblog offering news, tips and resources related to \u003cb\u003eGoogle\u0026#39;s\u003c/b\u003e web \u003cbr\u003e  traffic analytics service.",
                "link": "http://analytics.blogspot.com/"
            },
            {
                "url": "http://feeds.feedburner.com/search-engines-news",
                "title": "\u003cb\u003eOfficial Google\u0026#39;s Blogs\u003c/b\u003e List",
                "contentSnippet": "Oct 24, 2005 \u003cb\u003e...\u003c/b\u003e \u003cb\u003eOfficial Google\u0026#39;s Blogs\u003c/b\u003e List - Search Engines News.",
                "link": "http://www.prweaver.com/blog/2005/10/24/180-official-google-blogs-list"
            }
        ]
    },
    "responseDetails": null,
    "responseStatus": 200
}

Load feed

Command
curl -e http://www.my-ajax-site.com \
'https://ajax.googleapis.com/ajax/services/feed/load?v=1.0&q=http://www.digg.com/rss/index.xml'
Result
{
    "responseData": {
        "feed": {
            "feedUrl": "http://www.digg.com/rss/index.xml",
            "title": "digg.com: Stories / Popular",
            "link": "http://digg.com/",
            "author": "",
            "description": "digg.com: Stories / Popular",
            "type": "rss20",
            "entries": [
                {
                    "mediaGroups": [
                        {
                            "contents": [
                                {
                                    "url": "http://digg.com/security/Devil_Is_In_The_Details_DHS_Monitoring_Web_Wrong_Words/t.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 80,
                                    "width": 80
                                },
                                {
                                    "url": "http://digg.com/security/Devil_Is_In_The_Details_DHS_Monitoring_Web_Wrong_Words/a.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 30,
                                    "width": 30
                                },
                                {
                                    "url": "http://digg.com/security/Devil_Is_In_The_Details_DHS_Monitoring_Web_Wrong_Words/s.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "isDefault": "true",
                                    "height": 48,
                                    "width": 48
                                },
                                {
                                    "url": "http://digg.com/security/Devil_Is_In_The_Details_DHS_Monitoring_Web_Wrong_Words/m.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 120,
                                    "width": 120
                                },
                                {
                                    "url": "http://digg.com/security/Devil_Is_In_The_Details_DHS_Monitoring_Web_Wrong_Words/l.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 160,
                                    "width": 160
                                },
                                {
                                    "url": "http://digg.com/security/Devil_Is_In_The_Details_DHS_Monitoring_Web_Wrong_Words/p.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 43,
                                    "width": 80
                                }
                            ]
                        }
                    ],
                    "title": "Devil Is In The Details: DHS Monitoring Web \u0026 \"Wrong\" Words",
                    "link": "http://feeds.digg.com/~r/digg/popular/~3/UVxtFC251dA/Devil_Is_In_The_Details_DHS_Monitoring_Web_Wrong_Words",
                    "author": "",
                    "publishedDate": "Fri, 25 Jun 2010 15:10:02 -0700",
                    "contentSnippet": "DHS will monitor more U.S. citizens on the Internet, the feds may have the power to pull the plug on the Web, and certain words ...",
                    "content": "DHS will monitor more U.S. citizens on the Internet, the feds may have the power to pull the plug on the Web, and certain words automatically incriminate you if used in emails. It's been a busy week, eroding away at privacy. The devil in the details of censorship.\u003cp\u003e\u003c/p\u003e\u003cimg src\u003d\"http://feeds.feedburner.com/~r/digg/popular/~4/UVxtFC251dA\" height\u003d\"1\" width\u003d\"1\"\u003e",
                    "categories": [
                    ]
                },
                {
                    "title": "iPhone 4 screen yellowing could be a temporary problem",
                    "link": "http://feeds.digg.com/~r/digg/popular/~3/We-jE7E4pNk/iPhone_4_screen_yellowing_could_be_a_temporary_problem",
                    "author": "",
                    "publishedDate": "Fri, 25 Jun 2010 15:00:03 -0700",
                    "contentSnippet": "New iPhone 4 devices plagued with a yellow discoloration of the screen could be the result of a temporary problem that will ...",
                    "content": "New iPhone 4 devices plagued with a yellow discoloration of the screen could be the result of a temporary problem that will alleviate itself in a matter of days.\u003cimg src\u003d\"http://feeds.feedburner.com/~r/digg/popular/~4/We-jE7E4pNk\" height\u003d\"1\" width\u003d\"1\"\u003e",
                    "categories": [
                    ]
                },
                {
                    "mediaGroups": [
                        {
                            "contents": [
                                {
                                    "url": "http://digg.com/pets_animals/She_has_no_clue_that_I_am_down_here_Tee_hee_Pic/t.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 80,
                                    "width": 80
                                },
                                {
                                    "url": "http://digg.com/pets_animals/She_has_no_clue_that_I_am_down_here_Tee_hee_Pic/a.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 30,
                                    "width": 30
                                },
                                {
                                    "url": "http://digg.com/pets_animals/She_has_no_clue_that_I_am_down_here_Tee_hee_Pic/s.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "isDefault": "true",
                                    "height": 48,
                                    "width": 48
                                },
                                {
                                    "url": "http://digg.com/pets_animals/She_has_no_clue_that_I_am_down_here_Tee_hee_Pic/m.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 120,
                                    "width": 120
                                },
                                {
                                    "url": "http://digg.com/pets_animals/She_has_no_clue_that_I_am_down_here_Tee_hee_Pic/l.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 160,
                                    "width": 160
                                },
                                {
                                    "url": "http://digg.com/pets_animals/She_has_no_clue_that_I_am_down_here_Tee_hee_Pic/p.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 60,
                                    "width": 80
                                }
                            ]
                        }
                    ],
                    "title": "She has no clue that I am down here. Tee hee! [Pic]",
                    "link": "http://feeds.digg.com/~r/digg/popular/~3/sfR7jDm-D-Q/She_has_no_clue_that_I_am_down_here_Tee_hee_Pic",
                    "author": "",
                    "publishedDate": "Fri, 25 Jun 2010 14:50:02 -0700",
                    "contentSnippet": "Green Sea Turtle in Hawaii.",
                    "content": "Green Sea Turtle in Hawaii.\u003cimg src\u003d\"http://feeds.feedburner.com/~r/digg/popular/~4/sfR7jDm-D-Q\" height\u003d\"1\" width\u003d\"1\"\u003e",
                    "categories": [
                    ]
                },
                {
                    "mediaGroups": [
                        {
                            "contents": [
                                {
                                    "url": "http://digg.com/design/Someone_Finally_Built_a_Better_Mousetrap/t.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 80,
                                    "width": 80
                                },
                                {
                                    "url": "http://digg.com/design/Someone_Finally_Built_a_Better_Mousetrap/a.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 30,
                                    "width": 30
                                },
                                {
                                    "url": "http://digg.com/design/Someone_Finally_Built_a_Better_Mousetrap/s.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "isDefault": "true",
                                    "height": 48,
                                    "width": 48
                                },
                                {
                                    "url": "http://digg.com/design/Someone_Finally_Built_a_Better_Mousetrap/m.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 120,
                                    "width": 120
                                },
                                {
                                    "url": "http://digg.com/design/Someone_Finally_Built_a_Better_Mousetrap/l.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 160,
                                    "width": 160
                                },
                                {
                                    "url": "http://digg.com/design/Someone_Finally_Built_a_Better_Mousetrap/p.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 46,
                                    "width": 80
                                }
                            ]
                        }
                    ],
                    "title": "Someone Finally Built a Better Mousetrap",
                    "link": "http://feeds.digg.com/~r/digg/popular/~3/crtWcK5m9xY/Someone_Finally_Built_a_Better_Mousetrap",
                    "author": "",
                    "publishedDate": "Fri, 25 Jun 2010 14:40:03 -0700",
                    "contentSnippet": "One of the most loved design products at this year’s International Design Excellence Awards was the OneDown mousetrap, which ...",
                    "content": "One of the most loved design products at this year’s International Design Excellence Awards was the OneDown mousetrap, which swings upright from horizontal due to a rodent’s own weight, to clearly indicate that it has been trapped.\u003cp\u003e\u003c/p\u003e\u003cimg src\u003d\"http://feeds.feedburner.com/~r/digg/popular/~4/crtWcK5m9xY\" height\u003d\"1\" width\u003d\"1\"\u003e",
                    "categories": [
                    ]
                }
            ]
        }
    },
    "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, which directs the API to deliver the JSON object as an argument to the specified callback.

Below, you will find examples of how to use the callback argument for both find feed and load feed. This command supplies a relevant query, as in the basic example, except that it has been altered to pass callback. With this argument in place, the API returns a JavaScript call in the response and passes the JSON object via the results parameter.

Find feed

Command
curl -e http://www.my-ajax-site.com \
'https://ajax.googleapis.com/ajax/services/feed/find?v=1.0&q=Official%20Google%20Blogs&callback=processResults'
Result
processResults({
    "responseData": {
        "query": "Official Google Blog",
        "entries": [
            {
                "url": "http://googleblog.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eOfficial Google Blog\u003c/b\u003e",
                "contentSnippet": "Jun 24, 2010 \u003cb\u003e...\u003c/b\u003e \u003cb\u003eOfficial\u003c/b\u003e weblog, with news of new products, events and glimpses of life inside \u003cbr\u003e  \u003cb\u003eGoogle\u003c/b\u003e.",
                "link": "http://googleblog.blogspot.com/"
            },
            {
                "url": "http://googleblog.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eOfficial Google Blog\u003c/b\u003e: Our new search index: Caffeine",
                "contentSnippet": "Jun 8, 2010 \u003cb\u003e...\u003c/b\u003e skip to main | skip to sidebar. The \u003cb\u003eOfficial Google Blog\u003c/b\u003e - Insights from \u003cbr\u003e  Googlers into our products, technology and the Google \u003cb\u003e...\u003c/b\u003e",
                "link": "http://googleblog.blogspot.com/2010/06/our-new-search-index-caffeine.html"
            },
            {
                "url": "http://googlemobile.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eOfficial Google\u003c/b\u003e Mobile \u003cb\u003eBlog\u003c/b\u003e",
                "contentSnippet": "Jun 10, 2010 \u003cb\u003e...\u003c/b\u003e News, features and tips from the \u003cb\u003eGoogle\u003c/b\u003e Mobile team.",
                "link": "http://googlemobile.blogspot.com/"
            },
            {
                "url": "http://googlewebmastercentral.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eOfficial Google\u003c/b\u003e Webmaster Central \u003cb\u003eBlog\u003c/b\u003e",
                "contentSnippet": "Jun 21, 2010 \u003cb\u003e...\u003c/b\u003e The \u003cb\u003eofficial\u003c/b\u003e weblog on \u003cb\u003eGoogle\u003c/b\u003e crawling and indexing, and on webmaster tools, \u003cbr\u003e  including the Sitemaps facility.",
                "link": "http://googlewebmastercentral.blogspot.com/"
            },
            {
                "url": "http://blog.google.org/feeds/posts/default",
                "title": "\u003cb\u003eOfficial google\u003c/b\u003e.org \u003cb\u003eBlog\u003c/b\u003e",
                "contentSnippet": "We will keep posting updates to the \u003cb\u003eGoogle\u003c/b\u003e China \u003cb\u003eblog\u003c/b\u003e as more information and \u003cbr\u003e  tools become available. Please visit this page for updated resources. \u003cb\u003e...\u003c/b\u003e",
                "link": "http://blog.google.org/"
            },
            {
                "url": "http://blog.google.org/feeds/posts/default",
                "title": "\u003cb\u003eOfficial google\u003c/b\u003e.org \u003cb\u003eBlog\u003c/b\u003e: Seeing the forest through the cloud",
                "contentSnippet": "Dec 10, 2009 \u003cb\u003e...\u003c/b\u003e For example, in \u003cb\u003eGoogle\u003c/b\u003e Earth today, you can fly to Rondonia, Brazil and easily \u003cbr\u003e  observe the advancement of deforestation over time, \u003cb\u003e...\u003c/b\u003e",
                "link": "http://blog.google.org/2009/12/seeing-forest-through-cloud.html"
            },
            {
                "url": "http://googledocs.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eOfficial Google\u003c/b\u003e Docs \u003cb\u003eBlog\u003c/b\u003e",
                "contentSnippet": "Jun 17, 2010 \u003cb\u003e...\u003c/b\u003e Labels: \u003cb\u003eGoogle\u003c/b\u003e Apps \u003cb\u003eBlog\u003c/b\u003e, sharing. The ability to share my \u003cb\u003eGoogle\u003c/b\u003e Docs is \u003cbr\u003e  crucial to my productivity. My teammates and I often add comments \u003cb\u003e...\u003c/b\u003e",
                "link": "http://googledocs.blogspot.com/"
            },
            {
                "url": "http://analytics.blogspot.com/feeds/posts/default",
                "title": "\u003cb\u003eGoogle\u003c/b\u003e Analytics \u003cb\u003eBlog\u003c/b\u003e",
                "contentSnippet": "\u003cb\u003eOfficial\u003c/b\u003e weblog offering news, tips and resources related to \u003cb\u003eGoogle\u0026#39;s\u003c/b\u003e web \u003cbr\u003e  traffic analytics service.",
                "link": "http://analytics.blogspot.com/"
            },
            {
                "url": "http://feeds.searchengineland.com/searchengineland",
                "title": "Baidu: The \u003cb\u003eOfficial Google Blog\u003c/b\u003e You Seek Does Not Exist (\u0026amp; Don\u0026#39;t \u003cb\u003e...\u003c/b\u003e",
                "contentSnippet": "Jan 13, 2010 \u003cb\u003e...\u003c/b\u003e Looking for the \u003cb\u003eofficial Google blog\u003c/b\u003e post about Google deciding to to leave \u003cbr\u003e  China over censorship? Don\u0026#39;t try finding it on China\u0026#39;s leading \u003cb\u003e...\u003c/b\u003e",
                "link": "http://searchengineland.com/baidu-the-official-google-blog-you-seek-does-not-exist-33490"
            },
            {
                "url": "http://www.resourceshelf.com/feed/",
                "title": "\u003cb\u003eOfficial Google Blog\u003c/b\u003e Looks at Search Trends from the Winter \u003cb\u003e...\u003c/b\u003e",
                "contentSnippet": "Mar 2, 2010 \u003cb\u003e...\u003c/b\u003e \u003cb\u003eOfficial Google Blog\u003c/b\u003e Looks at Search Trends from the Winter Olympics. An \u003cbr\u003e  interesting post from Google today about how and when people \u003cb\u003e...\u003c/b\u003e",
                "link": "http://www.resourceshelf.com/2010/03/02/the-official-google-blog-looks-at-search-trends-and-the-winter-olympics/"
            }
        ]
    },
    "responseDetails": null,
    "responseStatus": 200
})

Load feed

Command
curl -e http://www.my-ajax-site.com \
'https://ajax.googleapis.com/ajax/services/feed/load?v=1.0&q=http%3A//api.flickr.com/services/feeds/photos_public.gne%3Fid%3D17472213@N00%26lang%3Den-us%26format%3Drss_200&v=1.0&callback=processResults'
Result
processResults({
    "responseData": {
        "feed": {
            "feedUrl": "http://www.digg.com/rss/index.xml",
            "title": "digg.com: Stories / Popular",
            "link": "http://digg.com/",
            "author": "",
            "description": "digg.com: Stories / Popular",
            "type": "rss20",
            "entries": [
                {
                    "mediaGroups": [
                        {
                            "contents": [
                                {
                                    "url": "http://digg.com/xbox/New_Crysis_2_screens_will_literally_make_jaws_drop/t.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 80,
                                    "width": 80
                                },
                                {
                                    "url": "http://digg.com/xbox/New_Crysis_2_screens_will_literally_make_jaws_drop/a.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 30,
                                    "width": 30
                                },
                                {
                                    "url": "http://digg.com/xbox/New_Crysis_2_screens_will_literally_make_jaws_drop/s.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "isDefault": "true",
                                    "height": 48,
                                    "width": 48
                                },
                                {
                                    "url": "http://digg.com/xbox/New_Crysis_2_screens_will_literally_make_jaws_drop/m.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 120,
                                    "width": 120
                                },
                                {
                                    "url": "http://digg.com/xbox/New_Crysis_2_screens_will_literally_make_jaws_drop/l.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 160,
                                    "width": 160
                                },
                                {
                                    "url": "http://digg.com/xbox/New_Crysis_2_screens_will_literally_make_jaws_drop/p.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 44,
                                    "width": 80
                                }
                            ]
                        }
                    ],
                    "title": "New Crysis 2 screens will literally make jaws drop",
                    "link": "http://feeds.digg.com/~r/digg/popular/~3/oSLM8LMKdRs/New_Crysis_2_screens_will_literally_make_jaws_drop",
                    "author": "",
                    "publishedDate": "Fri, 25 Jun 2010 15:50:02 -0700",
                    "contentSnippet": "Crytek have released a new batch of screens from Crysis 2. Check them out, they are hot!",
                    "content": "Crytek have released a new batch of screens from Crysis 2. Check them out, they are hot!\u003cp\u003e\u003c/p\u003e\u003cimg src\u003d\"http://feeds.feedburner.com/~r/digg/popular/~4/oSLM8LMKdRs\" height\u003d\"1\" width\u003d\"1\"\u003e",
                    "categories": [
                    ]
                },
                {
                    "mediaGroups": [
                        {
                            "contents": [
                                {
                                    "url": "http://digg.com/politics/Philadelphia_can_t_evict_Boy_Scouts_for_banning_gays/t.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 80,
                                    "width": 80
                                },
                                {
                                    "url": "http://digg.com/politics/Philadelphia_can_t_evict_Boy_Scouts_for_banning_gays/a.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 30,
                                    "width": 30
                                },
                                {
                                    "url": "http://digg.com/politics/Philadelphia_can_t_evict_Boy_Scouts_for_banning_gays/s.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "isDefault": "true",
                                    "height": 48,
                                    "width": 48
                                },
                                {
                                    "url": "http://digg.com/politics/Philadelphia_can_t_evict_Boy_Scouts_for_banning_gays/m.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 120,
                                    "width": 120
                                },
                                {
                                    "url": "http://digg.com/politics/Philadelphia_can_t_evict_Boy_Scouts_for_banning_gays/l.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 160,
                                    "width": 160
                                },
                                {
                                    "url": "http://digg.com/politics/Philadelphia_can_t_evict_Boy_Scouts_for_banning_gays/p.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 61,
                                    "width": 80
                                }
                            ]
                        }
                    ],
                    "title": "Philadelphia can't evict Boy Scouts for banning gays",
                    "link": "http://feeds.digg.com/~r/digg/popular/~3/OnZ5wPErNHg/Philadelphia_can_t_evict_Boy_Scouts_for_banning_gays",
                    "author": "",
                    "publishedDate": "Fri, 25 Jun 2010 15:40:02 -0700",
                    "contentSnippet": "A federal jury has ruled that Philadelphia cannot evict a Boy Scout chapter from city-owned property because the Scouts ban ...",
                    "content": "A federal jury has ruled that Philadelphia cannot evict a Boy Scout chapter from city-owned property because the Scouts ban gays. The jury found the city's demand that Scouts end their ban on gays in order to use city property violated the Scout council's First Amendment rights. The city is reviewing further legal challenges to the Scouts' gay ban.\u003cimg src\u003d\"http://feeds.feedburner.com/~r/digg/popular/~4/OnZ5wPErNHg\" height\u003d\"1\" width\u003d\"1\"\u003e",
                    "categories": [
                    ]
                },
                {
                    "mediaGroups": [
                        {
                            "contents": [
                                {
                                    "url": "http://digg.com/comedy/What_Your_Awful_Font_Choices_Say_About_You_CHART/t.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 80,
                                    "width": 80
                                },
                                {
                                    "url": "http://digg.com/comedy/What_Your_Awful_Font_Choices_Say_About_You_CHART/a.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 30,
                                    "width": 30
                                },
                                {
                                    "url": "http://digg.com/comedy/What_Your_Awful_Font_Choices_Say_About_You_CHART/s.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "isDefault": "true",
                                    "height": 48,
                                    "width": 48
                                },
                                {
                                    "url": "http://digg.com/comedy/What_Your_Awful_Font_Choices_Say_About_You_CHART/m.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 120,
                                    "width": 120
                                },
                                {
                                    "url": "http://digg.com/comedy/What_Your_Awful_Font_Choices_Say_About_You_CHART/l.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 160,
                                    "width": 160
                                },
                                {
                                    "url": "http://digg.com/comedy/What_Your_Awful_Font_Choices_Say_About_You_CHART/p.jpg",
                                    "type": "image/jpeg",
                                    "medium": "image",
                                    "height": 80,
                                    "width": 80
                                }
                            ]
                        }
                    ],
                    "title": "What Your Awful Font Choices Say About You [CHART]",
                    "link": "http://feeds.digg.com/~r/digg/popular/~3/bfTRliEtfn8/What_Your_Awful_Font_Choices_Say_About_You_CHART",
                    "author": "",
                    "publishedDate": "Fri, 25 Jun 2010 15:31:53 -0700",
                    "contentSnippet": "If graphic design was a religion, fonts are its priests - some are brilliant and enhance your understanding of the text and ...",
                    "content": "If graphic design was a religion, fonts are its priests - some are brilliant and enhance your understanding of the text and others are, well ... best avoided.\u003cimg src\u003d\"http://feeds.feedburner.com/~r/digg/popular/~4/bfTRliEtfn8\" height\u003d\"1\" width\u003d\"1\"\u003e",
                    "categories": [
                    ]
                },
                {
                    "title": "The Most Disgusting Tongue You'll See All Day",
                    "link": "http://feeds.digg.com/~r/digg/popular/~3/oubDHx5ML3U/The_Most_Disgusting_Tongue_You_ll_See_All_Day",
                    "author": "",
                    "publishedDate": "Fri, 25 Jun 2010 15:20:03 -0700",
                    "contentSnippet": "Man, I'm thirsty, but I seem to have lost my appetite. Saharan Tongue sucks.",
                    "content": "Man, I'm thirsty, but I seem to have lost my appetite. Saharan Tongue sucks.\u003cp\u003e\u003c/p\u003e\u003cimg src\u003d\"http://feeds.feedburner.com/~r/digg/popular/~4/oubDHx5ML3U\" height\u003d\"1\" width\u003d\"1\"\u003e",
                    "categories": [

                    ]
                }
            ]
        }
    },
    "responseDetails": null,
    "responseStatus": 200
})

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.

The following curl commands searches for feeds as in the previous example, but in this case it passes both callback and context arguments. With these arguments in place, the API returns a JavaScript call and the JSON object is passed via the results parameter.

Find feed

Command
curl -e http://www.my-ajax-site.com \
'https://ajax.googleapis.com/ajax/services/feed/find?v=1.0&q=Official%20Google%20Blogs&callback=processResults&context=foo
Result
processResults('foo',
{
    "query": "Official Google Blogs",
    "entries": [
        {
            "url": "http://googleblog.blogspot.com/feeds/posts/default",
            "title": "\u003cb\u003eOfficial Google Blog\u003c/b\u003e",
            "contentSnippet": "Jun 24, 2010 \u003cb\u003e...\u003c/b\u003e \u003cb\u003eOfficial\u003c/b\u003e weblog, with news of new products, events and glimpses of life inside \u003cbr\u003e  \u003cb\u003eGoogle\u003c/b\u003e.",
            "link": "http://googleblog.blogspot.com/"
        },
        {
            "url": "http://googleblog.blogspot.com/feeds/posts/default",
            "title": "\u003cb\u003eOfficial Google Blog\u003c/b\u003e: A new approach to China",
            "contentSnippet": "Jan 12, 2010 \u003cb\u003e...\u003c/b\u003e skip to main | skip to sidebar. The \u003cb\u003eOfficial Google Blog\u003c/b\u003e - Insights from \u003cbr\u003e  Googlers into our products, technology and the Google \u003cb\u003e...\u003c/b\u003e",
            "link": "http://googleblog.blogspot.com/2010/01/new-approach-to-china.html"
        },
        {
            "url": "http://googlepress.blogspot.com/feeds/posts/default",
            "title": "\u003cb\u003eGoogle Blog\u003c/b\u003e Directory",
            "contentSnippet": "\u003cb\u003eGoogle Blog\u003c/b\u003e Directory About our \u003cb\u003eblogs\u003c/b\u003e. Whether it\u0026#39;s a product or feature launch \u003cbr\u003e  or a cool new \u003cb\u003e...\u003c/b\u003e \u003cb\u003eBlogs\u003c/b\u003e by Category. \u003cb\u003eGoogle\u003c/b\u003e-wide. Products. Ads. Developer \u003cb\u003e...\u003c/b\u003e",
            "link": "http://www.google.com/press/blogs/directory.html"
        },
        {
            "url": "http://googlemobile.blogspot.com/feeds/posts/default",
            "title": "\u003cb\u003eOfficial Google\u003c/b\u003e Mobile \u003cb\u003eBlog\u003c/b\u003e",
            "contentSnippet": "Jun 10, 2010 \u003cb\u003e...\u003c/b\u003e News, features and tips from the \u003cb\u003eGoogle\u003c/b\u003e Mobile team.",
            "link": "http://googlemobile.blogspot.com/"
        },
        {
            "url": "http://blog.google.org/feeds/posts/default",
            "title": "\u003cb\u003eOfficial google\u003c/b\u003e.org \u003cb\u003eBlog\u003c/b\u003e",
            "contentSnippet": "We will keep posting updates to the \u003cb\u003eGoogle\u003c/b\u003e China \u003cb\u003eblog\u003c/b\u003e as more information and \u003cbr\u003e  tools become available. Please visit this page for updated resources. \u003cb\u003e...\u003c/b\u003e",
            "link": "http://blog.google.org/"
        },
        {
            "url": "http://blog.google.org/feeds/posts/default",
            "title": "\u003cb\u003eOfficial google\u003c/b\u003e.org \u003cb\u003eBlog\u003c/b\u003e: Seeing the forest through the cloud",
            "contentSnippet": "Dec 10, 2009 \u003cb\u003e...\u003c/b\u003e For example, in \u003cb\u003eGoogle\u003c/b\u003e Earth today, you can fly to Rondonia, Brazil and easily \u003cbr\u003e  observe the advancement of deforestation over time, \u003cb\u003e...\u003c/b\u003e",
            "link": "http://blog.google.org/2009/12/seeing-forest-through-cloud.html"
        },
        {
            "url": "http://blogoscoped.com/rss.xml",
            "title": "\u003cb\u003eGoogle\u0026#39;s Blogs\u003c/b\u003e \u0026#39;n More",
            "contentSnippet": "Below posts are mostly from the corporate blogs by Google, Yahoo and Microsoft. \u003cbr\u003e  You can also \u0026gt;\u0026gt; Search \u003cb\u003eofficial Google blogs\u003c/b\u003e. \u003cb\u003e...\u003c/b\u003e",
            "link": "http://blogoscoped.com/google/"
        },
        {
            "url": "http://googlewebmastercentral.blogspot.com/feeds/posts/default",
            "title": "\u003cb\u003eOfficial Google\u003c/b\u003e Webmaster Central \u003cb\u003eBlog\u003c/b\u003e",
            "contentSnippet": "Jun 21, 2010 \u003cb\u003e...\u003c/b\u003e The \u003cb\u003eofficial\u003c/b\u003e weblog on \u003cb\u003eGoogle\u003c/b\u003e crawling and indexing, and on webmaster tools, \u003cbr\u003e  including the Sitemaps facility.",
            "link": "http://googlewebmastercentral.blogspot.com/"
        },
        {
            "url": "http://googlemac.blogspot.com/feeds/posts/default",
            "title": "\u003cb\u003eOfficial Google\u003c/b\u003e Mac \u003cb\u003eBlog\u003c/b\u003e",
            "contentSnippet": "Jun 13, 2010 \u003cb\u003e...\u003c/b\u003e The \u003cb\u003eofficial\u003c/b\u003e weblog about \u003cb\u003eGoogle\u003c/b\u003e in the Apple Macintosh world.",
            "link": "http://googlemac.blogspot.com/"
        },
        {
            "url": "http://googledocs.blogspot.com/feeds/posts/default",
            "title": "\u003cb\u003eOfficial Google\u003c/b\u003e Docs \u003cb\u003eBlog\u003c/b\u003e",
            "contentSnippet": "Jun 17, 2010 \u003cb\u003e...\u003c/b\u003e Labels: \u003cb\u003eGoogle\u003c/b\u003e Apps \u003cb\u003eBlog\u003c/b\u003e, sharing. The ability to share my \u003cb\u003eGoogle\u003c/b\u003e Docs is \u003cbr\u003e  crucial to my productivity. My teammates and I often add comments \u003cb\u003e...\u003c/b\u003e",
            "link": "http://googledocs.blogspot.com/"
        }
    ]
},
200,
null,
200)

Load feed

Command
curl -e http://www.my-ajax-site.com \
'https://ajax.googleapis.com/ajax/services/feed/load?v=1.0&q=http%3A//api.flickr.com/services/feeds/photos_public.gne%3Fid%3D17472213@N00%26lang%3Den-us%26format%3Drss_200&v=1.0&callback=processResults&context=foo'
Result
processResults('foo',
{
    "feed": {
        "feedUrl": "http://api.flickr.com/services/feeds/photos_public.gne?id\u003d17472213@N00\u0026lang\u003den-us\u0026format\u003drss_200",
        "title": "Uploads from -wiktor-",
        "link": "http://www.flickr.com/photos/-wiktor-/",
        "author": "",
        "description": "",
        "type": "rss20",
        "entries": [
            {
                "mediaGroups": [
                    {
                        "contents": [
                            {
                                "url": "http://farm5.static.flickr.com/4070/4614027764_0341aeeda5_o.jpg",
                                "type": "image/jpeg",
                                "height": 1584,
                                "width": 2376,
                                "title": "SF bay view",
                                "thumbnails": [
                                    {
                                        "height": 75,
                                        "width": 75,
                                        "url": "http://farm5.static.flickr.com/4070/4614027764_0e2bd93600_s.jpg"
                                    }
                                ],
                                "categories": [
                                    {
                                        "scheme": "urn:flickr:tags",
                                        "content": "sf sanfrancisco bay"
                                    }
                                ],
                                "credits": [
                                    {
                                        "role": "photographer",
                                        "content": "-wiktor-"
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "title": "SF bay view",
                "link": "http://www.flickr.com/photos/-wiktor-/4614027764/",
                "author": "nobody@flickr.com (-wiktor-)",
                "publishedDate": "Sun, 16 May 2010 18:55:38 -0700",
                "contentSnippet": "-wiktor- posted a photo:\n\t\n",
                "content": "\u003cp\u003e\u003ca href\u003d\"http://www.flickr.com/people/-wiktor-/\"\u003e-wiktor-\u003c/a\u003e posted a photo:\u003c/p\u003e\n\t\n\u003cp\u003e\u003ca href\u003d\"http://www.flickr.com/photos/-wiktor-/4614027764/\" title\u003d\"SF bay view\"\u003e\u003cimg src\u003d\"http://farm5.static.flickr.com/4070/4614027764_0e2bd93600_m.jpg\" width\u003d\"240\" height\u003d\"160\" alt\u003d\"SF bay view\"\u003e\u003c/a\u003e\u003c/p\u003e",
                "categories": [
                ]
            },
            {
                "mediaGroups": [
                    {
                        "contents": [
                            {
                                "url": "http://farm4.static.flickr.com/3357/4614027540_3169687324_o.jpg",
                                "type": "image/jpeg",
                                "height": 1584,
                                "width": 2376,
                                "title": "Definition of casual",
                                "thumbnails": [
                                    {
                                        "height": 75,
                                        "width": 75,
                                        "url": "http://farm4.static.flickr.com/3357/4614027540_b34283534c_s.jpg"
                                    }
                                ],
                                "categories": [
                                    {
                                        "scheme": "urn:flickr:tags",
                                        "content": "relax cafe casual"
                                    }
                                ],
                                "credits": [
                                    {
                                        "role": "photographer",
                                        "content": "-wiktor-"
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "title": "Definition of casual",
                "link": "http://www.flickr.com/photos/-wiktor-/4614027540/",
                "author": "nobody@flickr.com (-wiktor-)",
                "publishedDate": "Sun, 16 May 2010 18:55:34 -0700",
                "contentSnippet": "-wiktor- posted a photo:\n\t\n",
                "content": "\u003cp\u003e\u003ca href\u003d\"http://www.flickr.com/people/-wiktor-/\"\u003e-wiktor-\u003c/a\u003e posted a photo:\u003c/p\u003e\n\t\n\u003cp\u003e\u003ca href\u003d\"http://www.flickr.com/photos/-wiktor-/4614027540/\" title\u003d\"Definition of casual\"\u003e\u003cimg src\u003d\"http://farm4.static.flickr.com/3357/4614027540_b34283534c_m.jpg\" width\u003d\"240\" height\u003d\"160\" alt\u003d\"Definition of casual\"\u003e\u003c/a\u003e\u003c/p\u003e",
                "categories": [
                ]
            },
            {
                "mediaGroups": [
                    {
                        "contents": [
                            {
                                "url": "http://farm4.static.flickr.com/3371/4613409659_cb357ae3cc_o.jpg",
                                "type": "image/jpeg",
                                "height": 800,
                                "width": 600,
                                "title": "Cafe full of geeks",
                                "thumbnails": [
                                    {
                                        "height": 75,
                                        "width": 75,
                                        "url": "http://farm4.static.flickr.com/3371/4613409659_ae2bd0bd6c_s.jpg"
                                    }
                                ],
                                "categories": [
                                    {
                                        "scheme": "urn:flickr:tags",
                                        "content": "cafe geek laptop"
                                    }
                                ],
                                "credits": [
                                    {
                                        "role": "photographer",
                                        "content": "-wiktor-"
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "title": "Cafe full of geeks",
                "link": "http://www.flickr.com/photos/-wiktor-/4613409659/",
                "author": "nobody@flickr.com (-wiktor-)",
                "publishedDate": "Sun, 16 May 2010 18:55:29 -0700",
                "contentSnippet": "-wiktor- posted a photo:\n\t\n",
                "content": "\u003cp\u003e\u003ca href\u003d\"http://www.flickr.com/people/-wiktor-/\"\u003e-wiktor-\u003c/a\u003e posted a photo:\u003c/p\u003e\n\t\n\u003cp\u003e\u003ca href\u003d\"http://www.flickr.com/photos/-wiktor-/4613409659/\" title\u003d\"Cafe full of geeks\"\u003e\u003cimg src\u003d\"http://farm4.static.flickr.com/3371/4613409659_ae2bd0bd6c_m.jpg\" width\u003d\"180\" height\u003d\"240\" alt\u003d\"Cafe full of geeks\"\u003e\u003c/a\u003e\u003c/p\u003e",
                "categories": [
                ]
            },
            {
                "mediaGroups": [
                    {
                        "contents": [
                            {
                                "url": "http://farm3.static.flickr.com/2676/4145232664_9a883ffe8e_o.jpg",
                                "type": "image/jpeg",
                                "height": 683,
                                "width": 1024,
                                "title": "Christmas Stitches loves muffins",
                                "thumbnails": [
                                    {
                                        "height": 75,
                                        "width": 75,
                                        "url": "http://farm3.static.flickr.com/2676/4145232664_4bf3ac7787_s.jpg"
                                    }
                                ],
                                "categories": [
                                    {
                                        "scheme": "urn:flickr:tags",
                                        "content": "christmas xmas cupcake muffin stich"
                                    }
                                ],
                                "credits": [
                                    {
                                        "role": "photographer",
                                        "content": "-wiktor-"
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "title": "Christmas Stitches loves muffins",
                "link": "http://www.flickr.com/photos/-wiktor-/4145232664/",
                "author": "nobody@flickr.com (-wiktor-)",
                "publishedDate": "Sun, 29 Nov 2009 14:00:59 -0800",
                "contentSnippet": "-wiktor- posted a photo:\n\t\n",
                "content": "\u003cp\u003e\u003ca href\u003d\"http://www.flickr.com/people/-wiktor-/\"\u003e-wiktor-\u003c/a\u003e posted a photo:\u003c/p\u003e\n\t\n\u003cp\u003e\u003ca href\u003d\"http://www.flickr.com/photos/-wiktor-/4145232664/\" title\u003d\"Christmas Stitches loves muffins\"\u003e\u003cimg src\u003d\"http://farm3.static.flickr.com/2676/4145232664_4bf3ac7787_m.jpg\" width\u003d\"240\" height\u003d\"160\" alt\u003d\"Christmas Stitches loves muffins\"\u003e\u003c/a\u003e\u003c/p\u003e",
                "categories": [
                ]
            }
        ]
    }
},
200,
null,
200)

Code Examples

The following sections contain code snippets that show how to access the find feed API from Flash, Java, PHP, Python, and Perl. You can access the load feed API simply by changing the URL parameter from /find to /load.

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 Feed API is made available through the JSON API.

Using Flash

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

var service:HTTPService = new HTTPService();
service.url = 'https://ajax.googleapis.com/ajax/services/feed/find';
service.request.v = '1.0';
service.request.q = 'Official%20Google%20Blog';
service.resultFormat = 'text';
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 Feed API using Java. This example uses the JSON library from json.org.

URL url = new URL("https://ajax.googleapis.com/ajax/services/feed/find?" +
                  "v=1.0&q=Official%20Google%20Blog&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 Feed 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/feed/find?" .
       "v=1.0&q=Official%20Google%20Blog&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 Feed 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/feed/find?' +
       'v=1.0&q=Official%20Google%20Blog&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 Feed 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/feed/find?" +
          "v=1.0&q=Official%20Google%20Blog&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

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 addresses

The standard URLs for the Google Feed API are:

https://ajax.googleapis.com/ajax/services/feed/find

https://ajax.googleapis.com/ajax/services/feed/load

URL arguments

This section describes the arguments that can be used for Feed 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=Official%20Google%20Blog

This argument supplies the query:

  • For find feed, the query consists of keywords.
  • For load feed, the query consists of a URL.

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

In addition to the required URL arguments listed above, you can use the following, optional arguments in both find feed and load feed.

Argument Example Description
callback callback=foo This optional 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.
foo({
    "responseData": {
        "language": "es",
        "isReliable": false,
        "confidence": 0.14400463
    },
    "responseDetails": null,
    "responseStatus": 200
})
context context=bar This optional 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 method result
  responseStatus,  // 200 on success, non-200 on failure
  errorDetails)    // error string for non-200 response
      
hl hl=fr 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.
num num=100 Applicable to load feed only. This optional argument supplies the number of entries to load from the feed specified by q. A value of -1 indicates the maximum number of entries supported, currently 100. By default, load feed returns four results.
output output=json Applicable to load feed only. This optional argument determines the output format for the responseData property.
  • json is the default value and returns JSON-only output.
  • json_xml returns the JSON representation of the feed along with a new xmlString property containing the XML representation of the feed in string form.
  • xml returns Only the xmlString property, and does not return the JSON representation of the feed. The xmlString property contains the XML representation of the feed in string form.
scoring scoring=h Applicable to load feed only. By default, when a feed is loaded, the system returns a cached copy of the specified feed that is 100% in sync with the feed contents at the time that it was cached. The only value this parameter takes is h, and setting this value instructs the system to return any additional historical entries that it might have in its cache.
userip userip=192.168.0.1 This argument supplies the IP address of the end-user on whose behalf the request is being made. Google is less likely to mistake requests for abuse when they include userip. 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.

Result objects

Basic

The .load() method calls the function argument with a single result when the feed download completes. The result has the following structure:

  • <root>
    • error?
      Present if there was an error loading the feed.
    • xmlDocument?
      The feed XML document. Present for the XML_FORMAT and MIXED_FORMAT result formats. See the XML documentation below.
    • feed?
      The JSON representation of the feed. Present for the JSON_FORMAT and MIXED_FORMAT result formats. See the JSON documentation below.

JSON

If you request the google.feeds.Feed.JSON_FORMAT result format, the feed attribute appears in the feed result. It corresponds to the json value for the output argument in JSON. The feed attribute has the following structure:

  • feed
    • feedUrl
      The URL for the feed.

      Note: This API uses URL normalization to standardize feed URLs. Therefore, the API does not always return the same URL that you supplied. The context parameter allows you to distinguish between multiple feed load requests.

    • title
      The feed title. Corresponds to the <title> element in Atom and the <title> element in RSS.
    • link
      The URL for the HTML version of the feed. Corresponds to the <link> element in Atom and the <link> element in RSS.
    • description
      The feed description. Corresponds to the <subtitle> element in Atom and the <description> element in RSS.
    • author
      The feed author. Corresponds to the <name> element for the author in Atom.
    • entries[]
      A list of all of the entries in the feed. Corresponds to the <entry> element in Atom and the <item> element in RSS.
      • mediaGroup
        A container for Media RSS feed results. All result properties nested under mediaGroups correspond exactly as documented in the Media RSS Specification. Media RSS is available only for feed entries newer than February 1st, 2010. Please refer to that specification for detailed information about Media RSS fields.
      • title
        The entry title. Corresponds to the <title> element in Atom and the <title> element in RSS.
      • link
        The URL for the HTML version of the entry. Corresponds to the <link> element in Atom and the <link> element in RSS.
      • content
        The body of this entry, inlcuding HTML tags. Since this value can contain HTML tags, you should display this value using elem.innerHTML = entry.content (as opposed to using document.createTextNode). Corresponds to the <content> or <summary> elements in Atom and the <description> element in RSS.
      • contentSnippet
        A snippet (< 120 characters) version of the content attribute. The snippet does not contain any HTML tags.
      • publishedDate
        The string date on which the entry was published of the form "13 Apr 2007 12:40:07 -0700". You can parse the date with new Date(entry.publishedDate). Corresponds to the <published> element in Atom and the <pubDate> element in RSS.
      • categories[]
        A list of string tags for the entry. Corresponds to the term attribute for the <category> element in Atom and the <category> element in RSS.

XML

If you request the google.feeds.Feed.XML_FORMAT result format, the API places the xmlDocument attribute in the feed result. This attribute is the fully parsed XML Document node for the feed. It corresponds to the xml value for the output argument in JSON. You can access the document using the XML functionality built into browsers (e.g., getElementsByTagName).

Mixed

If you request the google.feeds.Feed.MIXED_FORMAT result format, the API places both the feed JSON attribute and the xmlDocument XML DOM attribute in the feed result. It corresponds to the json_xml value for the output argument in JSON. See the JSON result format and XML result format for details.

In addition to those attributes, every entry in the JSON results array contains an additional xmlNode property. That property is a pointer to the XML Element representing that entry in the feed XML document. For an ATOM feed, xmlNode points to the <entry> element for the entry. For an RSS feed, xmlNode points to the <item> element for the entry.

FindResult

The findFeeds() method calls the callback function argument with a single result when the feed query completes. The result has the following structure:

  • <root>
    • error?
      Present if there was an error loading the feed.
    • entries[]
      A list typically containing up to ten feeds that matched the given query string.
      • title
        The feed title.
      • link
        The URL for the HTML version of the feed.
      • contentSnippet
        A snippet (< 120 characters) version of the content.
      • url
        The URL for the actual feed.

Response format

Basic query

There are two major variations in the response format, present both in find feed and load feed. When the callback and context arguments are not supplied, the response format is a simple JSON objects shown below.

In the JSON objects below, note that the responseData property contains method-specific properties that are identical to the properties available in the JavaScript binding. For additional information, please review the Result Objects.

Note that the responseStatus and responseDetails properties contain a value of 200 on success and a non-200 http error status code on failure. If the call fails, you can dfiagnose the failure via the diagnostic string following responseDetails.

Find feed

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

Load feed

{
  "responseData" : {
    "feed" : {}
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
}

Callback argument

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

Find feed

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

Load feed

callback({
  "responseData" : {
    "feed" : {}
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
})

Context argument

If you wish to use the context argument, you always need to include the callback argument as well. 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.

Find feed

callback('foo',{
  "responseData" : {
    "query" : query-string,
    "entries" : []
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
}

Load feed

callback('foo',{
  "responseData" : {
    "feed" : {}
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
})

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.