{"id":13245,"library":"google-ads-api","title":"Google Ads API Client for Node.js","description":"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.","status":"active","version":"23.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/Opteo/google-ads-api","tags":["javascript","google ads","google ads api","google ads node","google ads nodejs","google ads javascript","adwords","adwords api","adwords nodejs","typescript"],"install":[{"cmd":"npm install google-ads-api","lang":"bash","label":"npm"},{"cmd":"yarn add google-ads-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add google-ads-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { GoogleAdsApi } = require('google-ads-api')","symbol":"GoogleAdsApi","correct":"import { GoogleAdsApi } from 'google-ads-api'"},{"note":"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.","wrong":"import * as enums from 'google-ads-api/build/lib/protos/enums'","symbol":"enums","correct":"import { enums } from 'google-ads-api'"},{"note":"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.","wrong":"import { GoogleAdsFailure } from 'google-ads-api/build/lib/errors'","symbol":"GoogleAdsFailure","correct":"import { GoogleAdsFailure } from 'google-ads-api'"}],"quickstart":{"code":"import { GoogleAdsApi, enums } from \"google-ads-api\";\nimport dotenv from \"dotenv\"; \n\ndotenv.config();\n\n// Ensure all required environment variables are set for authentication\nconst CLIENT_ID = process.env.GOOGLE_ADS_CLIENT_ID ?? \"\";\nconst CLIENT_SECRET = process.env.GOOGLE_ADS_CLIENT_SECRET ?? \"\";\nconst DEVELOPER_TOKEN = process.env.GOOGLE_ADS_DEVELOPER_TOKEN ?? \"\";\nconst REFRESH_TOKEN = process.env.GOOGLE_ADS_REFRESH_TOKEN ?? \"\";\nconst CUSTOMER_ID = process.env.GOOGLE_ADS_CUSTOMER_ID ?? \"\"; // Target customer account\n\nif (!CLIENT_ID || !CLIENT_SECRET || !DEVELOPER_TOKEN || !REFRESH_TOKEN || !CUSTOMER_ID) {\n  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.\");\n  process.exit(1);\n}\n\nconst client = new GoogleAdsApi({\n  client_id: CLIENT_ID,\n  client_secret: CLIENT_SECRET,\n  developer_token: DEVELOPER_TOKEN,\n});\n\nasync function retrieveCampaignsAndCustomers() {\n  try {\n    const customer = client.Customer({\n      customer_id: CUSTOMER_ID,\n      refresh_token: REFRESH_TOKEN,\n    });\n\n    console.log(`\\nRetrieving enabled campaigns for customer ID: ${CUSTOMER_ID}...`);\n\n    const campaigns = await customer.report({\n      entity: \"campaign\",\n      attributes: [\n        \"campaign.id\",\n        \"campaign.name\",\n        \"campaign.bidding_strategy_type\",\n        \"campaign_budget.amount_micros\",\n      ],\n      metrics: [\n        \"metrics.cost_micros\",\n        \"metrics.clicks\",\n        \"metrics.impressions\",\n        \"metrics.all_conversions\",\n      ],\n      constraints: {\n        \"campaign.status\": enums.CampaignStatus.ENABLED,\n      },\n      limit: 5, // Limit to 5 campaigns for brevity\n    });\n\n    if (campaigns.length === 0) {\n      console.log(\"No enabled campaigns found.\");\n    } else {\n      campaigns.forEach((campaign: any) => {\n        console.log(\n          `  ID: ${campaign.campaign.id}, Name: ${campaign.campaign.name}, ` +\n          `Status: ${enums.CampaignStatus[campaign.campaign.status]}, ` +\n          `Clicks: ${campaign.metrics.clicks}, Cost: ${(campaign.metrics.cost_micros / 1_000_000).toFixed(2)}`\n        );\n      });\n    }\n\n    console.log(\"\\nListing accessible customers for the provided refresh token...\");\n    const accessibleCustomers = await client.listAccessibleCustomers(REFRESH_TOKEN);\n    console.log(\"  Accessible Customer Resource Names:\", accessibleCustomers);\n\n  } catch (error: any) {\n    console.error(\"\\nAn error occurred:\", error.message);\n    if (error.errors && error.errors.length > 0) {\n        console.error(\"Google Ads API specific errors:\", JSON.stringify(error.errors, null, 2));\n    }\n    process.exit(1);\n  }\n}\n\nretrieveCampaignsAndCustomers();","lang":"typescript","description":"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."},"warnings":[{"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 } })`.","message":"With 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.","severity":"breaking","affected_versions":">=10.0.0"},{"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.","message":"Authentication 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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"This 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).","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The application has sent too many requests within a short period, or has exceeded daily API quotas.","error":"RESOURCE_EXHAUSTED: Rate limits exceeded. Please retry in some time."},{"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).","cause":"The developer token provided in the client configuration is either incorrect, unapproved, or has insufficient access levels.","error":"[GoogleAdsFailure] authentication_error: The developer token is not approved. Make sure you have a valid developer token."},{"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.","cause":"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.","error":"[GoogleAdsFailure] authorization_error: User doesn't have permission to access customer."},{"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>' } })`.","cause":"Attempting to use a deprecated `get` method that was removed in `google-ads-api` v10.","error":"TypeError: customer.getCampaign is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}