Registry / gcp / google-ads-api

google-ads-api

JSON →
library23.0.0jsnpmunverified

This library provides an unofficial Node.js client for interacting with the Google Ads API, currently supporting API version 23.0.0. It aims to offer a simplified and easy-to-use interface, leveraging REST and Protocol Buffers internally for underlying communication. The library maintains a strong focus on developer experience by shipping comprehensive TypeScript definitions for all resources, enums, errors, and services, ensuring strong type-checking and autocompletion. While unofficial, it typically tracks Google Ads API releases closely, with major library versions often aligning with new Google Ads API versions. Key differentiators include its full API functionality coverage, support for both declarative `report` and raw GAQL `query` methods, and the provision of hooks for various service methods. It's a robust alternative for Node.js developers requiring programmatic access to Google Ads.

npm install google-ads-api
INSTALL
IMPORT
SIG · GOOGLE-ADS-API
G
google-ads-api
gcpjavascriptv23.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

GoogleAdsApi
✓ import { GoogleAdsApi } from 'google-ads-api'
✗ const { GoogleAdsApi } = require('google-ads-api')
The library is designed for ESM usage with TypeScript. While CommonJS might work via transpilation, direct `require` is generally not recommended for modern Node.js applications using this library.
enums
✓ import { enums } from 'google-ads-api'
✗ import * as enums from 'google-ads-api/build/lib/protos/enums'
All Google Ads API enums are conveniently exposed via the top-level `enums` export. Avoid importing directly from internal build paths as these are subject to change.
GoogleAdsFailure
✓ import { GoogleAdsFailure } from 'google-ads-api'
✗ import { GoogleAdsFailure } from 'google-ads-api/build/lib/errors'
Specific Google Ads API errors are typically wrapped in `GoogleAdsFailure` instances, which should be imported directly from the main package for consistent error handling. The `GoogleAdsFailure` object provides detailed error information from the API.

This quickstart demonstrates how to initialize the Google Ads API client, retrieve a list of enabled campaigns with various metrics, and list all customer accounts accessible by the provided refresh token. It highlights the use of environmental variables for secure credential management.

import { GoogleAdsApi, enums } from "google-ads-api"; import dotenv from "dotenv"; dotenv.config(); // Ensure all required environment variables are set for authentication const CLIENT_ID = process.env.GOOGLE_ADS_CLIENT_ID ?? ""; const CLIENT_SECRET = process.env.GOOGLE_ADS_CLIENT_SECRET ?? ""; const DEVELOPER_TOKEN = process.env.GOOGLE_ADS_DEVELOPER_TOKEN ?? ""; const REFRESH_TOKEN = process.env.GOOGLE_ADS_REFRESH_TOKEN ?? ""; const CUSTOMER_ID = process.env.GOOGLE_ADS_CUSTOMER_ID ?? ""; // Target customer account if (!CLIENT_ID || !CLIENT_SECRET || !DEVELOPER_TOKEN || !REFRESH_TOKEN || !CUSTOMER_ID) { console.error("Missing one or more required environment variables. Please set GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_REFRESH_TOKEN, and GOOGLE_ADS_CUSTOMER_ID."); process.exit(1); } const client = new GoogleAdsApi({ client_id: CLIENT_ID, client_secret: CLIENT_SECRET, developer_token: DEVELOPER_TOKEN, }); async function retrieveCampaignsAndCustomers() { try { const customer = client.Customer({ customer_id: CUSTOMER_ID, refresh_token: REFRESH_TOKEN, }); console.log(`\nRetrieving enabled campaigns for customer ID: ${CUSTOMER_ID}...`); const campaigns = await customer.report({ entity: "campaign", attributes: [ "campaign.id", "campaign.name", "campaign.bidding_strategy_type", "campaign_budget.amount_micros", ], metrics: [ "metrics.cost_micros", "metrics.clicks", "metrics.impressions", "metrics.all_conversions", ], constraints: { "campaign.status": enums.CampaignStatus.ENABLED, }, limit: 5, // Limit to 5 campaigns for brevity }); if (campaigns.length === 0) { console.log("No enabled campaigns found."); } else { campaigns.forEach((campaign: any) => { console.log( ` ID: ${campaign.campaign.id}, Name: ${campaign.campaign.name}, ` + `Status: ${enums.CampaignStatus[campaign.campaign.status]}, ` + `Clicks: ${campaign.metrics.clicks}, Cost: ${(campaign.metrics.cost_micros / 1_000_000).toFixed(2)}` ); }); } console.log("\nListing accessible customers for the provided refresh token..."); const accessibleCustomers = await client.listAccessibleCustomers(REFRESH_TOKEN); console.log(" Accessible Customer Resource Names:", accessibleCustomers); } catch (error: any) { console.error("\nAn error occurred:", error.message); if (error.errors && error.errors.length > 0) { console.error("Google Ads API specific errors:", JSON.stringify(error.errors, null, 2)); } process.exit(1); } } retrieveCampaignsAndCustomers();
Debug
Known issues
breakingWith v10.0.0, all direct `get` methods (e.g., `customer.getCampaign()`, `customer.getAdGroup()`) for services were removed to align with changes in the official Google Ads API. Attempts to use these methods will result in a runtime error.
fix
Migrate code to use `report` or `query` methods with Google Ads Query Language (GAQL) for retrieving resources. For example, instead of `customer.getCampaign(campaignId)`, use `await customer.report({ entity: 'campaign', constraints: { 'campaign.id': campaignId } })`.
affects: >=10.0.0
gotchaAuthentication requires a Google Ads Developer Token, Client ID, Client Secret, and Refresh Token. Misconfiguration of any of these credentials is a very common source of errors, typically resulting in `authentication_error` or `authorization_error`.
fix
Double-check all credentials against your Google Ads Manager Account. Ensure the developer token is approved and has the correct access level. Verify the `refresh_token` has access to the specified `customer_id` and that the `login_customer_id` is correct if managing multiple accounts.
affects: >=1.0.0
gotchaThe Google Ads API, and thus this client library, is subject to strict quotas and rate limits. Exceeding these limits will result in `RESOURCE_EXHAUSTED` errors.
fix
Implement robust error handling with exponential backoff and retry mechanisms for API calls. Review Google Ads API quota limits documentation and optimize your API request patterns.
affects: >=1.0.0
gotchaThis is an unofficial client library. While actively maintained and closely tracking the official Google Ads API, there might be slight delays in supporting the very latest API features or subtle behavioral differences compared to official Google-provided SDKs (if they existed for Node.js).
fix
Stay updated with the library's releases and Google Ads API release notes. Test thoroughly when upgrading to new Google Ads API versions or when new features are critical.
affects: >=1.0.0
gotchaThe `customer_id` and `login_customer_id` (if used) are crucial for specifying the context of your API requests. Incorrect values can lead to 'Customer not found' or permission errors, even with valid authentication tokens.
fix
Always verify that the `customer_id` provided corresponds to an actual customer account accessible by the `refresh_token`. If managing multiple accounts, ensure `login_customer_id` is set correctly to the manager account through which you access the target customer.
affects: >=1.0.0
Errors
Common errors & fixes
RESOURCE_EXHAUSTED: Rate limits exceeded. Please retry in some time.
The application has sent too many requests within a short period, or has exceeded daily API quotas.
fix
Implement an exponential backoff strategy for retrying failed API calls and review the Google Ads API quotas to ensure your usage aligns with limits. Consider batching operations where possible.
[GoogleAdsFailure] authentication_error: The developer token is not approved. Make sure you have a valid developer token.
The developer token provided in the client configuration is either incorrect, unapproved, or has insufficient access levels.
fix
Log into your Google Ads Manager Account, navigate to API Center, and verify the Developer Token. Ensure it's active and has the required access (e.g., Test Account, Basic, Standard access).
[GoogleAdsFailure] authorization_error: User doesn't have permission to access customer.
The Google account associated with the `refresh_token` does not have sufficient permissions to access the specified `customer_id`, or the `login_customer_id` is incorrect.
fix
Verify that the `refresh_token` was generated for a Google account that has permission to access the `customer_id`. If using a manager account, ensure `login_customer_id` is set to the manager account ID.
TypeError: customer.getCampaign is not a function
Attempting to use a deprecated `get` method that was removed in `google-ads-api` v10.
fix
Refactor your code to use the `customer.report()` method with appropriate GAQL. For example, to get a campaign by ID, use `await customer.report({ entity: 'campaign', constraints: { 'campaign.id': '<YOUR_CAMPAIGN_ID>' } })`.
Upgrade
Version history
23.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
50 hits · last 30 days
node
44
Bingbot
1
OpenAI (training)
1
Resources
google-ads-api — npm install google-ads-api · libregistry