Return to Google homepage

Developer's Guide

Calendar data API Terms and Conditions

Related Links

Google Data APIs (Beta) Developer's Guide

Google Data APIs Overview

The Google data APIs ("GData" for short) provide a simple standard protocol for reading and writing data on the web. GData combines common XML-based syndication formats (Atom and RSS) with a feed-publishing system based on the Atom publishing protocol, plus some extensions for handling queries.

Contents

Background: Atom and RSS

There are two common XML-based syndication formats for feeds and other data interchange on the web: Atom and RSS. RSS has been around longer, in various versions; Atom is more recent but has more features.

In addition to its syndication format, Atom provides a publishing protocol; it's an HTTP-based protocol for publishing and editing web resources. (The Atom publishing protocol specification isn't yet complete; it's an emerging standard, currently under development by the IETF.) For example, using the Atom publishing protocol, you can send a GET request to request a particular resource (such as a feed or entry); the server returns a representation of that resource in the Atom syndication format. Or you can create, edit, or delete a resource, using POST, PUT, or DELETE, respectively. This use of HTTP requests for a publishing and editing protocol is in the spirit of the REST approach to web service interfaces.

In various contexts, it's useful to be able to send a query to a server and receive a response containing a list of matching results. Neither Atom nor RSS provides a way to do that, but GData does.

About GData

GData is a new protocol based on Atom 1.0 and RSS 2.0.

To acquire information from a service that supports GData, you send an HTTP GET request; the service returns results as an Atom or RSS feed.

You can update data (where supported by a particular GData service) by sending an HTTP PUT request, an approach based on the Atom Publishing Protocol.

All sorts of services can provide GData feeds, from public services like blog feeds or news syndication feeds to personalized data like email or calendar events or task-list items. The RSS and Atom models are extensible, so each feed provider can define its own extensions and semantics as desired. A feed provider can provide read-only feeds (such as a search-results feed) or read/write feeds (such as a calendar application).

For example, a blogging application might provide a feed for each blog, and a comment feed for each blog entry. A calendar application might allow you to send full-text search queries using the GData protocol, and return results in the GData syndication format.

Because GData is built on basic technologies—HTTP and common syndication models—you can send GData requests and process the resulting feeds in a variety of ways: traditional syndication aggregators/feed readers, JavaScript/AJAX-based clients in a web browser, standalone applications, or any other approach you like. The GData protocol is language-neutral; you can write a client in any programming language that lets you issue HTTP requests and parse XML-based responses.

Creating and deleting a feed is left up to the service; the GData protocol does not provide ways to create or delete a feed.

The following table lists GData features and indicates whether they're available in other related technologies. For more information about these features, see the Protocol document.

Feature GData Atom* RSS 2.0
Syndication Format Y Y Y
Queries Y N N
Updates Y Y N
Optimistic Concurrency Y N N
Authentication Y N N

* The "Atom" column refers to both the syndication format and the publication protocol.

Motivation: Why GData?

Google's mission is to organize the world's information and make it universally accessible and useful. Sometimes making information accessible requires making it available in contexts other than a web browser. Thus, Google provides APIs to let client software request information outside of a browser context.

GData provides a general model for feeds, queries, and results. You can use it to send queries and updates to any service that has a GData interface.

Syndication is an effective and popular method for providing and aggregating content. GData provides a way to expand the types of content that Google can make available through syndication; in particular, it lets you use the syndication mechanism to send queries and receive query results. GData also lets you send data to Google, and update data that Google already has.

Last modified: