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.

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.

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.

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.

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.

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:

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.

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:

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.

Load feed

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.