googleapis

Google APIs NodeJS Client

Google's officially supported node.js client library for using Google APIs. It also supports authorization and authentication with OAuth 2.0.

Migrating to version 1.0.0 of this library

If you've used this library before 1.0.0, see our Migration Guide to learn about migrating your code from 0.x.x to 1.0.0. It's pretty easy :)

Questions/problems?

• Ask your development related questions on
• If you've found an bug/issue, please file it on GitHub.

Installation

This library is distributed on npm. In order to add it as a dependency, run the following command:

$ npm install googleapis

Usage

Example: Creates a URL Shortener client and retrieves the long url of the given short url:

var google = require('googleapis');
var urlshortener = google.urlshortener('v1');

var params = { shortUrl: 'http://goo.gl/xKbRu3' };

// get the long url of a shortened url
urlshortener.url.get(params, function (err, response) {
  console.log('Long url is', response.longUrl);
});

Create a service client

To interact with the various Google APIs you need to create a service client for that particular API. These are immutable objects you use to make API calls.

Example: Creating a urlshortener client with version v1 of the API.

var google = require('googleapis');
var urlshortener = google.urlshortener('v1');

Supported APIs are listed on the Google APIs Explorer.

Authorizing and Authenticating

This client comes with an OAuth2 client that allows you to retrieve an access token and refreshes the token and retry the request seamlessly if token is expired. The basics of Google's OAuth2 implementation is explained on Google Authorization and Authentication documentation.

In the following examples, you may need a CLIENT_ID, CLIENT_SECRET and REDIRECT_URL. You can find these pieces of information by going to the Developer Console, clicking your project --> APIs & auth --> credentials.

For more information about OAuth2 and how it works, see here.

A complete sample application that authorizes and authenticates with the OAuth2 client is available at examples/oauth2.js.

Generating an authentication URL

To ask for permissions from a user to retrieve an access token, you redirect them to a consent page. To create a consent page URL:

var google = require('googleapis');
var OAuth2 = google.auth.OAuth2;

var oauth2Client = new OAuth2(CLIENT_ID, CLIENT_SECRET, REDIRECT_URL);

// generate a url that asks permissions for Google+ and Google Calendar scopes
var scopes = [
  'https://www.googleapis.com/auth/plus.me',
  'https://www.googleapis.com/auth/calendar'
];

var url = oauth2Client.generateAuthUrl({
  access_type: 'offline', // 'online' (default) or 'offline' (gets refresh_token)
  scope: scopes // If you only need one scope you can pass it as string
});

Retrieve authorization code

Once a user has given permissions on the consent page, Google will redirect the page to the redirect URL you have provided with a code query parameter.

GET /oauthcallback?code={authorizationCode}

Retrieve access token

With the code returned, you can ask for an access token as shown below:

oauth2Client.getToken(code, function(err, tokens) {
  // Now tokens contains an access_token and an optional refresh_token. Save them.
  if(!err) {
    oauth2Client.setCredentials(tokens);
  }
});

Settings global or service-level auth

You can set the auth as a global or service-level option so you don't need to specify it every request.

Example: Setting a global auth option.

var google = require('googleapis');
var OAuth2 = google.auth.OAuth2;
var oauth2Client = new OAuth2(CLIENT_ID, CLIENT_SECRET, REDIRECT_URL);
google.options({ auth: oauth2Client }); // set auth as a global default

Example: Setting a service-level auth option.

var google = require('googleapis');
var OAuth2 = google.auth.OAuth2;
var oauth2Client = new OAuth2(CLIENT_ID, CLIENT_SECRET, REDIRECT_URL);

var drive = google.drive({ version: 'v2', auth: oauth2Client });

See the Options section for more information.

Making Authenticated Requests

You can start using OAuth2 to authorize and authenticate your requests to Google APIs with the retrieved tokens. If you provide a refresh_token, the access_token is automatically refreshed and the request is replayed in case the access_token has expired.

Following sample retrieves Google+ profile of the authenticated user.

var google = require('googleapis');
var plus = google.plus('v1');
var oauth2Client = new OAuth2(CLIENT_ID, CLIENT_SECRET, REDIRECT_URL);

// Retrieve tokens via token exchange explained above or set them:
oauth2Client.setCredentials({
  access_token: 'ACCESS TOKEN HERE',
  refresh_token: 'REFRESH TOKEN HERE'
});

plus.people.get({ userId: 'me', auth: oauth2Client }, function(err, response) {
  // handle err and response
});

Using API keys

You may need to send an API key with the request you are going to make. The following uses an API key to make a request to the Google+ API service to retrieve a person's profile given a userId:

var google = require('googleapis');
var plus = google.plus('v1');

var API_KEY = 'ABC123'; // specify your API key here

plus.people.get({ auth: API_KEY, userId: '+google' }, function(err, user) {
  console.log('Result: ' + (err ? err.message : user.displayName));
});

Alternatively, you can specify the key parameter and it will get used:

plus.people.get({ key: API_KEY, userId: '+google' }, function(err, user) {
  console.log('Result: ' + (err ? err.message : user.displayName));
});

To learn more about API keys, please see the documentation.

Media Uploads

This client supports multipart media uploads. The resource parameters are specified in the resource parameter object, and the media body itself is specified in the media parameter.

Example: Upload a plain text file to Google Drive with the title "Test" and contents "Hello World".

var drive = google.drive({ version: 'v2', auth: oauth2Client });

drive.files.insert({
  resource: {
    title: 'Test',
    mimeType: 'text/plain'
  },
  media: 'Hello World'
}, callback);

You can also upload media by specifying media as a Readable stream. This can allow you to upload very large files that cannot fit into memory.

Note: Your readable stream may be unstable. Use at your own risk.

Example: Upload an image to Google Drive from a readable stream.

var fs = require('fs');
var drive = google.drive({ version: 'v2', auth: oauth2Client });

drive.files.insert({
  resource: {
    title: 'testimage.png',
    mimeType: 'image/png'
  },
  media: fs.createReadStream('awesome.png') // read streams are awesome!
}, callback);

For more examples of creation and modification requests with media attachments, take a look at the examples/mediaupload.js sample.

Exposing request object

Every request to the API returns a request object, allowing you to track the request's progress or general information about the request.

var req = drive.files.insert(/* ... */);
console.log(req.uri.href); // print out the request's URL.

Options

For more fine-tuned control over how your API calls are made, we provide you with the ability to specify additional options that can be applied directly to the mikeal/request object used in this library to make network calls to the API.

You may specify additional options either in the global google object or on a service client basis.

Available options

The options you specify are attached to the request object so whatever request supports, this library supports.

A full list of supported options can be found here.

Global options

Example: Specifying a default proxy and auth to be used for each request

var google = require('googleapis');
google.options({ proxy: 'http://proxy.example.com', auth: auth });

// all requests made with this object will use these settings unless overridden

Service-client options

You can also specify options when creating a service client. For example, to specify a default auth option (API key or OAuth2 client), simply pass it in like so:

var auth = 'API KEY'; // or you could use oauth2Client
var urlshortener = google.urlshortener({ version: 'v1', auth: auth });

// all requests made with this object will use the specified auth

By doing this, every API call made with this service client will use 'API KEY' to authenticate.

Note: Created clients are immutable so you must create a new one if you want to specify different options.

Request-level options

You can specify an auth object to be used per request. Each request also inherits the options specified at the service level and global level.

License

This library is licensed under Apache 2.0. Full license text is available in COPYING.

Contributing

See CONTRIBUTING.