{"id":15628,"library":"googleapis","title":"Google APIs Node.js Client","description":"The `googleapis` package is Google's officially supported Node.js client library for interacting with a wide range of Google APIs. It provides a unified interface for over 200 Google services, including non-GCP APIs like YouTube, Gmail, and Google Drive, as well as some Google Cloud Platform (GCP) services. The library currently stands at version 171.4.0 and sees frequent updates, typically driven by automated API definition generators for individual service modules, leading to regular minor and patch releases. Major version bumps often aggregate breaking changes across various underlying API modules. A key differentiator is its comprehensive coverage of all Google APIs, contrasting with the `@google-cloud/*` libraries which are purpose-built and idiomatic Node.js clients specifically for Google Cloud Platform services. While `googleapis` provides authentication support for OAuth 2.0, API Keys, and JWT tokens, it is explicitly in maintenance mode, meaning new features will not be added, and development prioritizes critical bug fixes and security issues. For new projects utilizing GCP services, Google strongly recommends using the actively developed `@google-cloud/*` client libraries, which often offer gRPC support for improved performance.","status":"maintenance","version":"171.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/googleapis/google-api-nodejs-client","tags":["javascript","google","api","google apis","client","client library","typescript"],"install":[{"cmd":"npm install googleapis","lang":"bash","label":"npm"},{"cmd":"yarn add googleapis","lang":"bash","label":"yarn"},{"cmd":"pnpm add googleapis","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const google = require('googleapis');","symbol":"google","correct":"import { google } from 'googleapis';"},{"note":"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.","wrong":"import { GoogleAuth } from 'googleapis/build/src/auth/googleauth';","symbol":"Auth.GoogleAuth","correct":"import { GoogleAuth } from 'google-auth-library';"},{"note":"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.","wrong":"import { Youtube } from 'googleapis/build/src/apis/youtube/v3';","symbol":"youtube_v3.Youtube","correct":"import { youtube_v3 } from 'googleapis';"}],"quickstart":{"code":"import { google } from 'googleapis';\n\nasync function getBlogDetails(blogId: string, apiKey: string) {\n  // Each API may support multiple versions. With this sample, we're getting\n  // v3 of the blogger API, and using an API key to authenticate.\n  const blogger = google.blogger({\n    version: 'v3',\n    auth: apiKey\n  });\n\n  const params = {\n    blogId: blogId\n  };\n\n  try {\n    // Get the blog details\n    const res = await blogger.blogs.get(params);\n    console.log(`Successfully retrieved blog ID: ${blogId}`);\n    console.log(`The blog URL is: ${res.data.url}`);\n    console.log(`Blog Title: ${res.data.name}`);\n    return res.data;\n  } catch (err) {\n    console.error('The API returned an error: ' + err);\n    throw err;\n  }\n}\n\n// To run this example, replace 'YOUR_BLOG_ID' and process.env.GOOGLE_API_KEY with actual values.\n// A public blog ID can be found via Google APIs Explorer or your own Blogger account.\nconst BLOG_ID = process.env.BLOG_ID ?? '3213900'; // Example public blog ID\nconst API_KEY = process.env.GOOGLE_API_KEY ?? ''; // Ensure you have an API key enabled for Blogger API\n\nif (!API_KEY) {\n  console.warn('Warning: No GOOGLE_API_KEY provided. This example might fail if the API requires authentication.');\n}\n\ngetBlogDetails(BLOG_ID, API_KEY)\n  .then(details => console.log('Operation complete.'))\n  .catch(error => console.error('Failed to get blog details.', error));","lang":"typescript","description":"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`."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<171.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=25.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"Error: The API returned an error: Error: Not Found"},{"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.","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).","error":"Error: invalid_grant"},{"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.","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.","error":"TypeError: google.youtube is not a function"},{"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.","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.","error":"ERR_REQUIRE_ESM: require() of ES Module ... not supported"}],"ecosystem":"npm"}