Using the JavaScript Client Library (v2.0)

Warning: This page is about Google's older APIs, the Google Data APIs; it's relevant only to the APIs that are listed in the Google Data APIs directory, many of which have been replaced with newer APIs. For information about a specific new API, see the new API's documentation. For information about authorizing requests with a newer API, see Google Accounts Authentication and Authorization.

This document describes how to use the JavaScript client library to send Google Data API queries and interpret returned responses.

Google provides a set of client libraries, in a variety of programming languages, for interacting with services that have data APIs. Using these libraries, you can construct API requests, send them to a service, and receive responses.

This document provides some general information about using the JavaScript client library, along with a set of examples of common uses.

Audience

This document is intended for JavaScript programmers who want to write client applications that can interact with Google Data services.

This document assumes that you understand the general ideas behind the Google Data APIs protocol. It also assumes that you know how to program in JavaScript.

For reference information about the classes and methods provided by the client library, see the JavaScript client library API reference (in JSdoc format).

This document is designed to be read in order; each example builds on earlier examples.

Terms of use

You agree to abide by the Google JavaScript Client Library Terms of Use when using the JavaScript client library.

Data model and control flow overview

The JavaScript client library uses a set of classes to represent the elements used by the Google Data APIs.

Note: The underlying representation of the data is JSON, but the client library provides an abstraction layer so you don't have to work with the JSON data directly. If you want to work directly with JSON, without the client library, see Using JSON with Google Data APIs.

The library provides methods that let you asynchronously send data to and receive data from a service that has a data API. For example, the google.gdata.calendar.CalendarService.getEventsFeed() method sends a request for a feed to Google Calendar. One of the parameters you pass is a continuation function, also known as a callback; the service returns the feed, in JSON format, by calling the continuation function. The client can then call various get methods to use the data in the form of JavaScript objects.

To add a new entry, you create the entry using the client library's classes and methods, then call the feed.insertEntry() method to send the new entry to the service. Again you provide a continuation function, which the service calls when the entry has been successfully added.

If you're new to JavaScript, the control flow may be a little confusing. After calling a method like getEventsFeed() or insertEntry(), in most cases your script ends. Execution resumes in the continuation function when the service returns the requested data. Therefore, anything that your client does to the returned data should be done in the continuation function, or called from that function. You may need to make some variables global in order to use them in multiple functions.

For more information about this style of programming, see "Continuation-passing style" in Wikipedia.

About supported environments

Currently, we only support JavaScript client applications that run in a web page in a browser. Currently supported browsers are:

  • Firefox 2.x & 3.x
  • Internet Explorer 6, 7, & 8
  • Safari 3.x & 4.x
  • Google Chrome (all versions)

The JavaScript client library handles all communication with the service's server. If you're an experienced JS developer, you may be thinking, "But what about the same origin policy?" The JavaScript client library allows your client to send Google Data requests from any domain while remaining compliant with the browser security model.

For an overview on authenticating with the Google Data APIs, see the Google Data APIs Authentication Overview. The rest of this document assumes that you're familiar with the basics of how this system works.

Sample client applications

To see the JavaScript client library in action, visit our samples page.

Tutorial and examples

The following examples show how to send various data API requests using the JavaScript client library.

To make them more concrete, these examples show how to interact with a specific service: Google Calendar. We'll point out places where Calendar differs from other Google services, to help you adapt these examples for use with other services. For more information about Calendar, see the Google Calendar Data API document.

Loading the library

Before your client can use the client library, the client has to request the client library code from the server.

Start by using a .

If you are not autoloading modules, you can load the Google Data client library by using the next example in your JavaScript setup code, after fetching the common loader. This call must be made from the section of your HTML document (or from a JavaScript file that's included using a