Google's officially supported Node.js client library for using Google APIs. Support for authorization and authentication with OAuth 2.0, API Keys and JWT (Service Tokens) is included.
2.xof this library
This library is in Alpha. We will make an effort to support the library, but we reserve the right to make incompatible changes when necessary.
If you've used this library before
1.x, see our Migration Guide
to learn about migrating your code from
1.x. It's pretty easy :)
If your code already works with a
1.x version of this library, no work is required
to move to
2.x. However, note that return data of getToken has become an array. Furthermore, it is recommended that you update any direct links in your code,
as explained in the Migration Guide.
The full list of supported APIs can be found here. The API endpoints are automatically generated, so if the API is not in the list, it is currently not supported by this API client library.
You can find the list of Google Cloud Platform APIs supported by gcloud in the gcloud docs.
This library is distributed on
npm. In order to add it as a dependency,
run the following command:
$ npm install googleapis --save
Example: Creates a URL Shortener client and retrieves the long url of the given short url:
var google = ;var urlshortener = google;var params =shortUrl: '';// get the long url of a shortened urlurlshortenerurl;
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 = ;var urlshortener = google;
Supported APIs are listed on the Google APIs Explorer.
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 you
also provide an
expiry_date and the 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
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
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 = ;var OAuth2 = googleauthOAuth2;var oauth2Client =YOUR_CLIENT_IDYOUR_CLIENT_SECRETYOUR_REDIRECT_URL;// generate a url that asks permissions for Google+ and Google Calendar scopesvar scopes ='''';var url = oauth2Client;
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.
With the code returned, you can ask for an access token as shown below:
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
var google = ;var OAuth2 = googleauthOAuth2;var oauth2Client =YOUR_CLIENT_IDYOUR_CLIENT_SECRETYOUR_REDIRECT_URL;// set auth as a global defaultgoogleoptionsauth: oauth2Client;
Example: Setting a service-level
var google = ;var OAuth2 = googleauthOAuth2;var oauth2Client =YOUR_CLIENT_IDYOUR_CLIENT_SECRETYOUR_REDIRECT_URL;var drive = google;
See the Options section for more information.
You can start using OAuth2 to authorize and authenticate your
requests to Google APIs with the retrieved tokens. If you provide a
expiry_date (milliseconds since the Unix Epoch) and the
access_token has expired, the
access_token will be automatically refreshed
and the request is replayed (with the except of requests with a media body, as
we cannot reliably restart your media stream). Set
force a refresh.
The following sample retrieves Google+ profile of the authenticated user.
var google = ;var plus = google;var OAuth2 = googleauthOAuth2;var oauth2Client =YOUR_CLIENT_IDYOUR_CLIENT_SECRETYOUR_REDIRECT_URL;// Retrieve tokens via token exchange explained above or set them:oauth2Client;pluspeople;
If you need to manually refresh the
access_token associated with your OAuth2
client, make sure you have a
refresh_token set in your credentials first and
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 = ;var plus = google;var API_KEY = 'ABC123'; // specify your API key herepluspeople;
Alternatively, you can specify the
key parameter and it will get used:
To learn more about API keys, please see the documentation.
The Google Developers Console provides
.json file that you can use to configure a JWT auth client and authenticate your requests.
var key = ;var jwtClient =;jwtClient;
The parameters for the JWT auth client including how to use it with a
file are explained in samples/jwt.js.
Rather than manually creating an OAuth2 client, JWT client, or Compute client, the auth library can create the correct credential type for you, depending upon the environment your code is running under.
For example, a JWT auth client will be created when your code is running on your local developer machine, and a Compute client will be created when the same code is running on a configured instance of Google Compute Engine.
The code below shows how to retrieve a default credential type, depending upon the runtime environment. The createScopedRequired must be called to determine when you need to pass in the scopes manually, and when they have been set for you automatically based on the configured runtime environment.
// This method looks for the GCLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS// environment variables.googleauth;
The body of the request is specified in the
resource parameter object of the
pairs. See the example in the next section below for an example on how it is
This client supports multipart media uploads. The resource parameters are
specified in the
resource parameter object, and the media itself is
specified in the
media.body parameter with mime-type specified in
This example uploads a plain text file to Google Drive with the title "Test" and contents "Hello World".
var drive = google;drivefiles;
You can also upload media by specifying
media.body 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.
var fs = ;var drive = google;drivefiles;
For more examples of creation and modification requests with media attachments,
take a look at the
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 = drivefiles;console; // print out the request's URL.
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
The options you specify are attached to the
request object so whatever
request supports, this library supports. You may also specify global or per-service request parameters that will be attached to all API calls you make.
A full list of supported options can be found here.
var google = ;googleoptions proxy: '' auth: auth ;// All requests made with this object will use these settings unless overridden.
var google = ;googleoptions params: quotaUser: 'firstname.lastname@example.org' ;// All requests from all services will contain the above query parameter// unless overridden either in a service client or in individual API calls.
You can also specify options when creating a service client.
var auth = 'API KEY'; // or you could use oauth2Clientvar urlshortener = google;// All requests made with this object will use the specified auth.
By doing this, every API call made with this service client will use
Note: Created clients are immutable so you must create a new one if you want to specify different options.
var urlshortener = google;// All requests made with this service client will contain the// quotaUser query parameter unless overridden in individual API calls.// Calls with this drive client will NOT contain the quotaUser query parameter.var drive = google;
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.
var google = ;var bigquery = google;// This method looks for the GCLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS// environment variables.googleauth;
You can also override request options per request, such as
This library is licensed under Apache 2.0. Full license text is available in COPYING.