google-ads-api
  • Concepts
  • Core Resources

Google Ads API

Unofficial Google Ads API client library for Node

Google Ads version numberNPM version numberNumber of downloads from NPMDependency status

Overview

Features

Installation

$ yarn add google-ads-api

Why does this library exist?

The official Google Ads client libraries are robust, but they don't always offer the most user-friendly developer interfaces, and their documentation can be confusing.

This library aims to offer a better way to use the Google Ads API.

  • google-ads-node is a low-level Node implementation of the API, which imitates the stucture of the other client libraries.
  • google-ads-api (this library) is a wrapper around google-ads-node to provide a better developer experience.

Google Ads API versions

We aim to release new versions of this library within a few weeks of new API versions becoming available. These are the releases so far:

  • v2.0 of the official google ads API: Versions 3.0.0 and above of this library
  • v1.3 of the official google ads API: Versions 2.3.0 to 2.3.0 of this library
  • v1.2 of the official google ads API: Versions 2.1.0 to 2.2.0 of this library
  • v1.1 of the official google ads API: Versions 1.2.0 to 2.0.0 of this library
  • v1.0 of the official google ads API: Versions 1.0.0 to 1.0.2 of this library

Authentication

Before you can use the Google Ads API, you'll need to gather some authentication. You'll need:

  • Client id and client secret: These are your OAuth credentials. You'll find them in your Google Cloud Console. If you don't already have these tokens, see google's instructions.
  • Developer token: You'll find this in your Google Ads account, in the API Center. You will need to apply for one.

Then, for every Google Ads account you want to access, you'll need:

  • Customer account ID: This is the CID of the account you want to access, which will look like xxx-xxx-xxxx.
  • Login customer ID (only required if accessing the account via an MCC): This is usually the CID of the highest-level account in your MCC structure, also in the format xxx-xxx-xxxx.
  • Refresh token: You'll get this token when somebody authorises you to query their Google Ads account via OAuth. To get started, you can use https://refresh-token-helper.opteo.com/ to generate a single refresh token.
import { GoogleAdsApi } from 'google-ads-api'

const client = new GoogleAdsApi({
    client_id: '<YOUR_CLIENT_ID>',
    client_secret: '<YOUR_CLIENT_SECRET>',
    developer_token: '<YOUR_DEVELOPER_TOKEN>',
})

const customer = client.Customer({
    customer_account_id: '123-123-123',
    login_customer_id: '456-456-456', // Optionally provide a login-customer-id
    refresh_token: '<YOUR_REFRESH_TOKEN>',
})

// If done correctly, you should now be able to list the campaigns in the account 123-123-123
customer.campaigns.list()

Reporting

"Reporting" just means fetching data about an account.

All data in Google Ads is queriable via SQL-like tables. There is one table per resource (such as campaign or ad_group_ad). These tables and their associated fields can be found in the core resources section of this page, or in the "API Fields" section of the official docs.

Resources

There are four types of resources available for querying.

  1. Core Resources directly map to entities in your account. Example: campaign, ad_group_criterion.
  2. Criteria View Resources offer a more convenient way to query ad_group and campaign criteria (criteria are targeting options, such as keywords or placements). They may also aggregate metrics differently. Example: keyword_view is a subset of ad_group_criterion, while age_range_view is a subset of campaign_criterion.
  3. Click & Search Term Resources are like core resources, except that they are by nature read-only. Example: click_view, search_term_view.
  4. Constant Resources are just a convenient way to query Google Ads constants (and their IDs). They aren't specific to your account. Example: geo_target_constant, mobile_device_constant.

Fields

Resources contain three types of fields:

  1. Metrics hold data about the performance of your account, and change through time. Example: metrics.clicks or metrics.historical_quality_score.
  2. Segments allow you to segment your metrics by your chosen field, meaning your result will have more rows. Example: segments.device or segments.conversion_action.
  3. Attributes are static information about a resource. All fields described in the core resources section of this page are attributes. It is not possible to query the past value of an attribute. Example: campaign.name or ad_group_criterion.keyword.text.

Using GAQL

The customer.query() method allows you to query customer data using GAQL (Google Ads Query Language) query strings. This is great for prototyping and getting results out quickly.

GAQL looks like SQL, but it is not SQL. Key differences include:

  • Very limited grammar (for example, no OR in constraints).
  • Implicit joins when selecting selectableWith fields. These aren't always intuitive. This file holds a complete list of which fields are usable for each resource.
// Basic query
const campaigns = await customer.query(`
    SELECT 
      campaign.name, campaign.status
    FROM 
      campaign
`)

// More complex query
const keyword_texts = await customer.query(`
    SELECT 
        keyword_view.resource_name,
        ad_group_criterion.keyword.text <-- This is an implicit join on ad_group_criterion
    FROM 
      keyword_view                      <-- Main resource
    WHERE 
      campaign.status = 'PAUSED'        <-- This is another implicit join on campaign
      AND metrics.impressions > 5
    ORDER BY campaign.impressions
    LIMIT 20
`)

For a definition of the arguments and return types for customer.query(), see the customer core resource.

Using the query builder

The customer.report() method is a safer and more structured way to use GAQL. It's also more practical to use when your queries need to be built dynamically. If you are using typescript, it will give you handy autocomplete, too!

const response = await customer.report({
    entity: 'ad_group', 
    attributes: ['ad_group.id', 'ad_group.name', 'ad_group.status'], 
    metrics: ['metrics.clicks'],
    segments: ['segments.date'], 
    constraints: { 'ad_group.status': enums.AdGroupStatus.ENABLED }, 
    from_date: '2019-01-01', 
    order_by: 'metrics.clicks', 
    sort_order: 'desc',
    limit: 5, 
})

For full infomation on the arguments of customer.report(), see the customer core resource.

Every core resource also has get() and list() methods, which offer a convenient way to select every attribute of a resource. This can be quite valuable since GAQL does not support SELECT *. See the campaign core resource for an example.

Mutations

A "mutation" is a change to a Google Ads account, such as a new campaign or an adjusted bid.

Making changes using core resources

Most resources in the Google Ads API will have mutation methods for creating, updating, and deleting.

Create

The create method can take a single entity or array of entities. The results property of the response object will contain the newly created entity resource names.

const campaign = {
    name: 'new-campaign',
    campaign_budget: 'customers/123/campaignBudgets/123',
    advertising_channel_type: enums.AdvertisingChannelType.SEARCH,
    status: enums.CampaignStatus.PAUSED,
}

const { results } = await customer.campaigns.create(campaign)
console.log(results) // ['customers/123/campaigns/456'] <-- new resource_name

For more details on this method, check the create() section for the core resource you want to create, such as creating a campaign.

Update

The update method works the same way as create and takes a single entity or array of entities to update. All properties passed (that can be updated) will be updated, so if you don't want to update an attribute, don't include it.

The results property of the response object will contain the updated entity resource names.

const campaign = {
    resource_name: `customers/123/campaigns/456`,
    name: 'updated-campaign-name',
}
const { results } = await customer.campaigns.update(campaign)

For more details on this method, check the update() section for the core resource you want to modify, such as updating a campaign.

Delete

The delete method should be provided with the resource name of the entity to remove. Note: When deleting an entity in the Google Ads API, it will continue to exist, but it will be immutable and its status will be changed to REMOVED.

await customer.campaigns.delete('customers/123/campaigns/456')

For more details on this method, check the delete() section for the core resource you want to delete, such as deleting a campaign.

Atomic mutations using customer.mutateResources()

Sometimes you may want to create multiple resources of different types at once, such as creating a new campaign and its required budget. The customer.mutateResources method is designed for this use case, and supports:

  • Atomic Mutations: If any of the operations fail, all other operations will be rolled back.
  • Temporary Resource IDs: Define your entity relationships using your own temporary IDs.
  • All Mutation Types: Create, update, and delete resources.

A basic example of creating a budget, and a campaign that uses this budget, is shown below:

const { results } = await customer.mutateResources([
    {
        // For each resource, you must specify its type with the "_resource" key
        _resource: 'CampaignBudget',
        resource_name: `customers/123/campaignBudgets/-1`, // We define the new ID as -1
        name: 'My new budget',
        amount_micros: 3000000,
        explicitly_shared: true,
    },
    {
        _resource: 'Campaign',
        campaign_budget: `customers/123/campaignBudgets/-1`, // Reference to the budget above
        name: 'My new campaign',
        advertising_channel_type: enums.AdvertisingChannelType.SEARCH,
        status: enums.CampaignStatus.PAUSED,
        manual_cpc: {
            enhanced_cpc_enabled: true,
        },
        // We don't need to set a temporary resource name here because
        // nothing else in this operations array depends on this campaign
    },
])

// The real resource ids will now be defined after performing the operation
console.log(results) // ['customers/123/campaignBudgets/123123', 'customers/123/campaigns/321321']

By default, mutateResources is atomic and will rollback if one operation fails -- no new resources will be added to the client account if one operation fails. This mode can be disabled by setting the partial_failure option to true. The validate_only option is also supported in this method. See the Google Ads API documentation for more details on these settings.

await customer.mutateResources(operations, { partial_failure: true })

As well as creating resources, mutateResources also supports updating and deleting multiple resources (which also works with temporary resource ids). Use the _operation field in an operation to specify the mode, being either create, update or delete. This field isn't required and defaults to create. In the example below, these operations are executed:

  1. A new budget with the temporary resource id -1 is created.
  2. An existing campaign (id of 456) is updated to use the new budget (-1).
  3. The original budget used by the campaign is deleted.
const response = await customer.mutateResources([
    // Create new budget
    {
        _resource: 'CampaignBudget',
        _operation: 'create',
        resource_name: 'customers/123/campaignBudgets/-1',
        name: 'My new budget',
        amount_micros: 3000000,
        explicitly_shared: true,
    },
    // Update campaign to use new budget
    {
        _resource: 'Campaign',
        _operation: 'update',
        resource_name: 'customers/123/campaigns/456',
        campaign_budget: 'customers/123/campaignBudgets/-1', // Reference to budget above
    },
    // Delete old budget
    {
        _resource: 'CampaignBudget',
        _operation: 'delete',
        resource_name: 'customers/123/campaignBudgets/123123',
    },
])

Note: Using customer.mutateResources() with a single operation is equivalent to using any of the standard customer.someResource.create|update|delete() methods, but your ts definitions won't be as good.

For more information about this method, see the customer resource's mutateResources section.

Enums

All enums are represented as numbers in the Google Ads API. This means:

  • Numbers must be used for enums when making mutate calls (create, update, delete).
  • Reports will include numbers instead of strings for enum fields.

For example:

/*
    campaign.status can have a few states:

    "UNSPECIFIED" = 0
    "UNKNOWN" = 1
    "ENABLED" = 2
    "PAUSED" = 3
    "REMOVED" = 4
*/

const campaigns = await customer.query(`SELECT campaign.status FROM campaign`)

if (campaigns[0].campaign.status === 2) {
    // the campaign is enabled
}

const campaign_to_update = {
    resource_name: `customers/123/campaigns/123`,
    status: 3,
}

await customer.campaigns.update(campaign) // This will set the status to "PAUSED"

Of course, using numbers directly isn't convenient. Instead, use the enums import:

import { enums } from 'google-ads-api'

const campaigns = await customer.query(`SELECT campaign.status FROM campaign`)

if (campaigns[0].campaign.status === enums.CampaignStatus.ENABLED) {
    // the campaign is enabled
}

const campaign_to_update = {
    resource_name: `customers/123/campaigns/123`,
    status: enums.CampaignStatus.PAUSED,
}

await customer.campaigns.update(campaign) // This will set the status to "PAUSED"

The enums.ts file (found in our companion library) lists out all enums available in the Google Ads API. For example:

// Note that this will be compiled to an object by typescript.
export enum AdvertisingChannelType {
    'UNSPECIFIED' = 0,
    'UNKNOWN' = 1,
    'SEARCH' = 2,
    'DISPLAY' = 3,
    'SHOPPING' = 4,
    'HOTEL' = 5,
    'VIDEO' = 6,
    'MULTI_CHANNEL' = 7,
}

GAQL, on the other hand, expects strings for enums in constraints:

customer.query(`
    SELECT 
      ad_group_ad.id
    FROM 
        ad_group_ad 
    WHERE 
        campaign.status = "ENABLED" <-- works!
        campaign.status = ENABLED   <-- also works (for enums)
        campaign.status = 2         <-- will not work
`)
  • When using customer.query(), you must use strings.
  • When using customer.report(), both strings and numbers are supported.

Handling Errors with Enums

To handle errors from the Google Ads API, the best approach is to use the provided error enums, available with the enums import. A full list of error types can be found in the Google Ads API reference.

import { enums } from 'google-ads-api'

try {
    const campaigns = await customer.report({
        entity: 'campaign',
        attributes: ['ad_group_criterion.keyword.text'],
    })
} catch (err) {
    if (err.code.queryError === enums.QueryError.PROHIBITED_RESOURCE_TYPE_IN_SELECT_CLAUSE) {
        // Handle error case..
    }

    // Besides `code`, errors have other useful metadata:
    console.log(err.message) // "Cannot select fields from the following resource.."
    console.log(err.location) // "ad_group_criterion.keyword.text"
    console.log(err.request_id) // "5Tzsyp_M_9F7oHl_EZh8Ow", useful when discussing issues with Google support
    console.log(err.request) // Request protocol buffer body in readable format, useful for debugging
    console.log(err.failure) // gRPC GoogleAdsFailure instance
}

Utilities

This library exports a set of helper methods that can assist you during development.

  • fromMicros : Converts micro value to a normal number.
  • toMicros: Converts a normal number to a micro value.
  • getEnumString: Get the value of an enum as a string (instead of the default number value).
import { fromMicros, toMicros, getEnumString /* , enums, types, GoogleAdsApi */ } from 'google-ads-api'

fromMicros(123300000) // 123.3
toMicros(123.3) // 123300000

// You must pass the enum name and the value
getEnumString('AdvertisingChannelType', enums.AdvertisingChannelType.DISPLAY) // "DISPLAY"
getEnumString('AdvertisingChannelType', 3) // "DISPLAY"

Typescript

This library has first-class support for Typescript. We also expose every single type in the Google Ads API via the types export, should you choose to use them in your own code:

import { types } from 'google-ads-api'

const campaign: types.Campaign = {
    id: 123123,
    some_wrong_field: false, // The type checker won't allow this.
    name: [1, 2, 3], // `name` should be a string, so this will also throw an error.
}

The resources.ts file (found in our companion library) is a good reference for all exported types. For example, you'll find:

// Example interface for the v2 common "TextAdInfo" entity in the Google Ads API

/* .google.ads.googleads.v2.common.TextAdInfo */
export interface TextAdInfo {
    headline?: string
    description_1?: string
    description_2?: string
}

Changelog

This library's changelog: https://github.com/Opteo/google-ads-api/blob/master/CHANGELOG.md

Official API changelog: Google Ads API release notes

We do not yet support every feature of the Google Ads API. Currently, these parts are missing:

  • Uploading click and call conversions
  • Adjusting conversion via uploads
  • Listing accessible MCC customers
  • Creating new customers
  • Generating new keyword ideas
  • Using keywordPlans to generate forecasts
  • Listing Merchant Center links
  • Using the MutateJobService
  • Listing payment accounts
  • Applying and dismissing Google's recommendations

If any of these features are important to you, help us prioritise by opening an issue on GitHub!

FAQ

I'm getting errors that my bids or budgets are too small. Why? All monetary values are set and fetched in micros. These are 1,000,000x bigger than the actual amount. Use our utility functions toMicros and fromMicros to convert.

Where are my keywords? Keywords are hidden away in AdGroupCriterion -> keyword. Keywords are just one of many types of targeting "Criteria", meaning they modify the targeting of ads.

Can I run this in a browser? No. There's no way to hide your tokens without using a proxy, which would need to be on your server anyway.

Can I run this in a serverless environment (Lambda, etc.)? Yes. Note that this library uses several NodeJS native methods (fs, crypto), so webworker-like environments such as CloudFlare workers won't function.

When Google releases their own Node client for Google Ads, will this library still be relevant? Yes. We've already auto-generated a client with Google's protocol buffers, called google-ads-node. It's very feature complete, and this library is built on top of it. When Google releases their own node client, we may deprecate google-ads-node and refractor this library to use it instead.

Do you have any examples on how to use this library? We're working on a robust set of examples. You can find the ones we've already completed in this branch.

Core resources

AccountBudget

The AccountBudget object

Fields

ONE of the following:
  • adjusted_spending_limit_micros int64
  • adjusted_spending_limit_type enum
ONE of the following:
  • approved_end_date_time string
  • approved_end_time_type enum
ONE of the following:
  • approved_spending_limit_micros int64
  • approved_spending_limit_type enum
ONE of the following:
  • proposed_end_date_time string
  • proposed_end_time_type enum
ONE of the following:
  • proposed_spending_limit_micros int64
  • proposed_spending_limit_type enum
amount_served_micros int64
The value of Ads that have been served, in micros. This includes overdelivery costs, in which case a credit might be automatically applied to the budget (see total_adjustments_micros).
approved_start_date_time string
The approved start time of the account-level budget in yyyy-MM-dd HH:mm:ss format. For example, if a new budget is approved after the proposed start time, the approved start time is the time of approval.
billing_setup string
The resource name of the billing setup associated with this account-level budget. BillingSetup resource names have the form: customers/{customer_id}/billingSetups/{billing_setup_id}
id int64
The ID of the account-level budget.
name string
The name of the account-level budget.
notes string
Notes associated with the budget.
pending_proposal object
account_budget_proposal string
The resource name of the proposal. AccountBudgetProposal resource names have the form: customers/{customer_id}/accountBudgetProposals/{account_budget_proposal_id}
creation_date_time string
The time when this account-level budget proposal was created. Formatted as yyyy-MM-dd HH:mm:ss.
end_date_time string
The end time in yyyy-MM-dd HH:mm:ss format.
end_time_type enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • NOW (2)
    As soon as possible.
  • FOREVER (3)
    An infinite point in the future.
The end time as a well-defined type, e.g. FOREVER.
name string
The name to assign to the account-level budget.
notes string
Notes associated with this budget.
proposal_type enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CREATE (2)
    Identifies a request to create a new budget.
  • UPDATE (3)
    Identifies a request to edit an existing budget.
  • END (4)
    Identifies a request to end a budget that has already started.
  • REMOVE (5)
    Identifies a request to remove a budget that hasn't started yet.
The type of this proposal, e.g. END to end the budget associated with this proposal.
purchase_order_number string
A purchase order number is a value that helps users reference this budget in their monthly invoices.
spending_limit_micros int64
The spending limit in micros. One million is equivalent to one unit.
spending_limit_type enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • INFINITE (2)
    Infinite, indicates unlimited spending power.
The spending limit as a well-defined type, e.g. INFINITE.
start_date_time string
The start time in yyyy-MM-dd HH:mm:ss format.
proposed_start_date_time string
The proposed start time of the account-level budget in yyyy-MM-dd HH:mm:ss format. If a start time type of NOW was proposed, this is the time of request.
purchase_order_number string
A purchase order number is a value that helps users reference this budget in their monthly invoices.
resource_name string
The resource name of the account-level budget. AccountBudget resource names have the form: customers/{customer_id}/accountBudgets/{account_budget_id}
status enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • PENDING (2)
    The account budget is pending approval.
  • APPROVED (3)
    The account budget has been approved.
  • CANCELLED (4)
    The account budget has been cancelled by the user.
The status of this account-level budget.
total_adjustments_micros int64
The total adjustments amount. An example of an adjustment is courtesy credits.
// Example AccountBudget
const account_budget = {
  adjusted_spending_limit_type: 2,
  amount_served_micros: 118743720000,
  approved_end_time_type: 3,
  approved_spending_limit_type: 2,
  approved_start_date_time: '2017-01-01 12:22:14',
  billing_setup: 'customers/3827277046/billingSetups/295854200',
  id: 295854560,
  name: '',
  proposed_end_time_type: 3,
  proposed_spending_limit_type: 2,
  proposed_start_date_time: '2017-01-01 12:22:14',
  resource_name: 'customers/3827277046/accountBudgets/295854560',
  status: 3,
  total_adjustments_micros: 870720000,
}

Get an AccountBudget

The customer.accountBudgets.get(resource_name) method returns the AccountBudget identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AccountBudget

Returns

Returns that AccountBudget as an object.

// Getting the entity
let result = await customer.accountBudgets.get('customers/3827277046/accountBudgets/295854560')
// Example result
;({
  adjusted_spending_limit_type: 2,
  amount_served_micros: 118743720000,
  approved_end_time_type: 3,
  approved_spending_limit_type: 2,
  approved_start_date_time: '2017-01-01 12:22:14',
  billing_setup: 'customers/3827277046/billingSetups/295854200',
  id: 295854560,
  name: '',
  proposed_end_time_type: 3,
  proposed_spending_limit_type: 2,
  proposed_start_date_time: '2017-01-01 12:22:14',
  resource_name: 'customers/3827277046/accountBudgets/295854560',
  status: 3,
  total_adjustments_micros: 870720000,
})

List every instance of AccountBudget

The customer.accountBudgets.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AccountBudget.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a account_budget property. Any other resources that can be selected with account_budget will also be added as properities.

// Listing all the accountBudgets in the account
let result = await customer.accountBudgets.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.accountBudgets.list({
  constraints: [
    {
      key: 'account_budget.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'account_budget.some_field.sub_field',
})
// Example result
;[
  {
    account_budget: {
      adjusted_spending_limit_type: 2,
      amount_served_micros: 118743720000,
      approved_end_time_type: 3,
      approved_spending_limit_type: 2,
      approved_start_date_time: '2017-01-01 12:22:14',
      billing_setup: 'customers/3827277046/billingSetups/295854200',
      id: 295854560,
      name: '',
      proposed_end_time_type: 3,
      proposed_spending_limit_type: 2,
      proposed_start_date_time: '2017-01-01 12:22:14',
      resource_name: 'customers/3827277046/accountBudgets/295854560',
      status: 3,
      total_adjustments_micros: 870720000,
    },
    billing_setup: {
      end_time_type: 3,
      id: 295854200,
      payments_account: 'customers/3827277046/paymentsAccounts/2445-9502-2490-5474',
      payments_account_info: {
        payments_account_id: '2445-9502-2490-5474',
        payments_account_name: 'AdWords 382-727-7046',
        payments_profile_id: '4466-6664-9412',
        payments_profile_name: 'Opteo LTD',
      },
      resource_name: 'customers/3827277046/billingSetups/295854200',
      start_date_time: '2017-01-01 12:22:14',
      status: 4,
    },
    customer: {
      auto_tagging_enabled: true,
      call_reporting_setting: {
        call_conversion_action: 'customers/3827277046/conversionActions/179',
        call_conversion_reporting_enabled: true,
        call_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 875176189 },
      currency_code: 'GBP',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [5],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 875176189 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-875176189\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-875176189');\n</script>\n",
      },
      resource_name: 'customers/3827277046',
      test_account: false,
      time_zone: 'Europe/London',
    },
  },
]

AccountBudgetProposal

The AccountBudgetProposal object

Fields

ONE of the following:
  • approved_end_date_time string
  • approved_end_time_type enum
ONE of the following:
  • approved_spending_limit_micros int64
  • approved_spending_limit_type enum
ONE of the following:
  • proposed_end_date_time string
  • proposed_end_time_type enum
ONE of the following:
  • proposed_spending_limit_micros int64
  • proposed_spending_limit_type enum
ONE of the following:
  • proposed_start_date_time string
  • proposed_start_time_type enum
account_budget string
The resource name of the account-level budget associated with this proposal.
approval_date_time string
The date time when this account-level budget was approved, if applicable.
approved_start_date_time string
The approved start date time in yyyy-mm-dd hh:mm:ss format.
billing_setup string
The resource name of the billing setup associated with this proposal.
creation_date_time string
The date time when this account-level budget proposal was created, which is not the same as its approval date time, if applicable.
id int64
The ID of the proposal.
proposal_type enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CREATE (2)
    Identifies a request to create a new budget.
  • UPDATE (3)
    Identifies a request to edit an existing budget.
  • END (4)
    Identifies a request to end a budget that has already started.
  • REMOVE (5)
    Identifies a request to remove a budget that hasn't started yet.
The type of this proposal, e.g. END to end the budget associated with this proposal.
proposed_name string
The name to assign to the account-level budget.
proposed_notes string
Notes associated with this budget.
proposed_purchase_order_number string
A purchase order number is a value that enables the user to help them reference this budget in their monthly invoices.
resource_name string
The resource name of the proposal. AccountBudgetProposal resource names have the form: customers/{customer_id}/accountBudgetProposals/{account_budget_proposal_id}
status enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • PENDING (2)
    The proposal is pending approval.
  • APPROVED_HELD (3)
    The proposal has been approved but the corresponding billing setup has not. This can occur for proposals that set up the first budget when signing up for billing or when performing a change of bill-to operation.
  • APPROVED (4)
    The proposal has been approved.
  • CANCELLED (5)
    The proposal has been cancelled by the user.
  • REJECTED (6)
    The proposal has been rejected by the user, e.g. by rejecting an acceptance email.
The status of this proposal. When a new proposal is created, the status defaults to PENDING.
// Example AccountBudgetProposal
const account_budget_proposal = {
  account_budget: 'customers/3827277046/accountBudgets/295854560',
  approval_date_time: '2017-01-01 12:25:18',
  approved_end_time_type: 3,
  approved_spending_limit_type: 2,
  approved_start_date_time: '2017-01-01 12:22:14',
  billing_setup: 'customers/3827277046/billingSetups/295854200',
  creation_date_time: '2017-01-01 12:25:18',
  id: 265265547,
  proposed_end_time_type: 3,
  proposed_name: '',
  proposed_spending_limit_type: 2,
  proposed_start_date_time: '2017-01-01 12:22:14',
  resource_name: 'customers/3827277046/accountBudgetProposals/265265547',
  status: 4,
}

Get an AccountBudgetProposal

The customer.accountBudgetProposals.get(resource_name) method returns the AccountBudgetProposal identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AccountBudgetProposal

Returns

Returns that AccountBudgetProposal as an object.

// Getting the entity
let result = await customer.accountBudgetProposals.get('customers/3827277046/accountBudgetProposals/265265547')
// Example result
;({
  account_budget: 'customers/3827277046/accountBudgets/295854560',
  approval_date_time: '2017-01-01 12:25:18',
  approved_end_time_type: 3,
  approved_spending_limit_type: 2,
  approved_start_date_time: '2017-01-01 12:22:14',
  billing_setup: 'customers/3827277046/billingSetups/295854200',
  creation_date_time: '2017-01-01 12:25:18',
  id: 265265547,
  proposed_end_time_type: 3,
  proposed_name: '',
  proposed_spending_limit_type: 2,
  proposed_start_date_time: '2017-01-01 12:22:14',
  resource_name: 'customers/3827277046/accountBudgetProposals/265265547',
  status: 4,
})

List every instance of AccountBudgetProposal

The customer.accountBudgetProposals.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AccountBudgetProposal.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a account_budget_proposal property. Any other resources that can be selected with account_budget_proposal will also be added as properities.

// Listing all the accountBudgetProposals in the account
let result = await customer.accountBudgetProposals.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.accountBudgetProposals.list({
  constraints: [
    {
      key: 'account_budget_proposal.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'account_budget_proposal.some_field.sub_field',
})
// Example result
;[
  {
    account_budget_proposal: {
      account_budget: 'customers/3827277046/accountBudgets/295854560',
      approval_date_time: '2017-01-01 12:25:18',
      approved_end_time_type: 3,
      approved_spending_limit_type: 2,
      approved_start_date_time: '2017-01-01 12:22:14',
      billing_setup: 'customers/3827277046/billingSetups/295854200',
      creation_date_time: '2017-01-01 12:25:18',
      id: 265265547,
      proposed_end_time_type: 3,
      proposed_name: '',
      proposed_spending_limit_type: 2,
      proposed_start_date_time: '2017-01-01 12:22:14',
      resource_name: 'customers/3827277046/accountBudgetProposals/265265547',
      status: 4,
    },
    billing_setup: {
      end_time_type: 3,
      id: 295854200,
      payments_account: 'customers/3827277046/paymentsAccounts/2445-9502-2490-5474',
      payments_account_info: {
        payments_account_id: '2445-9502-2490-5474',
        payments_account_name: 'AdWords 382-727-7046',
        payments_profile_id: '4466-6664-9412',
        payments_profile_name: 'Opteo LTD',
      },
      resource_name: 'customers/3827277046/billingSetups/295854200',
      start_date_time: '2017-01-01 12:22:14',
      status: 4,
    },
    customer: {
      auto_tagging_enabled: true,
      call_reporting_setting: {
        call_conversion_action: 'customers/3827277046/conversionActions/179',
        call_conversion_reporting_enabled: true,
        call_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 875176189 },
      currency_code: 'GBP',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [5],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 875176189 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-875176189\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-875176189');\n</script>\n",
      },
      resource_name: 'customers/3827277046',
      test_account: false,
      time_zone: 'Europe/London',
    },
  },
]

Create an AccountBudgetProposal

The customer.accountBudgetProposals.create(account_budget_proposal) method makes a new AccountBudgetProposal in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AccountBudgetProposal object or array of objects.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names created.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Creating the entity

const account_budget_proposal = {
  // Your AccountBudgetProposal here, without immutable fields such as resource_name
}

// Passing in a single entity to create
const result = await customer.accountBudgetProposals.create(account_budget_proposal)

// Passing in an array of entities to create, validating only
const result = await customer.accountBudgetProposals.create([account_budget_proposal, other_account_budget_proposal], {
  validate_only: true,
})
// Example result
{
	results : ['customers/3827277046/accountBudgetProposals/265265547'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AccountBudgetProposal

The customer.accountBudgetProposals.update(account_budget_proposal) method changes the attributes of an existing accountBudgetProposals in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AccountBudgetProposal object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const account_budget_proposal = {
  resource_name: 'customers/3827277046/accountBudgetProposals/265265547', // The resource_name is required
  // ...any other fields that you would like to update
}

// Passing in a single entity to update
const result = await customer.accountBudgetProposals.update(account_budget_proposal)

// Passing in an array of entities to update, validating only
const result = await customer.accountBudgetProposals.update([account_budget_proposal, other_account_budget_proposal], {
  validate_only: true,
})
// Example result
{
	results : ['customers/3827277046/accountBudgetProposals/265265547'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AccountBudgetProposal

The customer.accountBudgetProposals.delete(resource_name) sets the status field of an AccountBudgetProposal to REMOVED. Those entities and their metrics will continue to exist, but they will be read-only. Removed entities cannot be re-enabled.

Arguments

  • resource_name required

    The resource_name of that AccountBudgetProposal

Returns

Nothing

// Deleting the entity

await customer.accountBudgetProposals.delete('customers/3827277046/accountBudgetProposals/265265547')

Get an Ad

The customer.ads.get(resource_name) method returns the Ad identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that Ad

Returns

Returns that Ad as an object.

// Getting the entity
let result = await customer.ads.get('customers/9262111890/ads/284706472002')
// Example result
;({
    added_by_google_ads: false,
    display_url: '',
    expanded_text_ad: {
        description: 'my description here',
        headline_part1: 'headline part 1 here',
        headline_part2: 'headline part 2 here',
        path1: 'path one here',
        path2: 'path two here',
    },
    final_app_urls: [],
    final_mobile_urls: [],
    final_urls: ['http://hello.com'],
    id: 284706472002,
    resource_name: 'customers/9262111890/ads/284706472002',
    type: 3,
    url_collections: [],
    url_custom_parameters: [],
})

Update an Ad

The customer.ads.update(ad) method changes the attributes of an existing ad in an account. It also supports an array as its first agument for batch operations. Updating an ad using this method will not reset its metrics.

Arguments

  • entity required

    The Ad object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const ad = {
    resource_name: 'customers/1234567890/ads/123123123', // The resource_name is required
    final_urls : ['https://updated-url.com']
    expanded_text_ad: {
        headline_part1: 'updated headline here',
    },
}

// Passing in a single entity to update
const result = await customer.ads.update(ad)

// Passing in an array of entities to update, validating only
const result = await customer.ads.update([ad, other_ad], {
    validate_only: true,
})
// Example result
{
	results : ['customers/1234567890/ads/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

AdGroup

The AdGroup object

Fields

ad_rotation_mode enum
  • UNSPECIFIED (0)
    The ad rotation mode has not been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • OPTIMIZE (2)
    Optimize ad group ads based on clicks or conversions.
  • ROTATE_FOREVER (3)
    Rotate evenly forever.
The ad rotation mode of the ad group.
base_ad_group string
For draft or experiment ad groups, this field is the resource name of the base ad group from which this ad group was created. If a draft or experiment ad group does not have a base ad group, then this field is null. For base ad groups, this field equals the ad group resource name. This field is read-only.
campaign string
The campaign to which the ad group belongs.
cpc_bid_micros int64
The maximum CPC (cost-per-click) bid.
cpm_bid_micros int64
The maximum CPM (cost-per-thousand viewable impressions) bid.
cpv_bid_micros int64
The CPV (cost-per-view) bid.
display_custom_bid_dimension enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • KEYWORD (2)
    Keyword criteria, e.g. 'mars cruise'. KEYWORD may be used as a custom bid dimension. Keywords are always a targeting dimension, so may not be set as a target "ALL" dimension with TargetRestriction.
  • AUDIENCE (3)
    Audience criteria, which include user list, user interest, custom affinity, and custom in market.
  • TOPIC (4)
    Topic criteria for targeting categories of content, e.g. 'category::Animals>Pets' Used for Display and Video targeting.
  • GENDER (5)
    Criteria for targeting gender.
  • AGE_RANGE (6)
    Criteria for targeting age ranges.
  • PLACEMENT (7)
    Placement criteria, which include websites like 'www.flowers4sale.com', as well as mobile applications, mobile app categories, YouTube videos, and YouTube channels.
  • PARENTAL_STATUS (8)
    Criteria for parental status targeting.
  • INCOME_RANGE (9)
    Criteria for income range targeting.
Allows advertisers to specify a targeting dimension on which to place absolute bids. This is only applicable for campaigns that target only the display network and not search.
effective_target_cpa_micros int64
The effective target CPA (cost-per-acquisition). This field is read-only.
effective_target_cpa_source enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (2)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (3)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (4)
    The bid or target is defined on the ad group criterion.
Source of the effective target CPA. This field is read-only.
effective_target_roas double
The effective target ROAS (return-on-ad-spend). This field is read-only.
effective_target_roas_source enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (2)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (3)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (4)
    The bid or target is defined on the ad group criterion.
Source of the effective target ROAS. This field is read-only.
explorer_auto_optimizer_setting object
opt_in boolean
Indicates whether the optimizer is turned on.
final_url_suffix string
URL template for appending params to Final URL.
id int64
The ID of the ad group.
labels array
The resource names of labels attached to this ad group.
name string
The name of the ad group. This field is required and should not be empty when creating new ad groups. It must contain fewer than 255 UTF-8 full-width characters. It must not contain any null (code point 0x0), NL line feed (code point 0xA) or carriage return (code point 0xD) characters.
percent_cpc_bid_micros int64
The percent cpc bid amount, expressed as a fraction of the advertised price for some good or service. The valid range for the fraction is [0,1) and the value stored here is 1,000,000 * [fraction].
resource_name string
The resource name of the ad group. Ad group resource names have the form: customers/{customer_id}/adGroups/{ad_group_id}
status enum
  • UNSPECIFIED (0)
    The status has not been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • ENABLED (2)
    The ad group is enabled.
  • PAUSED (3)
    The ad group is paused.
  • REMOVED (4)
    The ad group is removed.
The status of the ad group.
target_cpa_micros int64
The target CPA (cost-per-acquisition).
target_cpm_micros int64
Average amount in micros that the advertiser is willing to pay for every thousand times the ad is shown.
target_roas double
The target ROAS (return-on-ad-spend) override. If the ad group's campaign bidding strategy is a standard Target ROAS strategy, then this field overrides the target ROAS specified in the campaign's bidding strategy. Otherwise, this value is ignored.
targeting_setting object
target_restrictions array
The per-targeting-dimension setting to restrict the reach of your campaign or ad group.
tracking_url_template string
The URL template for constructing a tracking URL.
type enum
  • UNSPECIFIED (0)
    The type has not been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • SEARCH_STANDARD (2)
    The default ad group type for Search campaigns.
  • DISPLAY_STANDARD (3)
    The default ad group type for Display campaigns.
  • SHOPPING_PRODUCT_ADS (4)
    The ad group type for Shopping campaigns serving standard product ads.
  • HOTEL_ADS (5)
    The default ad group type for Hotel campaigns.
  • SHOPPING_SMART_ADS (6)
    The type for ad groups in Smart Shopping campaigns.
  • VIDEO_BUMPER (7)
    Short unskippable in-stream video ads.
  • VIDEO_TRUE_VIEW_IN_STREAM (8)
    TrueView (skippable) in-stream video ads.
  • VIDEO_TRUE_VIEW_IN_DISPLAY (9)
    TrueView in-display video ads.
  • VIDEO_NON_SKIPPABLE_IN_STREAM (10)
    Unskippable in-stream video ads.
  • VIDEO_OUTSTREAM (11)
    Outstream video ads.
  • SEARCH_DYNAMIC_ADS (12)
    Ad group type for Dynamic Search Ads ad groups.
  • SHOPPING_COMPARISON_LISTING_ADS (13)
    The type for ad groups in Shopping Comparison Listing campaigns.
The type of the ad group.
url_custom_parameters array
The list of mappings used to substitute custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls.
// Example AdGroup
const ad_group = {
  base_ad_group: 'customers/9262111890/adGroups/60937781178',
  campaign: 'customers/9262111890/campaigns/1485014801',
  cpc_bid_micros: 1000000,
  cpm_bid_micros: 10000,
  cpv_bid_micros: 0,
  effective_target_cpa_micros: 0,
  id: 60937781178,
  labels: [],
  name: 'My ad group',
  resource_name: 'customers/9262111890/adGroups/60937781178',
  status: 4,
  target_cpa_micros: 0,
  targeting_setting: {
    target_restrictions: [
      { targetingDimension: 5, bidOnly: true },
      { targetingDimension: 6, bidOnly: true },
      { targetingDimension: 8, bidOnly: true },
      { targetingDimension: 9, bidOnly: true },
    ],
  },
  type: 2,
  url_custom_parameters: [],
}

Get an AdGroup

The customer.adGroups.get(resource_name) method returns the AdGroup identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroup

Returns

Returns that AdGroup as an object.

// Getting the entity
let result = await customer.adGroups.get('customers/9262111890/adGroups/60937781178')
// Example result
;({
  base_ad_group: 'customers/9262111890/adGroups/60937781178',
  campaign: 'customers/9262111890/campaigns/1485014801',
  cpc_bid_micros: 1000000,
  cpm_bid_micros: 10000,
  cpv_bid_micros: 0,
  effective_target_cpa_micros: 0,
  id: 60937781178,
  labels: [],
  name: 'My ad group',
  resource_name: 'customers/9262111890/adGroups/60937781178',
  status: 4,
  target_cpa_micros: 0,
  targeting_setting: {
    target_restrictions: [
      { targetingDimension: 5, bidOnly: true },
      { targetingDimension: 6, bidOnly: true },
      { targetingDimension: 8, bidOnly: true },
      { targetingDimension: 9, bidOnly: true },
    ],
  },
  type: 2,
  url_custom_parameters: [],
})

List every instance of AdGroup

The customer.adGroups.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroup.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group property. Any other resources that can be selected with ad_group will also be added as properities.

// Listing all the adGroups in the account
let result = await customer.adGroups.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroups.list({
  constraints: [
    {
      key: 'ad_group.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group.some_field.sub_field',
})
// Example result
;[
  {
    ad_group: {
      base_ad_group: 'customers/9262111890/adGroups/60937781178',
      campaign: 'customers/9262111890/campaigns/1485014801',
      cpc_bid_micros: 1000000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      effective_target_cpa_micros: 0,
      id: 60937781178,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/9262111890/adGroups/60937781178',
      status: 4,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { targetingDimension: 5, bidOnly: true },
          { targetingDimension: 6, bidOnly: true },
          { targetingDimension: 8, bidOnly: true },
          { targetingDimension: 9, bidOnly: true },
        ],
      },
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_type: 2,
      base_campaign: 'customers/9262111890/campaigns/1485014801',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/9262111890/campaignBudgets/1548344372',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 5 },
      id: 1485014801,
      labels: [],
      name: 'My campaign',
      network_settings: {
        target_content_network: true,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: true,
      },
      payment_mode: 4,
      resource_name: 'customers/9262111890/campaigns/1485014801',
      selective_optimization: { conversion_actions: [] },
      serving_status: 2,
      start_date: '2018-07-24',
      status: 2,
      target_spend: { cpc_bid_ceiling_micros: 1000000 },
      url_custom_parameters: [],
    },
    customer: {
      auto_tagging_enabled: false,
      call_reporting_setting: {
        call_conversion_action: 'customers/9262111890/conversionActions/179',
        call_conversion_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 797556569 },
      currency_code: 'EUR',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 9262111890,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [8, 2],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 797556569 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-797556569\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-797556569');\n</script>\n",
      },
      resource_name: 'customers/9262111890',
      test_account: true,
      time_zone: 'Europe/London',
    },
  },
]

Create an AdGroup

The customer.adGroups.create(ad_group) method makes a new AdGroup in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroup object or array of objects.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names created.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Creating the entity

const ad_group = {
  // Your AdGroup here, without immutable fields such as resource_name
}

// Passing in a single entity to create
const result = await customer.adGroups.create(ad_group)

// Passing in an array of entities to create, validating only
const result = await customer.adGroups.create([ad_group, other_ad_group], {
  validate_only: true,
})
// Example result
{
	results : ['customers/9262111890/adGroups/60937781178'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroup

The customer.adGroups.update(ad_group) method changes the attributes of an existing adGroups in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroup object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const ad_group = {
  resource_name: 'customers/9262111890/adGroups/60937781178', // The resource_name is required
  // ...any other fields that you would like to update
}

// Passing in a single entity to update
const result = await customer.adGroups.update(ad_group)

// Passing in an array of entities to update, validating only
const result = await customer.adGroups.update([ad_group, other_ad_group], {
  validate_only: true,
})
// Example result
{
	results : ['customers/9262111890/adGroups/60937781178'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroup

The customer.adGroups.delete(resource_name) sets the status field of an AdGroup to REMOVED. Those entities and their metrics will continue to exist, but they will be read-only. Removed entities cannot be re-enabled.

Arguments

  • resource_name required

    The resource_name of that AdGroup

Returns

Nothing

// Deleting the entity

await customer.adGroups.delete('customers/9262111890/adGroups/60937781178')

AdGroupAd

The AdGroupAd object

Fields

ad object
ONE of the following:
  • app_ad object
  • app_engagement_ad object
  • call_only_ad object
  • display_upload_ad object
  • expanded_dynamic_search_ad object
  • expanded_text_ad object
  • gmail_ad object
  • hotel_ad object
  • image_ad object
  • legacy_app_install_ad object
  • legacy_responsive_display_ad object
  • responsive_display_ad object
  • responsive_search_ad object
  • shopping_comparison_listing_ad object
  • shopping_product_ad object
  • shopping_smart_ad object
  • text_ad object
  • video_ad object
added_by_google_ads boolean
Indicates if this ad was automatically added by Google Ads and not by a user. For example, this could happen when ads are automatically created as suggestions for new ads based on knowledge of how existing ads are performing.
device_preference enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    The value is unknown in this version.
  • MOBILE (2)
    Mobile devices with full browsers.
  • TABLET (3)
    Tablets with full browsers.
  • DESKTOP (4)
    Computers.
  • CONNECTED_TV (5)
    Smart TVs and game consoles.
  • OTHER (6)
    Other device types.
The device preference for the ad. You can only specify a preference for mobile devices. When this preference is set the ad will be preferred over other ads when being displayed on a mobile device. The ad can still be displayed on other device types, e.g. if no other ads are available. If unspecified (no device preference), all devices are targeted. This is only supported by some ad types.
display_url string
The URL that appears in the ad description for some ad formats.
final_app_urls array
A list of final app URLs that will be used on mobile if the user has the specific app installed.
final_mobile_urls array
The list of possible final mobile URLs after all cross-domain redirects for the ad.
final_urls array
The list of possible final URLs after all cross-domain redirects for the ad.
id int64
The ID of the ad.
name string
The name of the ad. This is only used to be able to identify the ad. It does not need to be unique and does not affect the served ad.
resource_name string
The resource name of the ad. Ad resource names have the form: customers/{customer_id}/ads/{ad_id}
system_managed_resource_source enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • AD_VARIATIONS (2)
    Generated ad variations experiment ad.
If this ad is system managed, then this field will indicate the source. This field is read-only.
tracking_url_template string
The URL template for constructing a tracking URL.
type enum
  • UNSPECIFIED (0)
    No value has been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • TEXT_AD (2)
    The ad is a text ad.
  • EXPANDED_TEXT_AD (3)
    The ad is an expanded text ad.
  • CALL_ONLY_AD (4)
    The ad is a call only ad.
  • EXPANDED_DYNAMIC_SEARCH_AD (5)
    The ad is an expanded dynamic search ad.
  • HOTEL_AD (6)
    The ad is a hotel ad.
  • SHOPPING_SMART_AD (7)
    The ad is a Smart Shopping ad.
  • SHOPPING_PRODUCT_AD (8)
    The ad is a standard Shopping ad.
  • VIDEO_AD (9)
    The ad is a video ad.
  • GMAIL_AD (10)
    This ad is a Gmail ad.
  • IMAGE_AD (11)
    This ad is an Image ad.
  • RESPONSIVE_SEARCH_AD (12)
    The ad is a responsive search ad.
  • LEGACY_RESPONSIVE_DISPLAY_AD (13)
    The ad is a legacy responsive display ad.
  • APP_AD (14)
    The ad is an app ad.
  • LEGACY_APP_INSTALL_AD (15)
    The ad is a legacy app install ad.
  • RESPONSIVE_DISPLAY_AD (16)
    The ad is a responsive display ad.
  • HTML5_UPLOAD_AD (17)
    The ad is a display upload ad with the HTML5_UPLOAD_AD product type.
  • DYNAMIC_HTML5_AD (18)
    The ad is a display upload ad with one of the DYNAMIC_HTML5_* product types.
  • APP_ENGAGEMENT_AD (19)
    The ad is an app engagement ad.
  • SHOPPING_COMPARISON_LISTING_AD (20)
    The ad is a Shopping Comparison Listing ad.
The type of ad.
url_collections array
Additional URLs for the ad that are tagged with a unique identifier that can be referenced from other fields in the ad.
url_custom_parameters array
The list of mappings that can be used to substitute custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls.
ad_group string
The ad group to which the ad belongs.
ad_strength enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • PENDING (2)
    The ad strength is currently pending.
  • NO_ADS (3)
    No ads could be generated.
  • POOR (4)
    Poor strength.
  • AVERAGE (5)
    Average strength.
  • GOOD (6)
    Good strength.
  • EXCELLENT (7)
    Excellent strength.
Overall ad strength for this ad group ad.
policy_summary object
approval_status enum
  • UNSPECIFIED (0)
    No value has been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • DISAPPROVED (2)
    Will not serve.
  • APPROVED_LIMITED (3)
    Serves with restrictions.
  • APPROVED (4)
    Serves without restrictions.
  • AREA_OF_INTEREST_ONLY (5)
    Will not serve in targeted countries, but may serve for users who are searching for information about the targeted countries.
The overall approval status of this ad, calculated based on the status of its individual policy topic entries.
policy_topic_entries array
The list of policy findings for this ad.
review_status enum
  • UNSPECIFIED (0)
    No value has been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • REVIEW_IN_PROGRESS (2)
    Currently under review.
  • REVIEWED (3)
    Primary review complete. Other reviews may be continuing.
  • UNDER_APPEAL (4)
    The resource has been resubmitted for approval or its policy decision has been appealed.
Where in the review process this ad is.
resource_name string
The resource name of the ad. Ad group ad resource names have the form: customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}
status enum
  • UNSPECIFIED (0)
    No value has been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • ENABLED (2)
    The ad group ad is enabled.
  • PAUSED (3)
    The ad group ad is paused.
  • REMOVED (4)
    The ad group ad is removed.
The status of the ad.
// Example AdGroupAd
const ad_group_ad = {
  ad: {
    added_by_google_ads: false,
    display_url: '',
    expanded_text_ad: {
      description: 'my description here2',
      headline_part1: 'headline part 1 here2',
      headline_part2: 'headline part 2 here2',
      path1: 'path one here2',
      path2: 'path two here2',
    },
    final_app_urls: [],
    final_mobile_urls: [],
    final_urls: ['http://hello.com'],
    id: 284706472002,
    resource_name: 'customers/9262111890/ads/284706472002',
    type: 3,
    url_collections: [],
    url_custom_parameters: [],
  },
  ad_group: 'customers/9262111890/adGroups/56328868446',
  resource_name: 'customers/9262111890/adGroupAds/56328868446~284706472002',
  status: 2,
}

Get an AdGroupAd

The customer.adGroupAds.get(resource_name) method returns the AdGroupAd identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroupAd

Returns

Returns that AdGroupAd as an object.

// Getting the entity
let result = await customer.adGroupAds.get('customers/9262111890/adGroupAds/56328868446~284706472002')
// Example result
;({
  ad: {
    added_by_google_ads: false,
    display_url: '',
    expanded_text_ad: {
      description: 'my description here2',
      headline_part1: 'headline part 1 here2',
      headline_part2: 'headline part 2 here2',
      path1: 'path one here2',
      path2: 'path two here2',
    },
    final_app_urls: [],
    final_mobile_urls: [],
    final_urls: ['http://hello.com'],
    id: 284706472002,
    resource_name: 'customers/9262111890/ads/284706472002',
    type: 3,
    url_collections: [],
    url_custom_parameters: [],
  },
  ad_group: 'customers/9262111890/adGroups/56328868446',
  resource_name: 'customers/9262111890/adGroupAds/56328868446~284706472002',
  status: 2,
})

List every instance of AdGroupAd

The customer.adGroupAds.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroupAd.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group_ad property. Any other resources that can be selected with ad_group_ad will also be added as properities.

// Listing all the adGroupAds in the account
let result = await customer.adGroupAds.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupAds.list({
  constraints: [
    {
      key: 'ad_group_ad.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_ad.some_field.sub_field',
})
// Example result
;[
  {
    ad_group_ad: {
      ad: {
        added_by_google_ads: false,
        display_url: '',
        expanded_text_ad: {
          description: 'my description here2',
          headline_part1: 'headline part 1 here2',
          headline_part2: 'headline part 2 here2',
          path1: 'path one here2',
          path2: 'path two here2',
        },
        final_app_urls: [],
        final_mobile_urls: [],
        final_urls: ['http://hello.com'],
        id: 284706472002,
        resource_name: 'customers/9262111890/ads/284706472002',
        type: 3,
        url_collections: [],
        url_custom_parameters: [],
      },
      ad_group: 'customers/9262111890/adGroups/56328868446',
      resource_name: 'customers/9262111890/adGroupAds/56328868446~284706472002',
      status: 2,
    },
    ad_group: {
      base_ad_group: 'customers/9262111890/adGroups/56328868446',
      campaign: 'customers/9262111890/campaigns/1485014801',
      cpc_bid_micros: 1000000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      effective_target_cpa_micros: 0,
      id: 56328868446,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/9262111890/adGroups/56328868446',
      status: 2,
      target_cpa_micros: 0,
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_type: 2,
      base_campaign: 'customers/9262111890/campaigns/1485014801',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/9262111890/campaignBudgets/1548344372',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 5 },
      id: 1485014801,
      labels: [],
      name: 'My campaign',
      network_settings: {
        target_content_network: true,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: true,
      },
      payment_mode: 4,
      resource_name: 'customers/9262111890/campaigns/1485014801',
      selective_optimization: { conversion_actions: [] },
      serving_status: 2,
      start_date: '2018-07-24',
      status: 2,
      target_spend: { cpc_bid_ceiling_micros: 1000000 },
      url_custom_parameters: [],
    },
    customer: {
      auto_tagging_enabled: false,
      call_reporting_setting: {
        call_conversion_action: 'customers/9262111890/conversionActions/179',
        call_conversion_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 797556569 },
      currency_code: 'EUR',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 9262111890,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [8, 2],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 797556569 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-797556569\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-797556569');\n</script>\n",
      },
      resource_name: 'customers/9262111890',
      test_account: true,
      time_zone: 'Europe/London',
    },
  },
]

Create an AdGroupAd

The customer.adGroupAds.create(ad_group_ad) method makes a new AdGroupAd in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupAd object or array of objects.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names created.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Creating the entity

const ad_group_ad = {
  // Your AdGroupAd here, without immutable fields such as resource_name
}

// Passing in a single entity to create
const result = await customer.adGroupAds.create(ad_group_ad)

// Passing in an array of entities to create, validating only
const result = await customer.adGroupAds.create([ad_group_ad, other_ad_group_ad], {
  validate_only: true,
})
// Example result
{
	results : ['customers/9262111890/adGroupAds/56328868446~284706472002'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupAd

The customer.adGroupAds.update(ad_group_ad) method changes the attributes of an existing adGroupAds in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupAd object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const ad_group_ad = {
  resource_name: 'customers/9262111890/adGroupAds/56328868446~284706472002', // The resource_name is required
  // ...any other fields that you would like to update
}

// Passing in a single entity to update
const result = await customer.adGroupAds.update(ad_group_ad)

// Passing in an array of entities to update, validating only
const result = await customer.adGroupAds.update([ad_group_ad, other_ad_group_ad], {
  validate_only: true,
})
// Example result
{
	results : ['customers/9262111890/adGroupAds/56328868446~284706472002'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupAd

The customer.adGroupAds.delete(resource_name) sets the status field of an AdGroupAd to REMOVED. Those entities and their metrics will continue to exist, but they will be read-only. Removed entities cannot be re-enabled.

Arguments

  • resource_name required

    The resource_name of that AdGroupAd

Returns

Nothing

// Deleting the entity

await customer.adGroupAds.delete('customers/9262111890/adGroupAds/56328868446~284706472002')

AdGroupAdLabel

The AdGroupAdLabel object

Fields

ad_group_ad string
The ad group ad to which the label is attached.
label string
The label assigned to the ad group ad.
resource_name string
The resource name of the ad group ad label. Ad group ad label resource names have the form: customers/{customer_id}/adGroupAdLabels/{ad_group_id}~{ad_id}~{label_id}
// Example AdGroupAdLabel
const ad_group_ad_label = {
  ad_group_ad: 'customers/3827277046/adGroupAds/37706041345~204347238383',
  label: 'customers/3827277046/labels/1285360183',
  resource_name: 'customers/3827277046/adGroupAdLabels/37706041345~204347238383~1285360183',
}

Get an AdGroupAdLabel

The customer.adGroupAdLabels.get(resource_name) method returns the AdGroupAdLabel identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroupAdLabel

Returns

Returns that AdGroupAdLabel as an object.

// Getting the entity
let result = await customer.adGroupAdLabels.get(
  'customers/3827277046/adGroupAdLabels/37706041345~204347238383~1285360183'
)
// Example result
;({
  ad_group_ad: 'customers/3827277046/adGroupAds/37706041345~204347238383',
  label: 'customers/3827277046/labels/1285360183',
  resource_name: 'customers/3827277046/adGroupAdLabels/37706041345~204347238383~1285360183',
})

List every instance of AdGroupAdLabel

The customer.adGroupAdLabels.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroupAdLabel.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group_ad_label property. Any other resources that can be selected with ad_group_ad_label will also be added as properities.

// Listing all the adGroupAdLabels in the account
let result = await customer.adGroupAdLabels.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupAdLabels.list({
  constraints: [
    {
      key: 'ad_group_ad_label.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_ad_label.some_field.sub_field',
})
// Example result
;[
  {
    ad_group_ad_label: {
      ad_group_ad: 'customers/3827277046/adGroupAds/37706041345~204347238383',
      label: 'customers/3827277046/labels/1285360183',
      resource_name: 'customers/3827277046/adGroupAdLabels/37706041345~204347238383~1285360183',
    },
    ad_group_ad: {
      ad: {
        added_by_google_ads: false,
        display_url: '',
        expanded_text_ad: {
          description: 'State Of The Art AdWords PPC Tool. Designed For Agencies. Try It Free!',
          headline_part1: 'Top Ad Words Tool',
          headline_part2: 'Modern Way To Manage Accounts',
          path1: 'ppc',
          path2: 'tool',
        },
        final_app_urls: [],
        final_mobile_urls: [],
        final_urls: ['http://opteo.co/lp/ad-words-software'],
        id: 204347238383,
        resource_name: 'customers/3827277046/ads/204347238383',
        type: 3,
        url_collections: [],
        url_custom_parameters: [],
      },
      ad_group: 'customers/3827277046/adGroups/37706041345',
      resource_name: 'customers/3827277046/adGroupAds/37706041345~204347238383',
      status: 4,
    },
    label: {
      id: 1285360183,
      name: 'My label',
      resource_name: 'customers/3827277046/labels/1285360183',
      status: 2,
      text_label: { background_color: '#336666', description: '' },
    },
    ad_group: {
      base_ad_group: 'customers/3827277046/adGroups/37706041345',
      campaign: 'customers/3827277046/campaigns/729684361',
      cpc_bid_micros: 4770000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      effective_target_cpa_micros: 0,
      explorer_auto_optimizer_setting: { opt_in: false },
      id: 37706041345,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/37706041345',
      status: 2,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { targetingDimension: 3, bidOnly: false },
          { targetingDimension: 4, bidOnly: false },
          { targetingDimension: 5, bidOnly: true },
          { targetingDimension: 6, bidOnly: false },
          { targetingDimension: 7, bidOnly: false },
          { targetingDimension: 8, bidOnly: false },
        ],
      },
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 4,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/729684361',
      bidding_strategy_type: 3,
      campaign_budget: 'customers/3827277046/campaignBudgets/1005523652',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 7 },
      id: 729684361,
      labels: [],
      manual_cpc: { enhanced_cpc_enabled: false },
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: true,
      },
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/729684361',
      selective_optimization: { conversion_actions: [] },
      serving_status: 2,
      start_date: '2017-01-04',
      status: 3,
      targeting_setting: { target_restrictions: [{ targetingDimension: 3, bidOnly: false }] },
      url_custom_parameters: [],
    },
    customer: {
      auto_tagging_enabled: true,
      call_reporting_setting: {
        call_conversion_action: 'customers/3827277046/conversionActions/179',
        call_conversion_reporting_enabled: true,
        call_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 875176189 },
      currency_code: 'GBP',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [5],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 875176189 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-875176189\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-875176189');\n</script>\n",
      },
      resource_name: 'customers/3827277046',
      test_account: false,
      time_zone: 'Europe/London',
    },
  },
]

Create an AdGroupAdLabel

The customer.adGroupAdLabels.create(ad_group_ad_label) method makes a new AdGroupAdLabel in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupAdLabel object or array of objects.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names created.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Creating the entity

const ad_group_ad_label = {
  // Your AdGroupAdLabel here, without immutable fields such as resource_name
}

// Passing in a single entity to create
const result = await customer.adGroupAdLabels.create(ad_group_ad_label)

// Passing in an array of entities to create, validating only
const result = await customer.adGroupAdLabels.create([ad_group_ad_label, other_ad_group_ad_label], {
  validate_only: true,
})
// Example result
{
	results : ['customers/3827277046/adGroupAdLabels/37706041345~204347238383~1285360183'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupAdLabel

The customer.adGroupAdLabels.update(ad_group_ad_label) method changes the attributes of an existing adGroupAdLabels in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupAdLabel object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const ad_group_ad_label = {
  resource_name: 'customers/3827277046/adGroupAdLabels/37706041345~204347238383~1285360183', // The resource_name is required
  // ...any other fields that you would like to update
}

// Passing in a single entity to update
const result = await customer.adGroupAdLabels.update(ad_group_ad_label)

// Passing in an array of entities to update, validating only
const result = await customer.adGroupAdLabels.update([ad_group_ad_label, other_ad_group_ad_label], {
  validate_only: true,
})
// Example result
{
	results : ['customers/3827277046/adGroupAdLabels/37706041345~204347238383~1285360183'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupAdLabel

The customer.adGroupAdLabels.delete(resource_name) sets the status field of an AdGroupAdLabel to REMOVED. Those entities and their metrics will continue to exist, but they will be read-only. Removed entities cannot be re-enabled.

Arguments

  • resource_name required

    The resource_name of that AdGroupAdLabel

Returns

Nothing

// Deleting the entity

await customer.adGroupAdLabels.delete('customers/3827277046/adGroupAdLabels/37706041345~204347238383~1285360183')

AdGroupBidModifier

The AdGroupBidModifier object

Fields

ONE of the following:
  • device object
  • hotel_advance_booking_window object
  • hotel_check_in_day object
  • hotel_date_selection_type object
  • hotel_length_of_stay object
  • preferred_content object
ad_group string
The ad group to which this criterion belongs.
base_ad_group string
The base ad group from which this draft/trial adgroup bid modifier was created. If ad_group is a base ad group then this field will be equal to ad_group. If the ad group was created in the draft or trial and has no corresponding base ad group, then this field will be null. This field is readonly.
bid_modifier double
The modifier for the bid when the criterion matches. The modifier must be in the range: 0.1 - 10.0. The range is 1.0 - 6.0 for PreferredContent. Use 0 to opt out of a Device type.
bid_modifier_source enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN (2)
    The bid modifier is specified at the campaign level, on the campaign level criterion.
  • AD_GROUP (3)
    The bid modifier is specified (overridden) at the ad group level.
Bid modifier source.
criterion_id int64
The ID of the criterion to bid modify. This field is ignored for mutates.
resource_name string
The resource name of the ad group bid modifier. Ad group bid modifier resource names have the form: customers/{customer_id}/adGroupBidModifiers/{ad_group_id}~{criterion_id}
// Example AdGroupBidModifier
const ad_group_bid_modifier = {
  ad_group: 'customers/9262111890/adGroups/57176985017',
  base_ad_group: 'customers/9262111890/adGroups/57176985017',
  criterion_id: 30000,
  device: { type: 4 },
  resource_name: 'customers/9262111890/adGroupBidModifiers/57176985017~30000',
}

Get an AdGroupBidModifier

The customer.adGroupBidModifiers.get(resource_name) method returns the AdGroupBidModifier identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroupBidModifier

Returns

Returns that AdGroupBidModifier as an object.

// Getting the entity
let result = await customer.adGroupBidModifiers.get('customers/9262111890/adGroupBidModifiers/57176985017~30000')
// Example result
;({
  ad_group: 'customers/9262111890/adGroups/57176985017',
  base_ad_group: 'customers/9262111890/adGroups/57176985017',
  criterion_id: 30000,
  device: { type: 4 },
  resource_name: 'customers/9262111890/adGroupBidModifiers/57176985017~30000',
})

List every instance of AdGroupBidModifier

The customer.adGroupBidModifiers.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroupBidModifier.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group_bid_modifier property. Any other resources that can be selected with ad_group_bid_modifier will also be added as properities.

// Listing all the adGroupBidModifiers in the account
let result = await customer.adGroupBidModifiers.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupBidModifiers.list({
  constraints: [
    {
      key: 'ad_group_bid_modifier.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_bid_modifier.some_field.sub_field',
})
// Example result
;[
  {
    ad_group_bid_modifier: {
      ad_group: 'customers/9262111890/adGroups/57176985017',
      base_ad_group: 'customers/9262111890/adGroups/57176985017',
      criterion_id: 30000,
      device: { type: 4 },
      resource_name: 'customers/9262111890/adGroupBidModifiers/57176985017~30000',
    },
    ad_group: {
      base_ad_group: 'customers/9262111890/adGroups/57176985017',
      campaign: 'customers/9262111890/campaigns/1485014801',
      cpc_bid_micros: 10000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      effective_target_cpa_micros: 0,
      id: 57176985017,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/9262111890/adGroups/57176985017',
      status: 4,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { targetingDimension: 5, bidOnly: true },
          { targetingDimension: 6, bidOnly: true },
          { targetingDimension: 8, bidOnly: true },
          { targetingDimension: 9, bidOnly: true },
        ],
      },
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_type: 2,
      base_campaign: 'customers/9262111890/campaigns/1485014801',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/9262111890/campaignBudgets/1548344372',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 5 },
      id: 1485014801,
      labels: [],
      name: 'My campaign',
      network_settings: {
        target_content_network: true,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: true,
      },
      payment_mode: 4,
      resource_name: 'customers/9262111890/campaigns/1485014801',
      selective_optimization: { conversion_actions: [] },
      serving_status: 2,
      start_date: '2018-07-24',
      status: 2,
      target_spend: { cpc_bid_ceiling_micros: 1000000 },
      url_custom_parameters: [],
    },
    customer: {
      auto_tagging_enabled: false,
      call_reporting_setting: {
        call_conversion_action: 'customers/9262111890/conversionActions/179',
        call_conversion_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 797556569 },
      currency_code: 'EUR',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 9262111890,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [8, 2],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 797556569 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-797556569\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-797556569');\n</script>\n",
      },
      resource_name: 'customers/9262111890',
      test_account: true,
      time_zone: 'Europe/London',
    },
  },
]

Create an AdGroupBidModifier

The customer.adGroupBidModifiers.create(ad_group_bid_modifier) method makes a new AdGroupBidModifier in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupBidModifier object or array of objects.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names created.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Creating the entity

const ad_group_bid_modifier = {
  // Your AdGroupBidModifier here, without immutable fields such as resource_name
}

// Passing in a single entity to create
const result = await customer.adGroupBidModifiers.create(ad_group_bid_modifier)

// Passing in an array of entities to create, validating only
const result = await customer.adGroupBidModifiers.create([ad_group_bid_modifier, other_ad_group_bid_modifier], {
  validate_only: true,
})
// Example result
{
	results : ['customers/9262111890/adGroupBidModifiers/57176985017~30000'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupBidModifier

The customer.adGroupBidModifiers.update(ad_group_bid_modifier) method changes the attributes of an existing adGroupBidModifiers in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupBidModifier object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const ad_group_bid_modifier = {
  resource_name: 'customers/9262111890/adGroupBidModifiers/57176985017~30000', // The resource_name is required
  // ...any other fields that you would like to update
}

// Passing in a single entity to update
const result = await customer.adGroupBidModifiers.update(ad_group_bid_modifier)

// Passing in an array of entities to update, validating only
const result = await customer.adGroupBidModifiers.update([ad_group_bid_modifier, other_ad_group_bid_modifier], {
  validate_only: true,
})
// Example result
{
	results : ['customers/9262111890/adGroupBidModifiers/57176985017~30000'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupBidModifier

The customer.adGroupBidModifiers.delete(resource_name) sets the status field of an AdGroupBidModifier to REMOVED. Those entities and their metrics will continue to exist, but they will be read-only. Removed entities cannot be re-enabled.

Arguments

  • resource_name required

    The resource_name of that AdGroupBidModifier

Returns

Nothing

// Deleting the entity

await customer.adGroupBidModifiers.delete('customers/9262111890/adGroupBidModifiers/57176985017~30000')

AdGroupCriterion

The AdGroupCriterion object

Fields

ONE of the following:
  • age_range object
  • app_payment_model object
  • custom_affinity object
  • custom_intent object
  • gender object
  • income_range object
  • keyword object
  • listing_group object
  • mobile_app_category object
  • mobile_application object
  • parental_status object
  • placement object
  • topic object
  • user_interest object
  • user_list object
  • webpage object
  • youtube_channel object
  • youtube_video object
ad_group string
The ad group to which the criterion belongs.
approval_status enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    The value is unknown in this version.
  • APPROVED (2)
    Approved.
  • DISAPPROVED (3)
    Disapproved.
  • PENDING_REVIEW (4)
    Pending Review.
  • UNDER_REVIEW (5)
    Under review.
Approval status of the criterion.
bid_modifier double
The modifier for the bid when the criterion matches. The modifier must be in the range: 0.1 - 10.0. Most targetable criteria types support modifiers.
cpc_bid_micros int64
The CPC (cost-per-click) bid.
cpm_bid_micros int64
The CPM (cost-per-thousand viewable impressions) bid.
cpv_bid_micros int64
The CPV (cost-per-view) bid.
criterion_id int64
The ID of the criterion. This field is ignored for mutates.
effective_cpc_bid_micros int64
The effective CPC (cost-per-click) bid.
effective_cpc_bid_source enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (2)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (3)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (4)
    The bid or target is defined on the ad group criterion.
Source of the effective CPC bid.
effective_cpm_bid_micros int64
The effective CPM (cost-per-thousand viewable impressions) bid.
effective_cpm_bid_source enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (2)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (3)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (4)
    The bid or target is defined on the ad group criterion.
Source of the effective CPM bid.
effective_cpv_bid_micros int64
The effective CPV (cost-per-view) bid.
effective_cpv_bid_source enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (2)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (3)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (4)
    The bid or target is defined on the ad group criterion.
Source of the effective CPV bid.
effective_percent_cpc_bid_micros int64
The effective Percent CPC bid amount.
effective_percent_cpc_bid_source enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (2)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (3)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (4)
    The bid or target is defined on the ad group criterion.
Source of the effective Percent CPC bid.
final_mobile_urls array
The list of possible final mobile URLs after all cross-domain redirects.
final_url_suffix string
URL template for appending params to final URL.
final_urls array
The list of possible final URLs after all cross-domain redirects for the ad.
negative boolean
Whether to target (false) or exclude (true) the criterion. This field is immutable. To switch a criterion from positive to negative, remove then re-add it.
percent_cpc_bid_micros int64
The CPC bid amount, expressed as a fraction of the advertised price for some good or service. The valid range for the fraction is [0,1) and the value stored here is 1,000,000 * [fraction].
position_estimates object
estimated_add_clicks_at_first_position_cpc int64
Estimate of how many clicks per week you might get by changing your keyword bid to the value in first_position_cpc_micros.
estimated_add_cost_at_first_position_cpc int64
Estimate of how your cost per week might change when changing your keyword bid to the value in first_position_cpc_micros.
first_page_cpc_micros int64
The estimate of the CPC bid required for ad to be shown on first page of search results.
first_position_cpc_micros int64
The estimate of the CPC bid required for ad to be displayed in first position, at the top of the first page of search results.
top_of_page_cpc_micros int64
The estimate of the CPC bid required for ad to be displayed at the top of the first page of search results.
quality_info object
creative_quality_score enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • BELOW_AVERAGE (2)
    Quality of the creative is below average.
  • AVERAGE (3)
    Quality of the creative is average.
  • ABOVE_AVERAGE (4)
    Quality of the creative is above average.
The performance of the ad compared to other advertisers.
post_click_quality_score enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • BELOW_AVERAGE (2)
    Quality of the creative is below average.
  • AVERAGE (3)
    Quality of the creative is average.
  • ABOVE_AVERAGE (4)
    Quality of the creative is above average.
The quality score of the landing page.
quality_score int32
The quality score. This field may not be populated if Google does not have enough information to determine a value.
search_predicted_ctr enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • BELOW_AVERAGE (2)
    Quality of the creative is below average.
  • AVERAGE (3)
    Quality of the creative is average.
  • ABOVE_AVERAGE (4)
    Quality of the creative is above average.
The click-through rate compared to that of other advertisers.
resource_name string
The resource name of the ad group criterion. Ad group criterion resource names have the form: customers/{customer_id}/adGroupCriteria/{ad_group_id}~{criterion_id}
status enum
  • UNSPECIFIED (0)
    No value has been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • ENABLED (2)
    The ad group criterion is enabled.
  • PAUSED (3)
    The ad group criterion is paused.
  • REMOVED (4)
    The ad group criterion is removed.
The status of the criterion.
system_serving_status enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    The value is unknown in this version.
  • ELIGIBLE (2)
    Eligible.
  • RARELY_SERVED (3)
    Low search volume.
Serving status of the criterion.
tracking_url_template string
The URL template for constructing a tracking URL.
type enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • KEYWORD (2)
    Keyword. e.g. 'mars cruise'.
  • PLACEMENT (3)
    Placement, aka Website. e.g. 'www.flowers4sale.com'
  • MOBILE_APP_CATEGORY (4)
    Mobile application categories to target.
  • MOBILE_APPLICATION (5)
    Mobile applications to target.
  • DEVICE (6)
    Devices to target.
  • LOCATION (7)
    Locations to target.
  • LISTING_GROUP (8)
    Listing groups to target.
  • AD_SCHEDULE (9)
    Ad Schedule.
  • AGE_RANGE (10)
    Age range.
  • GENDER (11)
    Gender.
  • INCOME_RANGE (12)
    Income Range.
  • PARENTAL_STATUS (13)
    Parental status.
  • YOUTUBE_VIDEO (14)
    YouTube Video.
  • YOUTUBE_CHANNEL (15)
    YouTube Channel.
  • USER_LIST (16)
    User list.
  • PROXIMITY (17)
    Proximity.
  • TOPIC (18)
    A topic target on the display network (e.g. "Pets & Animals").
  • LISTING_SCOPE (19)
    Listing scope to target.
  • LANGUAGE (20)
    Language.
  • IP_BLOCK (21)
    IpBlock.
  • CONTENT_LABEL (22)
    Content Label for category exclusion.
  • CARRIER (23)
    Carrier.
  • USER_INTEREST (24)
    A category the user is interested in.
  • WEBPAGE (25)
    Webpage criterion for dynamic search ads.
  • OPERATING_SYSTEM_VERSION (26)
    Operating system version.
  • APP_PAYMENT_MODEL (27)
    App payment model.
  • MOBILE_DEVICE (28)
    Mobile device.
  • CUSTOM_AFFINITY (29)
    Custom affinity.
  • CUSTOM_INTENT (30)
    Custom intent.
  • LOCATION_GROUP (31)
    Location group.
The type of the criterion.
url_custom_parameters array
The list of mappings used to substitute custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls.
// Example AdGroupCriterion
const ad_group_criterion = {
  ad_group: 'customers/9262111890/adGroups/60170225920',
  approval_status: 4,
  criterion_id: 521456008776,
  effective_cpc_bid_micros: 1000000,
  effective_cpc_bid_source: 6,
  effective_cpm_bid_micros: 10000,
  effective_cpm_bid_source: 6,
  final_mobile_urls: [],
  final_urls: [],
  keyword: { match_type: 4, text: 'test-keyword-478619' },
  negative: false,
  resource_name: 'customers/9262111890/adGroupCriteria/60170225920~521456008776',
  status: 3,
  system_serving_status: 3,
  type: 2,
  url_custom_parameters: [],
}

Get an AdGroupCriterion

The customer.adGroupCriteria.get(resource_name) method returns the AdGroupCriterion identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroupCriterion

Returns

Returns that AdGroupCriterion as an object.

// Getting the entity
let result = await customer.adGroupCriteria.get('customers/9262111890/adGroupCriteria/60170225920~521456008776')
// Example result
;({
  ad_group: 'customers/9262111890/adGroups/60170225920',
  approval_status: 4,
  criterion_id: 521456008776,
  effective_cpc_bid_micros: 1000000,
  effective_cpc_bid_source: 6,
  effective_cpm_bid_micros: 10000,
  effective_cpm_bid_source: 6,
  final_mobile_urls: [],
  final_urls: [],
  keyword: { match_type: 4, text: 'test-keyword-478619' },
  negative: false,
  resource_name: 'customers/9262111890/adGroupCriteria/60170225920~521456008776',
  status: 3,
  system_serving_status: 3,
  type: 2,
  url_custom_parameters: [],
})

List every instance of AdGroupCriterion

The customer.adGroupCriteria.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroupCriterion.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group_criterion property. Any other resources that can be selected with ad_group_criterion will also be added as properities.

// Listing all the adGroupCriteria in the account
let result = await customer.adGroupCriteria.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupCriteria.list({
  constraints: [
    {
      key: 'ad_group_criterion.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_criterion.some_field.sub_field',
})
// Example result
;[
  {
    ad_group_criterion: {
      ad_group: 'customers/9262111890/adGroups/60170225920',
      approval_status: 4,
      criterion_id: 521456008776,
      effective_cpc_bid_micros: 1000000,
      effective_cpc_bid_source: 6,
      effective_cpm_bid_micros: 10000,
      effective_cpm_bid_source: 6,
      final_mobile_urls: [],
      final_urls: [],
      keyword: { match_type: 4, text: 'test-keyword-478619' },
      negative: false,
      resource_name: 'customers/9262111890/adGroupCriteria/60170225920~521456008776',
      status: 3,
      system_serving_status: 3,
      type: 2,
      url_custom_parameters: [],
    },
    ad_group: {
      base_ad_group: 'customers/9262111890/adGroups/60170225920',
      campaign: 'customers/9262111890/campaigns/1485014801',
      cpc_bid_micros: 1000000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      effective_target_cpa_micros: 0,
      id: 60170225920,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/9262111890/adGroups/60170225920',
      status: 2,
      target_cpa_micros: 0,
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_type: 2,
      base_campaign: 'customers/9262111890/campaigns/1485014801',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/9262111890/campaignBudgets/1548344372',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 5 },
      id: 1485014801,
      labels: [],
      name: 'My campaign',
      network_settings: {
        target_content_network: true,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: true,
      },
      payment_mode: 4,
      resource_name: 'customers/9262111890/campaigns/1485014801',
      selective_optimization: { conversion_actions: [] },
      serving_status: 2,
      start_date: '2018-07-24',
      status: 2,
      target_spend: { cpc_bid_ceiling_micros: 1000000 },
      url_custom_parameters: [],
    },
    customer: {
      auto_tagging_enabled: false,
      call_reporting_setting: {
        call_conversion_action: 'customers/9262111890/conversionActions/179',
        call_conversion_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 797556569 },
      currency_code: 'EUR',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 9262111890,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [8, 2],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 797556569 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-797556569\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-797556569');\n</script>\n",
      },
      resource_name: 'customers/9262111890',
      test_account: true,
      time_zone: 'Europe/London',
    },
  },
]

Create an AdGroupCriterion

The customer.adGroupCriteria.create(ad_group_criterion) method makes a new AdGroupCriterion in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupCriterion object or array of objects.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names created.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Creating the entity

const ad_group_criterion = {
  // Your AdGroupCriterion here, without immutable fields such as resource_name
}

// Passing in a single entity to create
const result = await customer.adGroupCriteria.create(ad_group_criterion)

// Passing in an array of entities to create, validating only
const result = await customer.adGroupCriteria.create([ad_group_criterion, other_ad_group_criterion], {
  validate_only: true,
})
// Example result
{
	results : ['customers/9262111890/adGroupCriteria/60170225920~521456008776'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupCriterion

The customer.adGroupCriteria.update(ad_group_criterion) method changes the attributes of an existing adGroupCriteria in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupCriterion object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const ad_group_criterion = {
  resource_name: 'customers/9262111890/adGroupCriteria/60170225920~521456008776', // The resource_name is required
  // ...any other fields that you would like to update
}

// Passing in a single entity to update
const result = await customer.adGroupCriteria.update(ad_group_criterion)

// Passing in an array of entities to update, validating only
const result = await customer.adGroupCriteria.update([ad_group_criterion, other_ad_group_criterion], {
  validate_only: true,
})
// Example result
{
	results : ['customers/9262111890/adGroupCriteria/60170225920~521456008776'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupCriterion

The customer.adGroupCriteria.delete(resource_name) sets the status field of an AdGroupCriterion to REMOVED. Those entities and their metrics will continue to exist, but they will be read-only. Removed entities cannot be re-enabled.

Arguments

  • resource_name required

    The resource_name of that AdGroupCriterion

Returns

Nothing

// Deleting the entity

await customer.adGroupCriteria.delete('customers/9262111890/adGroupCriteria/60170225920~521456008776')

AdGroupCriterionLabel

The AdGroupCriterionLabel object

Fields

ad_group_criterion string
The ad group criterion to which the label is attached.
label string
The label assigned to the ad group criterion.
resource_name string
The resource name of the ad group criterion label. Ad group criterion label resource names have the form: customers/{customer_id}/adGroupCriterionLabels/{ad_group_id}~{criterion_id}~{label_id}
// Example AdGroupCriterionLabel
const ad_group_criterion_label = {
  ad_group_criterion: 'customers/3827277046/adGroupCriteria/45808681353~331634074542',
  label: 'customers/3827277046/labels/3866969030',
  resource_name: 'customers/3827277046/adGroupCriterionLabels/45808681353~331634074542~3866969030',
}

Get an AdGroupCriterionLabel

The customer.adGroupCriterionLabels.get(resource_name) method returns the AdGroupCriterionLabel identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroupCriterionLabel

Returns

Returns that AdGroupCriterionLabel as an object.

// Getting the entity
let result = await customer.adGroupCriterionLabels.get(
  'customers/3827277046/adGroupCriterionLabels/45808681353~331634074542~3866969030'
)
// Example result
;({
  ad_group_criterion: 'customers/3827277046/adGroupCriteria/45808681353~331634074542',
  label: 'customers/3827277046/labels/3866969030',
  resource_name: 'customers/3827277046/adGroupCriterionLabels/45808681353~331634074542~3866969030',
})

List every instance of AdGroupCriterionLabel

The customer.adGroupCriterionLabels.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroupCriterionLabel.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group_criterion_label property. Any other resources that can be selected with ad_group_criterion_label will also be added as properities.

// Listing all the adGroupCriterionLabels in the account
let result = await customer.adGroupCriterionLabels.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupCriterionLabels.list({
  constraints: [
    {
      key: 'ad_group_criterion_label.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_criterion_label.some_field.sub_field',
})
// Example result
;[
  {
    ad_group_criterion_label: {
      ad_group_criterion: 'customers/3827277046/adGroupCriteria/45808681353~331634074542',
      label: 'customers/3827277046/labels/3866969030',
      resource_name: 'customers/3827277046/adGroupCriterionLabels/45808681353~331634074542~3866969030',
    },
    ad_group_criterion: {
      ad_group: 'customers/3827277046/adGroups/45808681353',
      approval_status: 2,
      cpc_bid_micros: 2880000,
      criterion_id: 331634074542,
      effective_cpc_bid_micros: 2880000,
      effective_cpc_bid_source: 7,
      effective_cpm_bid_micros: 10000,
      effective_cpm_bid_source: 6,
      final_mobile_urls: [],
      final_urls: [],
      keyword: { match_type: 2, text: 'opteo adwords' },
      negative: false,
      position_estimates: {
        first_page_cpc_micros: 550000,
        first_position_cpc_micros: 2880000,
        top_of_page_cpc_micros: 1220000,
      },
      quality_info: {
        creative_quality_score: 2,
        post_click_quality_score: 4,
        quality_score: 8,
        search_predicted_ctr: 4,
      },
      resource_name: 'customers/3827277046/adGroupCriteria/45808681353~331634074542',
      status: 3,
      system_serving_status: 2,
      type: 2,
      url_custom_parameters: [],
    },
    label: {
      id: 3866969030,
      name: 'My label',
      resource_name: 'customers/3827277046/labels/3866969030',
      status: 2,
      text_label: { background_color: '#1be779', description: '' },
    },
    ad_group: {
      base_ad_group: 'customers/3827277046/adGroups/45808681353',
      campaign: 'customers/3827277046/campaigns/881817006',
      cpc_bid_micros: 2720000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      effective_target_cpa_micros: 0,
      explorer_auto_optimizer_setting: { opt_in: false },
      id: 45808681353,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/45808681353',
      status: 2,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { targetingDimension: 3, bidOnly: false },
          { targetingDimension: 4, bidOnly: false },
          { targetingDimension: 5, bidOnly: true },
          { targetingDimension: 6, bidOnly: true },
          { targetingDimension: 7, bidOnly: false },
          { targetingDimension: 8, bidOnly: false },
        ],
      },
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 5,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/881817006',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/3827277046/campaignBudgets/1159840470',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 7 },
      id: 881817006,
      labels: ['customers/3827277046/labels/898377018'],
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: true,
      },
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/881817006',
      selective_optimization: { conversion_actions: [] },
      serving_status: 2,
      start_date: '2017-07-12',
      status: 3,
      targeting_setting: { target_restrictions: [{ targetingDimension: 3, bidOnly: false }] },
      tracking_url_template:
        'https://ad.atdmt.com/s/go;adv=11202207688256;ec=11202207688723;c.a={campaignid};s.a=google;p.a={campaignid};as.a={adgroupid};qpb=1;?bidkw={keyword:defaultkeyword}&dvc={device}&h={lpurl}?utm_source=adwords&utm_medium=PPC&utm_campaign={campaignid}&utm_term={ifsearch:{keyword}}{ifcontent:{placement}}&utm_content={creative}&network={network}&adgroupid={adgroupid}&matchtype={matchtype}&adposition={adposition}&targetid={targetid}&target={target}&device={device}&devicemodel={devicemodel}',
      url_custom_parameters: [],
    },
    customer: {
      auto_tagging_enabled: true,
      call_reporting_setting: {
        call_conversion_action: 'customers/3827277046/conversionActions/179',
        call_conversion_reporting_enabled: true,
        call_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 875176189 },
      currency_code: 'GBP',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [5],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 875176189 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-875176189\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-875176189');\n</script>\n",
      },
      resource_name: 'customers/3827277046',
      test_account: false,
      time_zone: 'Europe/London',
    },
  },
]

Create an AdGroupCriterionLabel

The customer.adGroupCriterionLabels.create(ad_group_criterion_label) method makes a new AdGroupCriterionLabel in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupCriterionLabel object or array of objects.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names created.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Creating the entity

const ad_group_criterion_label = {
  // Your AdGroupCriterionLabel here, without immutable fields such as resource_name
}

// Passing in a single entity to create
const result = await customer.adGroupCriterionLabels.create(ad_group_criterion_label)

// Passing in an array of entities to create, validating only
const result = await customer.adGroupCriterionLabels.create(
  [ad_group_criterion_label, other_ad_group_criterion_label],
  {
    validate_only: true,
  }
)
// Example result
{
	results : ['customers/3827277046/adGroupCriterionLabels/45808681353~331634074542~3866969030'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupCriterionLabel

The customer.adGroupCriterionLabels.update(ad_group_criterion_label) method changes the attributes of an existing adGroupCriterionLabels in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupCriterionLabel object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const ad_group_criterion_label = {
  resource_name: 'customers/3827277046/adGroupCriterionLabels/45808681353~331634074542~3866969030', // The resource_name is required
  // ...any other fields that you would like to update
}

// Passing in a single entity to update
const result = await customer.adGroupCriterionLabels.update(ad_group_criterion_label)

// Passing in an array of entities to update, validating only
const result = await customer.adGroupCriterionLabels.update(
  [ad_group_criterion_label, other_ad_group_criterion_label],
  {
    validate_only: true,
  }
)
// Example result
{
	results : ['customers/3827277046/adGroupCriterionLabels/45808681353~331634074542~3866969030'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupCriterionLabel

The customer.adGroupCriterionLabels.delete(resource_name) sets the status field of an AdGroupCriterionLabel to REMOVED. Those entities and their metrics will continue to exist, but they will be read-only. Removed entities cannot be re-enabled.

Arguments

  • resource_name required

    The resource_name of that AdGroupCriterionLabel

Returns

Nothing

// Deleting the entity

await customer.adGroupCriterionLabels.delete(
  'customers/3827277046/adGroupCriterionLabels/45808681353~331634074542~3866969030'
)

AdGroupCriterionSimulation

The AdGroupCriterionSimulation object

Fields

ad_group_id int64
AdGroup ID of the simulation.
cpc_bid_point_list object
points array
Projected metrics for a series of CPC bid amounts.
criterion_id int64
Criterion ID of the simulation.
end_date string
Last day on which the simulation is based, in YYYY-MM-DD format.
modification_method enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • UNIFORM (2)
    The values in a simulation were applied to all children of a given resource uniformly. Overrides on child resources were not respected.
  • DEFAULT (3)
    The values in a simulation were applied to the given resource. Overrides on child resources were respected, and traffic estimates do not include these resources.
How the simulation modifies the field.
resource_name string
The resource name of the ad group criterion simulation. Ad group criterion simulation resource names have the form: customers/{customer_id}/adGroupCriterionSimulations/{ad_group_id}~{criterion_id}~{type}~{modification_method}~{start_date}~{end_date}
start_date string
First day on which the simulation is based, in YYYY-MM-DD format.
type enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CPC_BID (2)
    The simulation is for a cpc bid.
  • CPV_BID (3)
    The simulation is for a cpv bid.
  • TARGET_CPA (4)
    The simulation is for a cpa target.
  • BID_MODIFIER (5)
    The simulation is for a bid modifier.
The field that the simulation modifies.
// Example AdGroupCriterionSimulation
const ad_group_criterion_simulation = {
  ad_group_id: 74343279514,
  cpc_bid_point_list: {
    points: [
      {
        cpcBidMicros: 850000,
        biddableConversions: 0.6467771530151367,
        biddableConversionsValue: 631.013916015625,
        clicks: 1,
        costMicros: 650000,
        impressions: 33,
        topSlotImpressions: 20,
      },
      {
        cpcBidMicros: 1180000,
        biddableConversions: 1.145405888557434,
        biddableConversionsValue: 1117.4901123046875,
        clicks: 4,
        costMicros: 3610000,
        impressions: 41,
        topSlotImpressions: 30,
      },
      {
        cpcBidMicros: 1750000,
        biddableConversions: 1.145405888557434,
        biddableConversionsValue: 1117.4901123046875,
        clicks: 4,
        costMicros: 4110000,
        impressions: 47,
        topSlotImpressions: 43,
      },
      {
        cpcBidMicros: 3850000,
        biddableConversions: 1.1888701915740967,
        biddableConversionsValue: 1159.8951416015625,
        clicks: 4,
        costMicros: 4970000,
        impressions: 57,
        topSlotImpressions: 52,
      },
      {
        cpcBidMicros: 8530000,
        biddableConversions: 1.3281930685043335,
        biddableConversionsValue: 1295.8223876953125,
        clicks: 5,
        costMicros: 27150000,
        impressions: 66,
        topSlotImpressions: 61,
      },
      {
        cpcBidMicros: 11400000,
        biddableConversions: 1.3300000429153442,
        biddableConversionsValue: 1297.5853271484375,
        clicks: 5,
        costMicros: 29080000,
        impressions: 78,
        topSlotImpressions: 64,
      },
    ],
  },
  criterion_id: 310015189818,
  end_date: '2019-07-04',
  modification_method: 2,
  resource_name:
    'customers/3827277046/adGroupCriterionSimulations/74343279514~310015189818~CPC_BID~UNIFORM~20190628~20190704',
  start_date: '2019-06-28',
  type: 2,
}

Get an AdGroupCriterionSimulation

The customer.adGroupCriterionSimulations.get(resource_name) method returns the AdGroupCriterionSimulation identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroupCriterionSimulation

Returns

Returns that AdGroupCriterionSimulation as an object.

// Getting the entity
let result = await customer.adGroupCriterionSimulations.get(
  'customers/3827277046/adGroupCriterionSimulations/74343279514~310015189818~CPC_BID~UNIFORM~20190628~20190704'
)
// Example result
;({
  ad_group_id: 74343279514,
  cpc_bid_point_list: {
    points: [
      {
        cpcBidMicros: 850000,
        biddableConversions: 0.6467771530151367,
        biddableConversionsValue: 631.013916015625,
        clicks: 1,
        costMicros: 650000,
        impressions: 33,
        topSlotImpressions: 20,
      },
      {
        cpcBidMicros: 1180000,
        biddableConversions: 1.145405888557434,
        biddableConversionsValue: 1117.4901123046875,
        clicks: 4,
        costMicros: 3610000,
        impressions: 41,
        topSlotImpressions: 30,
      },
      {
        cpcBidMicros: 1750000,
        biddableConversions: 1.145405888557434,
        biddableConversionsValue: 1117.4901123046875,
        clicks: 4,
        costMicros: 4110000,
        impressions: 47,
        topSlotImpressions: 43,
      },
      {
        cpcBidMicros: 3850000,
        biddableConversions: 1.1888701915740967,
        biddableConversionsValue: 1159.8951416015625,
        clicks: 4,
        costMicros: 4970000,
        impressions: 57,
        topSlotImpressions: 52,
      },
      {
        cpcBidMicros: 8530000,
        biddableConversions: 1.3281930685043335,
        biddableConversionsValue: 1295.8223876953125,
        clicks: 5,
        costMicros: 27150000,
        impressions: 66,
        topSlotImpressions: 61,
      },
      {
        cpcBidMicros: 11400000,
        biddableConversions: 1.3300000429153442,
        biddableConversionsValue: 1297.5853271484375,
        clicks: 5,
        costMicros: 29080000,
        impressions: 78,
        topSlotImpressions: 64,
      },
    ],
  },
  criterion_id: 310015189818,
  end_date: '2019-07-04',
  modification_method: 2,
  resource_name:
    'customers/3827277046/adGroupCriterionSimulations/74343279514~310015189818~CPC_BID~UNIFORM~20190628~20190704',
  start_date: '2019-06-28',
  type: 2,
})

List every instance of AdGroupCriterionSimulation

The customer.adGroupCriterionSimulations.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroupCriterionSimulation.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group_criterion_simulation property. Any other resources that can be selected with ad_group_criterion_simulation will also be added as properities.

// Listing all the adGroupCriterionSimulations in the account
let result = await customer.adGroupCriterionSimulations.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupCriterionSimulations.list({
  constraints: [
    {
      key: 'ad_group_criterion_simulation.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_criterion_simulation.some_field.sub_field',
})
// Example result
;[
  {
    ad_group_criterion_simulation: {
      ad_group_id: 74343279514,
      cpc_bid_point_list: {
        points: [
          {
            cpcBidMicros: 850000,
            biddableConversions: 0.6467771530151367,
            biddableConversionsValue: 631.013916015625,
            clicks: 1,
            costMicros: 650000,
            impressions: 33,
            topSlotImpressions: 20,
          },
          {
            cpcBidMicros: 1180000,
            biddableConversions: 1.145405888557434,
            biddableConversionsValue: 1117.4901123046875,
            clicks: 4,
            costMicros: 3610000,
            impressions: 41,
            topSlotImpressions: 30,
          },
          {
            cpcBidMicros: 1750000,
            biddableConversions: 1.145405888557434,
            biddableConversionsValue: 1117.4901123046875,
            clicks: 4,
            costMicros: 4110000,
            impressions: 47,
            topSlotImpressions: 43,
          },
          {
            cpcBidMicros: 3850000,
            biddableConversions: 1.1888701915740967,
            biddableConversionsValue: 1159.8951416015625,
            clicks: 4,
            costMicros: 4970000,
            impressions: 57,
            topSlotImpressions: 52,
          },
          {
            cpcBidMicros: 8530000,
            biddableConversions: 1.3281930685043335,
            biddableConversionsValue: 1295.8223876953125,
            clicks: 5,
            costMicros: 27150000,
            impressions: 66,
            topSlotImpressions: 61,
          },
          {
            cpcBidMicros: 11400000,
            biddableConversions: 1.3300000429153442,
            biddableConversionsValue: 1297.5853271484375,
            clicks: 5,
            costMicros: 29080000,
            impressions: 78,
            topSlotImpressions: 64,
          },
        ],
      },
      criterion_id: 310015189818,
      end_date: '2019-07-04',
      modification_method: 2,
      resource_name:
        'customers/3827277046/adGroupCriterionSimulations/74343279514~310015189818~CPC_BID~UNIFORM~20190628~20190704',
      start_date: '2019-06-28',
      type: 2,
    },
    ad_group_criterion: {
      ad_group: 'customers/3827277046/adGroups/74343279514',
      approval_status: 2,
      cpc_bid_micros: 6670000,
      criterion_id: 310015189818,
      effective_cpc_bid_micros: 6670000,
      effective_cpc_bid_source: 7,
      effective_cpm_bid_micros: 10000000,
      effective_cpm_bid_source: 6,
      final_mobile_urls: [],
      final_urls: [],
      keyword: { match_type: 3, text: 'opteo' },
      negative: false,
      position_estimates: {
        estimated_add_clicks_at_first_position_cpc: -5,
        estimated_add_cost_at_first_position_cpc: -27080000,
        first_page_cpc_micros: 380000,
        first_position_cpc_micros: 390000,
        top_of_page_cpc_micros: 380000,
      },
      quality_info: {
        creative_quality_score: 4,
        post_click_quality_score: 4,
        quality_score: 8,
        search_predicted_ctr: 3,
      },
      resource_name: 'customers/3827277046/adGroupCriteria/74343279514~310015189818',
      status: 2,
      system_serving_status: 2,
      type: 2,
      url_custom_parameters: [],
    },
    ad_group: {
      base_ad_group: 'customers/3827277046/adGroups/74343279514',
      campaign: 'customers/3827277046/campaigns/2015922402',
      cpc_bid_micros: 200000000,
      cpm_bid_micros: 10000000,
      cpv_bid_micros: 0,
      effective_target_cpa_micros: 0,
      explorer_auto_optimizer_setting: { opt_in: false },
      id: 74343279514,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/74343279514',
      status: 2,
      target_cpa_micros: 0,
      target_cpm_micros: 10000,
      targeting_setting: {
        target_restrictions: [
          { targetingDimension: 3, bidOnly: true },
          { targetingDimension: 4, bidOnly: false },
          { targetingDimension: 5, bidOnly: true },
          { targetingDimension: 6, bidOnly: true },
          { targetingDimension: 7, bidOnly: false },
          { targetingDimension: 8, bidOnly: true },
          { targetingDimension: 9, bidOnly: true },
        ],
      },
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/2015922402',
      bidding_strategy: 'customers/3827277046/biddingStrategies/2039955526',
      bidding_strategy_type: 15,
      campaign_budget: 'customers/3827277046/campaignBudgets/2079279759',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 5, positive_geo_target_type: 7 },
      id: 2015922402,
      labels: [
        'customers/3827277046/labels/3889728216',
        'customers/3827277046/labels/3889728468',
        'customers/3827277046/labels/3889728480',
      ],
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: false,
      },
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/2015922402',
      selective_optimization: { conversion_actions: [] },
      serving_status: 2,
      start_date: '2019-06-06',
      status: 2,
      targeting_setting: { target_restrictions: [{ targetingDimension: 3, bidOnly: true }] },
      url_custom_parameters: [],
    },
    customer: {
      auto_tagging_enabled: true,
      call_reporting_setting: {
        call_conversion_action: 'customers/3827277046/conversionActions/179',
        call_conversion_reporting_enabled: true,
        call_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 875176189 },
      currency_code: 'GBP',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [5],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 875176189 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-875176189\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-875176189');\n</script>\n",
      },
      resource_name: 'customers/3827277046',
      test_account: false,
      time_zone: 'Europe/London',
    },
  },
]

AdGroupExtensionSetting

The AdGroupExtensionSetting object

Fields

ad_group string
The resource name of the ad group. The linked extension feed items will serve under this ad group. AdGroup resource names have the form: customers/{customer_id}/adGroups/{ad_group_id}
device enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    The value is unknown in this version.
  • MOBILE (2)
    Mobile. The extensions in the extension setting will only serve on mobile devices.
  • DESKTOP (3)
    Desktop. The extensions in the extension setting will only serve on desktop devices.
The device for which the extensions will serve. Optional.
extension_feed_items array
The resource names of the extension feed items to serve under the ad group. ExtensionFeedItem resource names have the form: customers/{customer_id}/extensionFeedItems/{feed_item_id}
extension_type enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • NONE (2)
    None.
  • APP (3)
    App.
  • CALL (4)
    Call.
  • CALLOUT (5)
    Callout.
  • MESSAGE (6)
    Message.
  • PRICE (7)
    Price.
  • PROMOTION (8)
    Promotion.
  • SITELINK (9)
    Sitelink.
  • STRUCTURED_SNIPPET (10)
    Structured snippet.
  • LOCATION (11)
    Location.
  • AFFILIATE_LOCATION (12)
    Affiliate location.
The extension type of the ad group extension setting.
resource_name string
The resource name of the ad group extension setting. AdGroupExtensionSetting resource names have the form: customers/{customer_id}/adGroupExtensionSettings/{ad_group_id}~{extension_type}
// Example AdGroupExtensionSetting
const ad_group_extension_setting = {
  ad_group: 'customers/3827277046/adGroups/69639056828',
  extension_feed_items: [
    'customers/3827277046/extensionFeedItems/48199744867',
    'customers/3827277046/extensionFeedItems/48199839565',
    'customers/3827277046/extensionFeedItems/48200356726',
    'customers/3827277046/extensionFeedItems/48200575108',
    'customers/3827277046/extensionFeedItems/48200618792',
  ],
  extension_type: 10,
  resource_name: 'customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK',
}

Get an AdGroupExtensionSetting

The customer.adGroupExtensionSettings.get(resource_name) method returns the AdGroupExtensionSetting identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroupExtensionSetting

Returns

Returns that AdGroupExtensionSetting as an object.

// Getting the entity
let result = await customer.adGroupExtensionSettings.get(
  'customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK'
)
// Example result
;({
  ad_group: 'customers/3827277046/adGroups/69639056828',
  extension_feed_items: [
    'customers/3827277046/extensionFeedItems/48199744867',
    'customers/3827277046/extensionFeedItems/48199839565',
    'customers/3827277046/extensionFeedItems/48200356726',
    'customers/3827277046/extensionFeedItems/48200575108',
    'customers/3827277046/extensionFeedItems/48200618792',
  ],
  extension_type: 10,
  resource_name: 'customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK',
})

List every instance of AdGroupExtensionSetting

The customer.adGroupExtensionSettings.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroupExtensionSetting.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group_extension_setting property. Any other resources that can be selected with ad_group_extension_setting will also be added as properities.

// Listing all the adGroupExtensionSettings in the account
let result = await customer.adGroupExtensionSettings.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupExtensionSettings.list({
  constraints: [
    {
      key: 'ad_group_extension_setting.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_extension_setting.some_field.sub_field',
})
// Example result
;[
  {
    ad_group_extension_setting: {
      ad_group: 'customers/3827277046/adGroups/69639056828',
      extension_feed_items: [
        'customers/3827277046/extensionFeedItems/48199744867',
        'customers/3827277046/extensionFeedItems/48199839565',
        'customers/3827277046/extensionFeedItems/48200356726',
        'customers/3827277046/extensionFeedItems/48200575108',
        'customers/3827277046/extensionFeedItems/48200618792',
      ],
      extension_type: 10,
      resource_name: 'customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK',
    },
    ad_group: {
      base_ad_group: 'customers/3827277046/adGroups/69639056828',
      campaign: 'customers/3827277046/campaigns/954460701',
      cpc_bid_micros: 4500000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      effective_target_cpa_micros: 0,
      explorer_auto_optimizer_setting: { opt_in: false },
      id: 69639056828,
      labels: ['customers/3827277046/labels/3345231412'],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/69639056828',
      status: 2,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { targetingDimension: 3, bidOnly: false },
          { targetingDimension: 4, bidOnly: false },
          { targetingDimension: 5, bidOnly: false },
          { targetingDimension: 6, bidOnly: false },
          { targetingDimension: 7, bidOnly: false },
          { targetingDimension: 8, bidOnly: false },
          { targetingDimension: 9, bidOnly: false },
        ],
      },
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 5,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/954460701',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/3827277046/campaignBudgets/1234926420',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 7 },
      id: 954460701,
      labels: ['customers/3827277046/labels/3889728471'],
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: false,
      },
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/954460701',
      selective_optimization: { conversion_actions: [] },
      serving_status: 2,
      start_date: '2017-10-13',
      status: 3,
      targeting_setting: { target_restrictions: [{ targetingDimension: 3, bidOnly: false }] },
      url_custom_parameters: [],
    },
    customer: {
      auto_tagging_enabled: true,
      call_reporting_setting: {
        call_conversion_action: 'customers/3827277046/conversionActions/179',
        call_conversion_reporting_enabled: true,
        call_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 875176189 },
      currency_code: 'GBP',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [5],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 875176189 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-875176189\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-875176189');\n</script>\n",
      },
      resource_name: 'customers/3827277046',
      test_account: false,
      time_zone: 'Europe/London',
    },
  },
]

Create an AdGroupExtensionSetting

The customer.adGroupExtensionSettings.create(ad_group_extension_setting) method makes a new AdGroupExtensionSetting in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupExtensionSetting object or array of objects.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names created.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Creating the entity

const ad_group_extension_setting = {
  // Your AdGroupExtensionSetting here, without immutable fields such as resource_name
}

// Passing in a single entity to create
const result = await customer.adGroupExtensionSettings.create(ad_group_extension_setting)

// Passing in an array of entities to create, validating only
const result = await customer.adGroupExtensionSettings.create(
  [ad_group_extension_setting, other_ad_group_extension_setting],
  {
    validate_only: true,
  }
)
// Example result
{
	results : ['customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupExtensionSetting

The customer.adGroupExtensionSettings.update(ad_group_extension_setting) method changes the attributes of an existing adGroupExtensionSettings in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupExtensionSetting object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const ad_group_extension_setting = {
  resource_name: 'customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK', // The resource_name is required
  // ...any other fields that you would like to update
}

// Passing in a single entity to update
const result = await customer.adGroupExtensionSettings.update(ad_group_extension_setting)

// Passing in an array of entities to update, validating only
const result = await customer.adGroupExtensionSettings.update(
  [ad_group_extension_setting, other_ad_group_extension_setting],
  {
    validate_only: true,
  }
)
// Example result
{
	results : ['customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupExtensionSetting

The customer.adGroupExtensionSettings.delete(resource_name) sets the status field of an AdGroupExtensionSetting to REMOVED. Those entities and their metrics will continue to exist, but they will be read-only. Removed entities cannot be re-enabled.

Arguments

  • resource_name required

    The resource_name of that AdGroupExtensionSetting

Returns

Nothing

// Deleting the entity

await customer.adGroupExtensionSettings.delete('customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK')

AdGroupFeed

The AdGroupFeed object

Fields

ad_group string
The ad group being linked to the feed.
feed string
The feed being linked to the ad group.
matching_function object
function_string string
String representation of the Function. Examples: 1. IDENTITY(true) or IDENTITY(false). All or no feed items served. 2. EQUALS(CONTEXT.DEVICE,"Mobile") 3. IN(FEED_ITEM_ID,{1000001,1000002,1000003}) 4. CONTAINS_ANY(FeedAttribute[12345678,0],{"Mars cruise","Venus cruise"}) 5. AND(IN(FEED_ITEM_ID,{10001,10002}),EQUALS(CONTEXT.DEVICE,"Mobile")) For more details, visit https://developers.google.com/adwords/api/docs/guides/feed-matching-functions Note that because multiple strings may represent the same underlying function (whitespace and single versus double quotation marks, for example), the value returned may not be identical to the string sent in a mutate request.
left_operands array
The operands on the left hand side of the equation. This is also the operand to be used for single operand expressions such as NOT.
operator enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • IN (2)
    The IN operator.
  • IDENTITY (3)
    The IDENTITY operator.
  • EQUALS (4)
    The EQUALS operator
  • AND (5)
    Operator that takes two or more operands that are of type FunctionOperand and checks that all the operands evaluate to true. For functions related to ad formats, all the operands must be in left_operands.
  • CONTAINS_ANY (6)
    Operator that returns true if the elements in left_operands contain any of the elements in right_operands. Otherwise, return false. The right_operands must contain at least 1 and no more than 3 ConstantOperands.
Operator for a function.
right_operands array
The operands on the right hand side of the equation.
placeholder_types array
Indicates which placeholder types the feed may populate under the connected ad group. Required.
resource_name string
The resource name of the ad group feed. Ad group feed resource names have the form: `customers/{customer_id}/adGroupFeeds/{ad_group_id}~{feed_id}
status enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • ENABLED (2)
    Feed link is enabled.
  • REMOVED (3)
    Feed link has been removed.
Status of the ad group feed. This field is read-only.
// Example AdGroupFeed
const ad_group_feed = {
  ad_group: 'customers/3827277046/adGroups/45808681193',
  feed: 'customers/3827277046/feeds/90651045',
  matching_function: {
    function_string: 'IN(FEED_ITEM_ID,{70745235845,70745235842,70745235839,70745235836,70745235833})',
    left_operands: [{ requestContextOperand: { contextType: 2 } }],
    operator: 2,
    right_operands: [
      { constantOperand: { longValue: 70745235845 } },
      { constantOperand: { longValue: 70745235842 } },
      { constantOperand: { longValue: 70745235839 } },
      { constantOperand: { longValue: 70745235836 } },
      { constantOperand: { longValue: 70745235833 } },
    ],
  },
  placeholder_types: [1],
  resource_name: 'customers/3827277046/adGroupFeeds/45808681193~90651045',
  status: 2,
}

Get an AdGroupFeed

The customer.adGroupFeeds.get(resource_name) method returns the AdGroupFeed identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroupFeed

Returns

Returns that AdGroupFeed as an object.

// Getting the entity
let result = await customer.adGroupFeeds.get('customers/3827277046/adGroupFeeds/45808681193~90651045')
// Example result
;({
  ad_group: 'customers/3827277046/adGroups/45808681193',
  feed: 'customers/3827277046/feeds/90651045',
  matching_function: {
    function_string: 'IN(FEED_ITEM_ID,{70745235845,70745235842,70745235839,70745235836,70745235833})',
    left_operands: [{ requestContextOperand: { contextType: 2 } }],
    operator: 2,
    right_operands: [
      { constantOperand: { longValue: 70745235845 } },
      { constantOperand: { longValue: 70745235842 } },
      { constantOperand: { longValue: 70745235839 } },
      { constantOperand: { longValue: 70745235836 } },
      { constantOperand: { longValue: 70745235833 } },
    ],
  },
  placeholder_types: [1],
  resource_name: 'customers/3827277046/adGroupFeeds/45808681193~90651045',
  status: 2,
})

List every instance of AdGroupFeed

The customer.adGroupFeeds.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroupFeed.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group_feed property. Any other resources that can be selected with ad_group_feed will also be added as properities.

// Listing all the adGroupFeeds in the account
let result = await customer.adGroupFeeds.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupFeeds.list({
  constraints: [
    {
      key: 'ad_group_feed.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_feed.some_field.sub_field',
})
// Example result
;[
  {
    ad_group_feed: {
      ad_group: 'customers/3827277046/adGroups/45808681193',
      feed: 'customers/3827277046/feeds/90651045',
      matching_function: {
        function_string: 'IN(FEED_ITEM_ID,{70745235845,70745235842,70745235839,70745235836,70745235833})',
        left_operands: [{ requestContextOperand: { contextType: 2 } }],
        operator: 2,
        right_operands: [
          { constantOperand: { longValue: 70745235845 } },
          { constantOperand: { longValue: 70745235842 } },
          { constantOperand: { longValue: 70745235839 } },
          { constantOperand: { longValue: 70745235836 } },
          { constantOperand: { longValue: 70745235833 } },
        ],
      },
      placeholder_types: [1],
      resource_name: 'customers/3827277046/adGroupFeeds/45808681193~90651045',
      status: 2,
    },
    feed: {
      attributes: [
        { id: 1, name: 'SitelinkText', type: 4, isPartOfKey: false },
        { id: 2, name: 'SitelinkURL', type: 6, isPartOfKey: false },
        { id: 3, name: 'SitelinkFinalURLFingerprint', type: 8, isPartOfKey: false },
        { id: 4, name: 'SitelinkSource', type: 2, isPartOfKey: false },
        { id: 5, name: 'SitelinkExtractionReuse', type: 2, isPartOfKey: false },
        { id: 6, name: 'SitelinkDescriptionLine2', type: 4, isPartOfKey: false },
        { id: 7, name: 'SitelinkDescriptionLine3', type: 4, isPartOfKey: false },
      ],
      id: 90651045,
      name: 'My feed',
      origin: 1,
      resource_name: 'customers/3827277046/feeds/90651045',
      status: 2,
    },
    ad_group: {
      base_ad_group: 'customers/3827277046/adGroups/45808681193',
      campaign: 'customers/3827277046/campaigns/881817006',
      cpc_bid_micros: 2720000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      effective_target_cpa_micros: 0,
      explorer_auto_optimizer_setting: { opt_in: false },
      id: 45808681193,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/45808681193',
      status: 2,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { targetingDimension: 3, bidOnly: false },
          { targetingDimension: 4, bidOnly: false },
          { targetingDimension: 5, bidOnly: true },
          { targetingDimension: 6, bidOnly: true },
          { targetingDimension: 7, bidOnly: false },
          { targetingDimension: 8, bidOnly: false },
        ],
      },
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 5,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/881817006',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/3827277046/campaignBudgets/1159840470',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 7 },
      id: 881817006,
      labels: ['customers/3827277046/labels/898377018'],
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: true,
      },
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/881817006',
      selective_optimization: { conversion_actions: [] },
      serving_status: 2,
      start_date: '2017-07-12',
      status: 3,
      targeting_setting: { target_restrictions: [{ targetingDimension: 3, bidOnly: false }] },
      tracking_url_template:
        'https://ad.atdmt.com/s/go;adv=11202207688256;ec=11202207688723;c.a={campaignid};s.a=google;p.a={campaignid};as.a={adgroupid};qpb=1;?bidkw={keyword:defaultkeyword}&dvc={device}&h={lpurl}?utm_source=adwords&utm_medium=PPC&utm_campaign={campaignid}&utm_term={ifsearch:{keyword}}{ifcontent:{placement}}&utm_content={creative}&network={network}&adgroupid={adgroupid}&matchtype={matchtype}&adposition={adposition}&targetid={targetid}&target={target}&device={device}&devicemodel={devicemodel}',
      url_custom_parameters: [],
    },
    customer: {
      auto_tagging_enabled: true,
      call_reporting_setting: {
        call_conversion_action: 'customers/3827277046/conversionActions/179',
        call_conversion_reporting_enabled: true,
        call_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 875176189 },
      currency_code: 'GBP',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [5],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 875176189 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-875176189\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-875176189');\n</script>\n",
      },
      resource_name: 'customers/3827277046',
      test_account: false,
      time_zone: 'Europe/London',
    },
  },
]

Create an AdGroupFeed

The customer.adGroupFeeds.create(ad_group_feed) method makes a new AdGroupFeed in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupFeed object or array of objects.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names created.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Creating the entity

const ad_group_feed = {
  // Your AdGroupFeed here, without immutable fields such as resource_name
}

// Passing in a single entity to create
const result = await customer.adGroupFeeds.create(ad_group_feed)

// Passing in an array of entities to create, validating only
const result = await customer.adGroupFeeds.create([ad_group_feed, other_ad_group_feed], {
  validate_only: true,
})
// Example result
{
	results : ['customers/3827277046/adGroupFeeds/45808681193~90651045'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupFeed

The customer.adGroupFeeds.update(ad_group_feed) method changes the attributes of an existing adGroupFeeds in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupFeed object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const ad_group_feed = {
  resource_name: 'customers/3827277046/adGroupFeeds/45808681193~90651045', // The resource_name is required
  // ...any other fields that you would like to update
}

// Passing in a single entity to update
const result = await customer.adGroupFeeds.update(ad_group_feed)

// Passing in an array of entities to update, validating only
const result = await customer.adGroupFeeds.update([ad_group_feed, other_ad_group_feed], {
  validate_only: true,
})
// Example result
{
	results : ['customers/3827277046/adGroupFeeds/45808681193~90651045'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupFeed

The customer.adGroupFeeds.delete(resource_name) sets the status field of an AdGroupFeed to REMOVED. Those entities and their metrics will continue to exist, but they will be read-only. Removed entities cannot be re-enabled.

Arguments

  • resource_name required

    The resource_name of that AdGroupFeed

Returns

Nothing

// Deleting the entity

await customer.adGroupFeeds.delete('customers/3827277046/adGroupFeeds/45808681193~90651045')

AdGroupLabel

The AdGroupLabel object

Fields

ad_group string
The ad group to which the label is attached.
label string
The label assigned to the ad group.
resource_name string
The resource name of the ad group label. Ad group label resource names have the form: customers/{customer_id}/adGroupLabels/{ad_group_id}~{label_id}
// Example AdGroupLabel
const ad_group_label = {
  ad_group: 'customers/3827277046/adGroups/69639056828',
  label: 'customers/3827277046/labels/3345231412',
  resource_name: 'customers/3827277046/adGroupLabels/69639056828~3345231412',
}

Get an AdGroupLabel

The customer.adGroupLabels.get(resource_name) method returns the AdGroupLabel identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroupLabel

Returns

Returns that AdGroupLabel as an object.

// Getting the entity
let result = await customer.adGroupLabels.get('customers/3827277046/adGroupLabels/69639056828~3345231412')
// Example result
;({
  ad_group: 'customers/3827277046/adGroups/69639056828',
  label: 'customers/3827277046/labels/3345231412',
  resource_name: 'customers/3827277046/adGroupLabels/69639056828~3345231412',
})

List every instance of AdGroupLabel

The customer.adGroupLabels.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroupLabel.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group_label property. Any other resources that can be selected with ad_group_label will also be added as properities.

// Listing all the adGroupLabels in the account
let result = await customer.adGroupLabels.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupLabels.list({
  constraints: [
    {
      key: 'ad_group_label.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_label.some_field.sub_field',
})
// Example result
;[
  {
    ad_group_label: {
      ad_group: 'customers/3827277046/adGroups/69639056828',
      label: 'customers/3827277046/labels/3345231412',
      resource_name: 'customers/3827277046/adGroupLabels/69639056828~3345231412',
    },
    label: {
      id: 3345231412,
      name: 'My label',
      resource_name: 'customers/3827277046/labels/3345231412',
      status: 2,
      text_label: {
        background_color: '#e993eb',
        description: 'Adgroups where Chloe will write new ads that kick butt.',
      },
    },
    ad_group: {
      base_ad_group: 'customers/3827277046/adGroups/69639056828',
      campaign: 'customers/3827277046/campaigns/954460701',
      cpc_bid_micros: 4500000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      effective_target_cpa_micros: 0,
      explorer_auto_optimizer_setting: { opt_in: false },
      id: 69639056828,
      labels: ['customers/3827277046/labels/3345231412'],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/69639056828',
      status: 2,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { targetingDimension: 3, bidOnly: false },
          { targetingDimension: 4, bidOnly: false },
          { targetingDimension: 5, bidOnly: false },
          { targetingDimension: 6, bidOnly: false },
          { targetingDimension: 7, bidOnly: false },
          { targetingDimension: 8, bidOnly: false },
          { targetingDimension: 9, bidOnly: false },
        ],
      },
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 5,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/954460701',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/3827277046/campaignBudgets/1234926420',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 7 },
      id: 954460701,
      labels: ['customers/3827277046/labels/3889728471'],
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: false,
      },
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/954460701',
      selective_optimization: { conversion_actions: [] },
      serving_status: 2,
      start_date: '2017-10-13',
      status: 3,
      targeting_setting: { target_restrictions: [{ targetingDimension: 3, bidOnly: false }] },
      url_custom_parameters: [],
    },
    customer: {
      auto_tagging_enabled: true,
      call_reporting_setting: {
        call_conversion_action: 'customers/3827277046/conversionActions/179',
        call_conversion_reporting_enabled: true,
        call_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 875176189 },
      currency_code: 'GBP',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [5],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 875176189 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-875176189\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-875176189');\n</script>\n",
      },
      resource_name: 'customers/3827277046',
      test_account: false,
      time_zone: 'Europe/London',
    },
  },
]

Create an AdGroupLabel

The customer.adGroupLabels.create(ad_group_label) method makes a new AdGroupLabel in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupLabel object or array of objects.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names created.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Creating the entity

const ad_group_label = {
  // Your AdGroupLabel here, without immutable fields such as resource_name
}

// Passing in a single entity to create
const result = await customer.adGroupLabels.create(ad_group_label)

// Passing in an array of entities to create, validating only
const result = await customer.adGroupLabels.create([ad_group_label, other_ad_group_label], {
  validate_only: true,
})
// Example result
{
	results : ['customers/3827277046/adGroupLabels/69639056828~3345231412'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupLabel

The customer.adGroupLabels.update(ad_group_label) method changes the attributes of an existing adGroupLabels in an account. It also supports an array as its first agument for batch operations.

Arguments

  • entity required

    The AdGroupLabel object or array of objects. These must have a resource_name field set to identify the entity. Any other fields that you set will be updated.

  • options optional

    Object of the form { validate_only, partial_failure }:

    • validate_only optional, boolean

      When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.

    • partial_failure optional, boolean

      Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

  • results

    An array of the resource_names updated.

  • partial_failure_error

    If partial_failure was set to true, an array of errors.

  • request

    The request object sent to google's gRPC services. Useful for debugging.

// Updating the entity

const ad_group_label = {
  resource_name: 'customers/3827277046/adGroupLabels/69639056828~3345231412', // The resource_name is required
  // ...any other fields that you would like to update
}

// Passing in a single entity to update
const result = await customer.adGroupLabels.update(ad_group_label)

// Passing in an array of entities to update, validating only
const result = await customer.adGroupLabels.update([ad_group_label, other_ad_group_label], {
  validate_only: true,
})
// Example result
{
	results : ['customers/3827277046/adGroupLabels/69639056828~3345231412'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupLabel

The customer.adGroupLabels.delete(resource_name) sets the status field of an AdGroupLabel to REMOVED. Those entities and their metrics will continue to exist, but they will be read-only. Removed entities cannot be re-enabled.

Arguments

  • resource_name required

    The resource_name of that AdGroupLabel

Returns

Nothing

// Deleting the entity

await customer.adGroupLabels.delete('customers/3827277046/adGroupLabels/69639056828~3345231412')

AdGroupSimulation

The AdGroupSimulation object

Fields

ONE of the following:
  • cpc_bid_point_list object
  • cpv_bid_point_list object
  • target_cpa_point_list object
ad_group_id int64
Ad group id of the simulation.
end_date string
Last day on which the simulation is based, in YYYY-MM-DD format
modification_method enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • UNIFORM (2)
    The values in a simulation were applied to all children of a given resource uniformly. Overrides on child resources were not respected.
  • DEFAULT (3)
    The values in a simulation were applied to the given resource. Overrides on child resources were respected, and traffic estimates do not include these resources.
How the simulation modifies the field.
resource_name string
The resource name of the ad group simulation. Ad group simulation resource names have the form: customers/{customer_id}/adGroupSimulations/{ad_group_id}~{type}~{modification_method}~{start_date}~{end_date}
start_date string
First day on which the simulation is based, in YYYY-MM-DD format.
type enum
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CPC_BID (2)
    The simulation is for a cpc bid.
  • CPV_BID (3)
    The simulation is for a cpv bid.
  • TARGET_CPA (4)
    The simulation is for a cpa target.
  • BID_MODIFIER (5)
    The simulation is for a bid modifier.
The field that the simulation modifies.
// Example AdGroupSimulation
const ad_group_simulation = {
  ad_group_id: 74343279514,
  cpc_bid_point_list: {
    points: [
      {
        cpcBidMicros: 850000,
        biddableConversions: 0.6467771530151367,
        biddableConversionsValue: 631.013916015625,
        clicks: 1,
        costMicros: 650000,
        impressions: 33,
        topSlotImpressions: 20,
      },
      {
        cpcBidMicros: 1180000,
        biddableConversions: 1.145405888557434,
        biddableConversionsValue: 1117.4901123046875,
        clicks: 4,
        costMicros: 3610000,
        impressions: 41,
        topSlotImpressions: 30,
      },
      {
        cpcBidMicros: 1750000,
        biddableConversions: 1.145405888557434,
        biddableConversionsValue: 1117.4901123046875,
        clicks: 4,
        costMicros: 4110000,
        impressions: 47,
        topSlotImpressions: 43,
      },
      {
        cpcBidMicros: 3850000,
        biddableConversions: 1.1888701915740967,
        biddableConversionsValue: 1159.8951416015625,
        clicks: 4,
        costMicros: 4970000,
        impressions: 57,
        topSlotImpressions: 52,
      },
      {
        cpcBidMicros: 8530000,
        biddableConversions: 1.3281930685043335,
        biddableConversionsValue: 1295.8223876953125,
        clicks: 5,
        costMicros: 27150000,
        impressions: 66,
        topSlotImpressions: 61,
      },
      {
        cpcBidMicros: 11400000,
        biddableConversions: 1.3300000429153442,
        biddableConversionsValue: 1297.5853271484375,
        clicks: 5,
        costMicros: 29080000,
        impressions: 78,
        topSlotImpressions: 64,
      },
    ],
  },
  end_date: '2019-07-04',
  modification_method: 2,
  resource_name: 'customers/3827277046/adGroupSimulations/74343279514~CPC_BID~UNIFORM~20190628~20190704',
  start_date: '2019-06-28',
  type: 2,
}

Get an AdGroupSimulation

The customer.adGroupSimulations.get(resource_name) method returns the AdGroupSimulation identified by a resource_name.

Note: This function is heavily rate-limited by Google, so avoid using it in production.

Arguments

  • resource_name required

    The resource_name of that AdGroupSimulation

Returns

Returns that AdGroupSimulation as an object.

// Getting the entity
let result = await customer.adGroupSimulations.get(
  'customers/3827277046/adGroupSimulations/74343279514~CPC_BID~UNIFORM~20190628~20190704'
)
// Example result
;({
  ad_group_id: 74343279514,
  cpc_bid_point_list: {
    points: [
      {
        cpcBidMicros: 850000,
        biddableConversions: 0.6467771530151367,
        biddableConversionsValue: 631.013916015625,
        clicks: 1,
        costMicros: 650000,
        impressions: 33,
        topSlotImpressions: 20,
      },
      {
        cpcBidMicros: 1180000,
        biddableConversions: 1.145405888557434,
        biddableConversionsValue: 1117.4901123046875,
        clicks: 4,
        costMicros: 3610000,
        impressions: 41,
        topSlotImpressions: 30,
      },
      {
        cpcBidMicros: 1750000,
        biddableConversions: 1.145405888557434,
        biddableConversionsValue: 1117.4901123046875,
        clicks: 4,
        costMicros: 4110000,
        impressions: 47,
        topSlotImpressions: 43,
      },
      {
        cpcBidMicros: 3850000,
        biddableConversions: 1.1888701915740967,
        biddableConversionsValue: 1159.8951416015625,
        clicks: 4,
        costMicros: 4970000,
        impressions: 57,
        topSlotImpressions: 52,
      },
      {
        cpcBidMicros: 8530000,
        biddableConversions: 1.3281930685043335,
        biddableConversionsValue: 1295.8223876953125,
        clicks: 5,
        costMicros: 27150000,
        impressions: 66,
        topSlotImpressions: 61,
      },
      {
        cpcBidMicros: 11400000,
        biddableConversions: 1.3300000429153442,
        biddableConversionsValue: 1297.5853271484375,
        clicks: 5,
        costMicros: 29080000,
        impressions: 78,
        topSlotImpressions: 64,
      },
    ],
  },
  end_date: '2019-07-04',
  modification_method: 2,
  resource_name: 'customers/3827277046/adGroupSimulations/74343279514~CPC_BID~UNIFORM~20190628~20190704',
  start_date: '2019-06-28',
  type: 2,
})

List every instance of AdGroupSimulation

The customer.adGroupSimulations.list() returns all of the entities in the account, including REMOVED entities. It also returns all other resources that can be selected with each instance of AdGroupSimulation.

This method was designed for convenience and discovery. Internally, it uses the customer.report() method with all attributes fields included. For production code, we recommend using customer.report() with only the fields you need.

Arguments

  • options optional

    Object of the form { limit, order_by, constraints }:

    • limit optional, number

      Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.

    • order_by optional, string

      The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.

    • constraints optional, array/object

      A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

Returns an array of objects. Each object has a ad_group_simulation property. Any other resources that can be selected with ad_group_simulation will also be added as properities.

// Listing all the adGroupSimulations in the account
let result = await customer.adGroupSimulations.list()

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupSimulations.list({
  constraints: [
    {
      key: 'ad_group_simulation.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_simulation.some_field.sub_field',
})
// Example result
;[
  {
    ad_group_simulation: {
      ad_group_id: 74343279514,
      cpc_bid_point_list: {
        points: [
          {
            cpcBidMicros: 850000,
            biddableConversions: 0.6467771530151367,
            biddableConversionsValue: 631.013916015625,
            clicks: 1,
            costMicros: 650000,
            impressions: 33,
            topSlotImpressions: 20,
          },
          {
            cpcBidMicros: 1180000,
            biddableConversions: 1.1454058