Google APIs Node.js Client

Common errors

• Error: The API returned an error: Error: Not Found

  cause The requested API version or resource does not exist, or the API is not enabled for your Google Cloud Project. This can happen if the API name or version is incorrect, or if the API is not publicly available or requires special access.
  fix Verify the API name and version against the Google APIs Explorer. Ensure the API is enabled in your Google Cloud Project's API Library. Check for any required scopes or specific access permissions.

• Error: invalid_grant

  cause This error typically indicates an issue with authentication credentials, such as an expired refresh token, an invalid service account key, or insufficient permissions for the authenticated identity (user or service account).
  fix For OAuth2, ensure your refresh token is valid or re-authorize the user. For service accounts, verify the JSON key file is correct, not expired, and the service account has the necessary IAM roles. For Application Default Credentials (ADC), ensure `gcloud auth application-default login` has been run or `GOOGLE_APPLICATION_CREDENTIALS` is correctly set and points to a valid service account key.

• TypeError: google.youtube is not a function

  cause This usually means the specific API client (e.g., `youtube`) could not be loaded or is not being accessed correctly from the `google` object. This might occur if the API is not supported by the version of `googleapis` installed, or if there's a typo in the API name.
  fix Check the exact API name and required version on the Google APIs Explorer. Ensure your `googleapis` package is up-to-date, or install the specific `@googleapis/<api-name>` submodule if using granular installations. If TypeScript, ensure your import statements and type definitions are correct.

• ERR_REQUIRE_ESM: require() of ES Module ... not supported

  cause You are attempting to use `require()` to import an ES Module package (like `googleapis` in newer Node.js versions or certain submodules) in a CommonJS context without proper configuration. Node.js >=18 defaults to ESM.
  fix Update your code to use `import` statements: `import { google } from 'googleapis';`. Ensure your `package.json` has `"type": "module"` if you intend to write ESM, or configure a transpiler like Babel or TypeScript to output CommonJS if you must use `require()` with an ESM-only dependency.

Warnings

• gotcha For Google Cloud Platform (GCP) APIs (e.g., Cloud Storage, Pub/Sub, Datastore), it is strongly recommended to use the dedicated `@google-cloud/*` client libraries (e.g., `@google-cloud/storage`). These libraries are idiomatic, actively developed, often provide gRPC support for better performance, and are built specifically for GCP services. The `googleapis` library is in maintenance mode for new features, focusing on critical bugs and security updates, and is generally recommended for non-GCP Google APIs.
  Fix: When interacting with GCP services, consider installing and using the corresponding `@google-cloud/*` package (e.g., `npm install @google-cloud/storage`) instead of `googleapis`.
• breaking The `googleapis` package requires Node.js version 18 or greater. Older Node.js versions are not supported and may lead to installation failures or runtime errors.
  Fix: Upgrade your Node.js environment to version 18 or a later actively supported LTS release. Use `nvm install 18` and `nvm use 18` or update your system's Node.js installation.
• gotcha While API keys can be used for simple, public data access, more secure and recommended authentication methods for Google APIs, especially when accessing user data or sensitive resources, include OAuth 2.0 (user accounts), Service Accounts (server-to-server), and Application Default Credentials (ADC). Using static API keys or hardcoding credentials is a common security anti-pattern.
  Fix: Implement Application Default Credentials for local development and Google Cloud deployments, or utilize OAuth 2.0 flows for user-centric applications, and Service Accounts for server-to-server interactions. Avoid embedding API keys directly in source code; use environment variables or secret management services.
• gotcha To reduce application startup times and dependency footprint, you can install individual API modules as separate `@googleapis/*` submodules (e.g., `npm install @googleapis/docs`) instead of the monolithic `googleapis` package. This is particularly beneficial if you only interact with a few Google APIs.
  Fix: Instead of `npm install googleapis`, consider `npm install @googleapis/<api-name>` for the specific Google API clients your application needs, replacing `<api-name>` with the desired API name (e.g., `docs`, `drive`, `youtube`).
• breaking Breaking changes for specific API modules are regularly introduced and are aggregated into major releases of the `googleapis` package. Always review the changelog for the specific API version you are using (e.g., `youtube-v3`) and the main `googleapis` package to understand potential impacts on your application.
  Fix: Pin your `googleapis` dependency to a specific major version in `package.json` to control when updates are applied (e.g., `"googleapis": "^171.0.0"`). Thoroughly test your application against new major versions before deploying to production.

Install

• npm install googleapis npm
• yarn add googleapis yarn
• pnpm add googleapis pnpm

Imports

• google
  wrong:

  const google = require('googleapis');

  correct:

  import { google } from 'googleapis';

  ESM import for `google` object is preferred in modern Node.js environments (>=18), though CommonJS `require` is still widely used and supported. Ensure your project's `type` is set to `module` in `package.json` for ESM.
• Auth.GoogleAuth
  wrong:

  import { GoogleAuth } from 'googleapis/build/src/auth/googleauth';

  correct:

  import { GoogleAuth } from 'google-auth-library';

  For advanced authentication scenarios, particularly with Application Default Credentials or custom auth flows, it's recommended to directly import `GoogleAuth` from the underlying `google-auth-library` package, which `googleapis` uses internally. The `google` object in `googleapis` typically handles common authentication patterns like API Keys and OAuth2 directly when passed to service constructors.
• youtube_v3.Youtube
  wrong:

  import { Youtube } from 'googleapis/build/src/apis/youtube/v3';

  correct:

  import { youtube_v3 } from 'googleapis';

  Specific API types and clients are typically accessed as properties of the main `google` object. For type-safety and consistency, import the namespace (e.g., `youtube_v3`) and then use `google.youtube({ version: 'v3', auth })` to instantiate the client.

Quickstart

This quickstart demonstrates how to initialize the Google APIs client library, instantiate the Blogger API client for version v3, and authenticate with an API key to retrieve blog details using `async/await`.

import { google } from 'googleapis';

async function getBlogDetails(blogId: string, apiKey: string) {
  // Each API may support multiple versions. With this sample, we're getting
  // v3 of the blogger API, and using an API key to authenticate.
  const blogger = google.blogger({
    version: 'v3',
    auth: apiKey
  });

  const params = {
    blogId: blogId
  };

  try {
    // Get the blog details
    const res = await blogger.blogs.get(params);
    console.log(`Successfully retrieved blog ID: ${blogId}`);
    console.log(`The blog URL is: ${res.data.url}`);
    console.log(`Blog Title: ${res.data.name}`);
    return res.data;
  } catch (err) {
    console.error('The API returned an error: ' + err);
    throw err;
  }
}

// To run this example, replace 'YOUR_BLOG_ID' and process.env.GOOGLE_API_KEY with actual values.
// A public blog ID can be found via Google APIs Explorer or your own Blogger account.
const BLOG_ID = process.env.BLOG_ID ?? '3213900'; // Example public blog ID
const API_KEY = process.env.GOOGLE_API_KEY ?? ''; // Ensure you have an API key enabled for Blogger API

if (!API_KEY) {
  console.warn('Warning: No GOOGLE_API_KEY provided. This example might fail if the API requires authentication.');
}

getBlogDetails(BLOG_ID, API_KEY)
  .then(details => console.log('Operation complete.'))
  .catch(error => console.error('Failed to get blog details.', error));