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:

  • v4.0 of the official google ads API: Versions 4.0.0 and above of this library
  • v3.0 of the official google ads API: Versions 3.6.0 to 3.7.4 of this library
  • v2.0 of the official google ads API: Versions 3.0.0 to 3.5.2 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.
  • Linked customer ID : Only required for methods that update the resources of an entity when permissioned via Linked Accounts in the Google Ads UI. Read more
  • 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
    linked_customer_id: '789-789-789', // Optionally provide a linked-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.

Using Report Stream

The customer.reportStream() method is equivalent to customer.report(), except that it returns an async generator that you can use to access rows of data as they come back from the API.

Unlike report(), reportStream() does not support the page_size argument.

The main advantage of reportStream is performance. Not only are you able to get rows before the entire set has finished downloading, but the total time to finish the request will be shorter, especially for large requests (10,000+ rows).

Unfortunately, Google has hardwired the stream's chunk size to 10,000 rows, so there is no benefit to streaming for smaller requests. We're working with them to find a solution.

interface SearchTermView {
    search_term_view: {
        resource_name: string
        search_term: string
    }
    metrics: {
        clicks: number
    }
}

const generator = customer.reportStream<SearchTermView>({
    entity: 'search_term_view',
    metrics: ['metrics.clicks'],
    attributes: ['search_term_view.search_term'],
    order_by: 'metrics.clicks',
    sort_order: 'desc',
})

for await (let item of generator) {
    // process each SearchTermView
}

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
Output only. 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
Output only. 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
Output only. 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
Output only. The ID of the account-level budget.
name string
Output only. The name of the account-level budget.
notes string
Output only. Notes associated with the budget.
pending_proposal object
Output only. The pending proposal to modify this budget, if applicable.
account_budget_proposal string
Output only. The resource name of the proposal. AccountBudgetProposal resource names have the form: customers/{customer_id}/accountBudgetProposals/{account_budget_proposal_id}
creation_date_time string
Output only. The time when this account-level budget proposal was created. Formatted as yyyy-MM-dd HH:mm:ss.
end_date_time string
Output only. The end time in yyyy-MM-dd HH:mm:ss format.
end_time_type enum
Output only. The end time as a well-defined type, e.g. FOREVER.
  • 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.
name string
Output only. The name to assign to the account-level budget.
notes string
Output only. Notes associated with this budget.
proposal_type enum
Output only. The type of this proposal, e.g. END to end the budget associated with this proposal.
  • 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.
purchase_order_number string
Output only. A purchase order number is a value that helps users reference this budget in their monthly invoices.
spending_limit_micros int64
Output only. The spending limit in micros. One million is equivalent to one unit.
spending_limit_type enum
Output only. The spending limit as a well-defined type, e.g. INFINITE.
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • INFINITE (2)
    Infinite, indicates unlimited spending power.
start_date_time string
Output only. The start time in yyyy-MM-dd HH:mm:ss format.
proposed_start_date_time string
Output only. 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
Output only. A purchase order number is a value that helps users reference this budget in their monthly invoices.
resource_name string
Output only. The resource name of the account-level budget. AccountBudget resource names have the form: customers/{customer_id}/accountBudgets/{account_budget_id}
status enum
Output only. The status of this account-level budget.
  • 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.
total_adjustments_micros int64
Output only. 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: 227337890000,
  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: 1176390000,
}

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: 227337890000,
  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: 1176390000,
})

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: 227337890000,
      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: 1176390000,
    },
    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',
      final_url_suffix:
        'wickedsource=google&wickedid={creative}&wtm_term={ifsearch:{keyword}}{ifcontent:{placement}}&wtm_campaign={campaignid}&wtm_content={adgroupid}&wickedplacement={placement}&wickedkeyword={keyword}&gclid={gclid}',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      optimization_score: 0.8214771414132993,
      pay_per_conversion_eligibility_failure_reasons: [],
      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',
      tracking_url_template:
        'https://w.opteo.co/workers/ct?url={lpurl}&domain_id=123443&campaign_id={campaignid}&adgroup_id={adgroupid}&matchtype={matchtype}&network={network}&device={device}&keyword={keyword}&targetid={targetid}',
    },
  },
]

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
Immutable. The resource name of the account-level budget associated with this proposal.
approval_date_time string
Output only. The date time when this account-level budget was approved, if applicable.
approved_start_date_time string
Output only. The approved start date time in yyyy-mm-dd hh:mm:ss format.
billing_setup string
Immutable. The resource name of the billing setup associated with this proposal.
creation_date_time string
Output only. 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
Output only. The ID of the proposal.
proposal_type enum
Immutable. The type of this proposal, e.g. END to end the budget associated with this proposal.
  • 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.
proposed_name string
Immutable. The name to assign to the account-level budget.
proposed_notes string
Immutable. Notes associated with this budget.
proposed_purchase_order_number string
Immutable. A purchase order number is a value that enables the user to help them reference this budget in their monthly invoices.
resource_name string
Immutable. The resource name of the proposal. AccountBudgetProposal resource names have the form: customers/{customer_id}/accountBudgetProposals/{account_budget_proposal_id}
status enum
Output only. The status of this proposal. When a new proposal is created, the status defaults to PENDING.
  • 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.
// 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,
  proposal_type: 0,
  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,
  proposal_type: 0,
  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,
      proposal_type: 0,
      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',
      final_url_suffix:
        'wickedsource=google&wickedid={creative}&wtm_term={ifsearch:{keyword}}{ifcontent:{placement}}&wtm_campaign={campaignid}&wtm_content={adgroupid}&wickedplacement={placement}&wickedkeyword={keyword}&gclid={gclid}',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      optimization_score: 0.8214771414132993,
      pay_per_conversion_eligibility_failure_reasons: [],
      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',
      tracking_url_template:
        'https://w.opteo.co/workers/ct?url={lpurl}&domain_id=123443&campaign_id={campaignid}&adgroup_id={adgroupid}&matchtype={matchtype}&network={network}&device={device}&keyword={keyword}&targetid={targetid}',
    },
  },
]

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: [],
})

List every instance of Ad

The customer.ads.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 Ad.

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 property. Any other resources that can be selected with ad will also be added as properities.

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.ads.list({
  constraints: [
    {
      key: 'ad.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad.some_field.sub_field',
})
// Example result
;[
  /* Todo: add example list() return here */
]

Create an Ad

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

Arguments

  • entity required

    The Ad 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 = {
  // Your Ad here, without immutable fields such as resource_name
}

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

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

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 */ }
}

Delete an Ad

The customer.ads.delete(resource_name) sets the status field of an Ad 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 Ad

Returns

Nothing

// Deleting the entity

await customer.ads.delete('customers/1234567890/ads/123123123')

AdGroup

The AdGroup object

Fields

ad_rotation_mode enum
The ad rotation mode of the ad group.
  • 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.
base_ad_group string
Output only. 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
Immutable. 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
Output only. The CPV (cost-per-view) bid.
display_custom_bid_dimension enum
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.
  • 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.
effective_target_cpa_micros int64
Output only. The effective target CPA (cost-per-acquisition). This field is read-only.
effective_target_cpa_source enum
Output only. Source of the effective target CPA. This field is read-only.
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (5)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (6)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (7)
    The bid or target is defined on the ad group criterion.
effective_target_roas double
Output only. The effective target ROAS (return-on-ad-spend). This field is read-only.
effective_target_roas_source enum
Output only. Source of the effective target ROAS. This field is read-only.
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (5)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (6)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (7)
    The bid or target is defined on the ad group criterion.
explorer_auto_optimizer_setting object
Settings for the Display Campaign Optimizer, initially termed "Explorer".
opt_in boolean
Indicates whether the optimizer is turned on.
final_url_suffix string
URL template for appending params to Final URL.
id int64
Output only. The ID of the ad group.
labels array of strings
Output only. 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
Immutable. The resource name of the ad group. Ad group resource names have the form: customers/{customer_id}/adGroups/{ad_group_id}
status enum
The status of the ad group.
  • 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.
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
Setting for targeting related features.
target_restriction_operations array of objects
The list of operations changing the target restrictions. Adding a target restriction with a targeting dimension that already exists causes the existing target restriction to be replaced with the new value.
operator enum
Type of list operation to perform.
  • UNSPECIFIED ()
    Unspecified.
  • UNKNOWN ()
    Used for return value only. Represents value unknown in this version.
  • ADD ()
    Add the restriction to the existing restrictions.
  • REMOVE ()
    Remove the restriction from the existing restrictions.
value object
The target restriction being added to or removed from the list.
bid_only boolean
Indicates whether to restrict your ads to show only for the criteria you have selected for this targeting_dimension, or to target all values for this targeting_dimension and show ads based on your targeting in other TargetingDimensions. A value of true means that these criteria will only apply bid modifiers, and not affect targeting. A value of false means that these criteria will restrict targeting as well as applying bid modifiers.
targeting_dimension enum
The targeting dimension that these settings apply to.
  • 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.
target_restrictions array of objects
The per-targeting-dimension setting to restrict the reach of your campaign or ad group.
bid_only boolean
Indicates whether to restrict your ads to show only for the criteria you have selected for this targeting_dimension, or to target all values for this targeting_dimension and show ads based on your targeting in other TargetingDimensions. A value of true means that these criteria will only apply bid modifiers, and not affect targeting. A value of false means that these criteria will restrict targeting as well as applying bid modifiers.
targeting_dimension enum
The targeting dimension that these settings apply to.
  • 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.
tracking_url_template string
The URL template for constructing a tracking URL.
type enum
Immutable. The type of the ad group.
  • 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 (6)
    The default ad group type for Hotel campaigns.
  • SHOPPING_SMART_ADS (7)
    The type for ad groups in Smart Shopping campaigns.
  • VIDEO_BUMPER (8)
    Short unskippable in-stream video ads.
  • VIDEO_TRUE_VIEW_IN_STREAM (9)
    TrueView (skippable) in-stream video ads.
  • VIDEO_TRUE_VIEW_IN_DISPLAY (10)
    TrueView in-display video ads.
  • VIDEO_NON_SKIPPABLE_IN_STREAM (11)
    Unskippable in-stream video ads.
  • VIDEO_OUTSTREAM (12)
    Outstream video ads.
  • SEARCH_DYNAMIC_ADS (13)
    Ad group type for Dynamic Search Ads ad groups.
  • SHOPPING_COMPARISON_LISTING_ADS (14)
    The type for ad groups in Shopping Comparison Listing campaigns.
  • PROMOTED_HOTEL_ADS (15)
    The ad group type for Promoted Hotel ad groups.
  • VIDEO_RESPONSIVE (16)
    Video responsive ad groups.
url_custom_parameters array of objects
The list of mappings used to substitute custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls.
key string
The key matching the parameter tag name.
value string
The value to be substituted.
// Example AdGroup
const ad_group = {
  ad_rotation_mode: 0,
  base_ad_group: 'customers/3827277046/adGroups/56761341338',
  campaign: 'customers/3827277046/campaigns/1398201241',
  cpc_bid_micros: 6000000,
  cpm_bid_micros: 10000,
  cpv_bid_micros: 0,
  display_custom_bid_dimension: 0,
  effective_target_cpa_micros: 0,
  effective_target_cpa_source: 0,
  effective_target_roas: 4,
  effective_target_roas_source: 5,
  explorer_auto_optimizer_setting: { opt_in: false },
  id: 56761341338,
  labels: [],
  name: 'My ad group',
  resource_name: 'customers/3827277046/adGroups/56761341338',
  status: 3,
  target_cpa_micros: 0,
  targeting_setting: {
    target_restrictions: [
      { targeting_dimension: 3, bid_only: false },
      { targeting_dimension: 4, bid_only: false },
      { targeting_dimension: 5, bid_only: false },
      { targeting_dimension: 6, bid_only: false },
      { targeting_dimension: 7, bid_only: false },
      { targeting_dimension: 8, bid_only: false },
      { targeting_dimension: 9, bid_only: false },
    ],
  },
  type: 13,
  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/3827277046/adGroups/56761341338')
// Example result
;({
  ad_rotation_mode: 0,
  base_ad_group: 'customers/3827277046/adGroups/56761341338',
  campaign: 'customers/3827277046/campaigns/1398201241',
  cpc_bid_micros: 6000000,
  cpm_bid_micros: 10000,
  cpv_bid_micros: 0,
  display_custom_bid_dimension: 0,
  effective_target_cpa_micros: 0,
  effective_target_cpa_source: 0,
  effective_target_roas: 4,
  effective_target_roas_source: 5,
  explorer_auto_optimizer_setting: { opt_in: false },
  id: 56761341338,
  labels: [],
  name: 'My ad group',
  resource_name: 'customers/3827277046/adGroups/56761341338',
  status: 3,
  target_cpa_micros: 0,
  targeting_setting: {
    target_restrictions: [
      { targeting_dimension: 3, bid_only: false },
      { targeting_dimension: 4, bid_only: false },
      { targeting_dimension: 5, bid_only: false },
      { targeting_dimension: 6, bid_only: false },
      { targeting_dimension: 7, bid_only: false },
      { targeting_dimension: 8, bid_only: false },
      { targeting_dimension: 9, bid_only: false },
    ],
  },
  type: 13,
  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: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/56761341338',
      campaign: 'customers/3827277046/campaigns/1398201241',
      cpc_bid_micros: 6000000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      display_custom_bid_dimension: 0,
      effective_target_cpa_micros: 0,
      effective_target_cpa_source: 0,
      effective_target_roas: 4,
      effective_target_roas_source: 5,
      explorer_auto_optimizer_setting: { opt_in: false },
      id: 56761341338,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/56761341338',
      status: 3,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { targeting_dimension: 3, bid_only: false },
          { targeting_dimension: 4, bid_only: false },
          { targeting_dimension: 5, bid_only: false },
          { targeting_dimension: 6, bid_only: false },
          { targeting_dimension: 7, bid_only: false },
          { targeting_dimension: 8, bid_only: false },
          { targeting_dimension: 9, bid_only: false },
        ],
      },
      type: 13,
      url_custom_parameters: [],
    },
    bidding_strategy: {
      campaign_count: 3,
      id: 2053936084,
      name: 'My bidding strategy',
      non_removed_campaign_count: 3,
      resource_name: 'customers/3827277046/biddingStrategies/2053936084',
      status: 2,
      target_roas: { cpc_bid_ceiling_micros: 8000000, target_roas: 4 },
      type: 8,
    },
    campaign: {
      ad_serving_optimization_status: 5,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/1398201241',
      bidding_strategy: 'customers/3827277046/biddingStrategies/2053936084',
      bidding_strategy_type: 8,
      campaign_budget: 'customers/3827277046/campaignBudgets/1453179506',
      dynamic_search_ads_setting: {
        domain_name: 'opteo.com',
        feeds: [],
        language_code: 'en',
        use_supplied_urls_only: false,
      },
      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: 1398201241,
      labels: [
        'customers/3827277046/labels/3889728216',
        'customers/3827277046/labels/3889728468',
        'customers/3827277046/labels/3889728474',
      ],
      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/1398201241',
      serving_status: 2,
      start_date: '2018-05-10',
      status: 3,
      targeting_setting: { target_restrictions: [{ targeting_dimension: 3, bid_only: false }] },
      url_custom_parameters: [],
      video_brand_safety_suitability: 0,
    },
    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',
      final_url_suffix:
        'wickedsource=google&wickedid={creative}&wtm_term={ifsearch:{keyword}}{ifcontent:{placement}}&wtm_campaign={campaignid}&wtm_content={adgroupid}&wickedplacement={placement}&wickedkeyword={keyword}&gclid={gclid}',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      optimization_score: 0.8214771414132993,
      pay_per_conversion_eligibility_failure_reasons: [],
      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',
      tracking_url_template:
        'https://w.opteo.co/workers/ct?url={lpurl}&domain_id=123443&campaign_id={campaignid}&adgroup_id={adgroupid}&matchtype={matchtype}&network={network}&device={device}&keyword={keyword}&targetid={targetid}',
    },
  },
]

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/3827277046/adGroups/56761341338'],
	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/3827277046/adGroups/56761341338', // 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/3827277046/adGroups/56761341338'],
	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/3827277046/adGroups/56761341338')

AdGroupAd

The AdGroupAd object

Fields

ad object
Immutable. The ad.
ONE of the following:
  • app_ad object
    Details pertaining to an app ad.
  • app_engagement_ad object
    Details pertaining to an app engagement ad.
  • call_only_ad object
    Details pertaining to a call-only ad.
  • display_upload_ad object
    Details pertaining to a display upload ad.
  • expanded_dynamic_search_ad object
    Immutable. Details pertaining to an Expanded Dynamic Search Ad. This type of ad has its headline, final URLs, and display URL auto-generated at serving time according to domain name specific information provided by dynamic_search_ads_setting linked at the campaign level.
  • expanded_text_ad object
    Details pertaining to an expanded text ad.
  • gmail_ad object
    Immutable. Details pertaining to a Gmail ad.
  • hotel_ad object
    Details pertaining to a hotel ad.
  • image_ad object
    Immutable. Details pertaining to an Image ad.
  • legacy_app_install_ad object
    Immutable. Details pertaining to a legacy app install ad.
  • legacy_responsive_display_ad object
    Details pertaining to a legacy responsive display ad.
  • local_ad object
    Details pertaining to a local ad.
  • responsive_display_ad object
    Details pertaining to a responsive display ad.
  • responsive_search_ad object
    Details pertaining to a responsive search ad.
  • shopping_comparison_listing_ad object
    Details pertaining to a Shopping Comparison Listing ad.
  • shopping_product_ad object
    Details pertaining to a Shopping product ad.
  • shopping_smart_ad object
    Details pertaining to a Smart Shopping ad.
  • text_ad object
    Immutable. Details pertaining to a text ad.
  • video_ad object
    Details pertaining to a Video ad.
added_by_google_ads boolean
Output only. 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
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.
  • 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 (6)
    Smart TVs and game consoles.
  • OTHER (5)
    Other device types.
display_url string
The URL that appears in the ad description for some ad formats.
final_app_urls array of objects
A list of final app URLs that will be used on mobile if the user has the specific app installed.
os_type enum
The operating system targeted by this URL. Required.
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • IOS (2)
    The Apple IOS operating system.
  • ANDROID (3)
    The Android operating system.
url string
The app deep link URL. Deep links specify a location in an app that corresponds to the content you'd like to show, and should be of the form {scheme}://{host_path} The scheme identifies which app to open. For your app, you can use a custom scheme that starts with the app's name. The host and path specify the unique location in the app where your content exists. Example: "exampleapp://productid_1234". Required.
final_mobile_urls array of strings
The list of possible final mobile URLs after all cross-domain redirects for the ad.
final_url_suffix string
The suffix to use when constructing a final URL.
final_urls array of strings
The list of possible final URLs after all cross-domain redirects for the ad.
id int64
Output only. The ID of the ad.
name string
Immutable. 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
Immutable. The resource name of the ad. Ad resource names have the form: customers/{customer_id}/ads/{ad_id}
system_managed_resource_source enum
Output only. If this ad is system managed, then this field will indicate the source. This field is read-only.
  • 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.
tracking_url_template string
The URL template for constructing a tracking URL.
type enum
Output only. The type of ad.
  • 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 (6)
    The ad is a call only ad.
  • EXPANDED_DYNAMIC_SEARCH_AD (7)
    The ad is an expanded dynamic search ad.
  • HOTEL_AD (8)
    The ad is a hotel ad.
  • SHOPPING_SMART_AD (9)
    The ad is a Smart Shopping ad.
  • SHOPPING_PRODUCT_AD (10)
    The ad is a standard Shopping ad.
  • VIDEO_AD (12)
    The ad is a video ad.
  • GMAIL_AD (13)
    This ad is a Gmail ad.
  • IMAGE_AD (14)
    This ad is an Image ad.
  • RESPONSIVE_SEARCH_AD (15)
    The ad is a responsive search ad.
  • LEGACY_RESPONSIVE_DISPLAY_AD (16)
    The ad is a legacy responsive display ad.
  • APP_AD (17)
    The ad is an app ad.
  • LEGACY_APP_INSTALL_AD (18)
    The ad is a legacy app install ad.
  • RESPONSIVE_DISPLAY_AD (19)
    The ad is a responsive display ad.
  • LOCAL_AD (20)
    The ad is a local ad.
  • HTML5_UPLOAD_AD (21)
    The ad is a display upload ad with the HTML5_UPLOAD_AD product type.
  • DYNAMIC_HTML5_AD (22)
    The ad is a display upload ad with one of the DYNAMIC_HTML5_* product types.
  • APP_ENGAGEMENT_AD (23)
    The ad is an app engagement ad.
  • SHOPPING_COMPARISON_LISTING_AD (24)
    The ad is a Shopping Comparison Listing ad.
  • VIDEO_BUMPER_AD (25)
    Video bumper ad.
  • VIDEO_NON_SKIPPABLE_IN_STREAM_AD (26)
    Video non-skippable in-stream ad.
  • VIDEO_OUTSTREAM_AD (27)
    Video outstream ad.
  • VIDEO_TRUEVIEW_DISCOVERY_AD (28)
    Video TrueView in-display ad.
  • VIDEO_TRUEVIEW_IN_STREAM_AD (29)
    Video TrueView in-stream ad.
  • VIDEO_RESPONSIVE_AD (30)
    Video responsive ad.
url_collections array of objects
Additional URLs for the ad that are tagged with a unique identifier that can be referenced from other fields in the ad.
final_mobile_urls array of strings
A list of possible final mobile URLs.
final_urls array of strings
A list of possible final URLs.
tracking_url_template string
URL template for constructing a tracking URL.
url_collection_id string
Unique identifier for this UrlCollection instance.
url_custom_parameters array of objects
The list of mappings that can be used to substitute custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls. For mutates, please use url custom parameter operations.
key string
The key matching the parameter tag name.
value string
The value to be substituted.
ad_group string
Immutable. The ad group to which the ad belongs.
ad_strength enum
Output only. Overall ad strength for this ad group ad.
  • 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.
policy_summary object
Output only. Policy information for the ad.
approval_status enum
Output only. The overall approval status of this ad, calculated based on the status of its individual policy topic entries.
  • 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.
policy_topic_entries array of objects
Output only. The list of policy findings for this ad.
constraints array of objects
Indicates how serving of this resource may be affected (e.g. not serving in a country).
certificate_domain_mismatch_in_country_list object
Countries where the resource's domain is not covered by the certificates associated with it.
countries array of objects
Countries in which serving is restricted.
country_criterion string
Geo target constant resource name of the country in which serving is constrained.
total_targeted_countries int32
Total number of countries targeted by the resource.
certificate_missing_in_country_list object
Countries where a certificate is required for serving.
countries array of objects
Countries in which serving is restricted.
country_criterion string
Geo target constant resource name of the country in which serving is constrained.
total_targeted_countries int32
Total number of countries targeted by the resource.
country_constraint_list object
Countries where the resource cannot serve.
countries array of objects
Countries in which serving is restricted.
country_criterion string
Geo target constant resource name of the country in which serving is constrained.
total_targeted_countries int32
Total number of countries targeted by the resource.
reseller_constraint object
Reseller constraint.
evidences array of objects
Additional information that explains policy finding (e.g. the brand name for a trademark finding).
destination_mismatch object
Mismatch between the destinations of a resource's URLs.
url_types array of strings
The set of URLs that did not match each other.
destination_not_working object
Details when the destination is returning an HTTP error code or isn't functional in all locations for commonly used devices.
device enum
The type of device that failed to load the URL.
  • UNSPECIFIED (0)
    No value has been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • DESKTOP (2)
    Landing page doesn't work on desktop device.
  • ANDROID (3)
    Landing page doesn't work on Android device.
  • IOS (4)
    Landing page doesn't work on iOS device.
dns_error_type enum
The type of DNS error.
  • UNSPECIFIED (0)
    No value has been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • HOSTNAME_NOT_FOUND (2)
    Host name not found in DNS when fetching landing page.
  • GOOGLE_CRAWLER_DNS_ISSUE (3)
    Google internal crawler issue when communicating with DNS. This error doesn't mean the landing page doesn't work. Google will recrawl the landing page.
expanded_url string
The full URL that didn't work.
http_error_code int64
The HTTP error code.
last_checked_date_time string
The time the URL was last checked. The format is "YYYY-MM-DD HH:MM:SS". Examples: "2018-03-05 09:15:00" or "2018-02-01 14:34:30"
destination_text_list object
The text in the destination of the resource that is causing a policy finding.
destination_texts array of strings
List of text found in the resource's destination page.
language_code string
The language the resource was detected to be written in. This is an IETF language tag such as "en-US".
text_list object
List of evidence found in the text of a resource.
texts array of strings
The fragments of text from the resource that caused the policy finding.
website_list object
List of websites linked with this resource.
websites array of strings
Websites that caused the policy finding.
topic string
Policy topic this finding refers to. For example, "ALCOHOL", "TRADEMARKS_IN_AD_TEXT", or "DESTINATION_NOT_WORKING". The set of possible policy topics is not fixed for a particular API version and may change at any time.
type enum
Describes the negative or positive effect this policy will have on serving.
  • UNSPECIFIED (0)
    No value has been specified.
  • UNKNOWN (1)
    The received value is not known in this version. This is a response-only value.
  • PROHIBITED (2)
    The resource will not be served.
  • LIMITED (4)
    The resource will not be served under some circumstances.
  • FULLY_LIMITED (8)
    The resource cannot serve at all because of the current targeting criteria.
  • DESCRIPTIVE (5)
    May be of interest, but does not limit how the resource is served.
  • BROADENING (6)
    Could increase coverage beyond normal.
  • AREA_OF_INTEREST_ONLY (7)
    Constrained for all targeted countries, but may serve in other countries through area of interest.
review_status enum
Output only. Where in the review process this ad is.
  • 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.
  • ELIGIBLE_MAY_SERVE (5)
    The resource is eligible and may be serving but could still undergo further review.
resource_name string
Immutable. 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
The status of the ad.
  • 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.
// Example AdGroupAd
const ad_group_ad = {
  ad: {
    added_by_google_ads: false,
    device_preference: 0,
    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',
    system_managed_resource_source: 0,
    type: 3,
    url_collections: [],
    url_custom_parameters: [],
  },
  ad_group: 'customers/9262111890/adGroups/56328868446',
  ad_strength: 0,
  policy_summary: { approval_status: 0, policy_topic_entries: [], review_status: 2 },
  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,
    device_preference: 0,
    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',
    system_managed_resource_source: 0,
    type: 3,
    url_collections: [],
    url_custom_parameters: [],
  },
  ad_group: 'customers/9262111890/adGroups/56328868446',
  ad_strength: 0,
  policy_summary: { approval_status: 0, policy_topic_entries: [], review_status: 2 },
  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,
        device_preference: 0,
        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',
        system_managed_resource_source: 0,
        type: 3,
        url_collections: [],
        url_custom_parameters: [],
      },
      ad_group: 'customers/9262111890/adGroups/56328868446',
      ad_strength: 0,
      policy_summary: { approval_status: 0, policy_topic_entries: [], review_status: 2 },
      resource_name: 'customers/9262111890/adGroupAds/56328868446~284706472002',
      status: 2,
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/9262111890/adGroups/56328868446',
      campaign: 'customers/9262111890/campaigns/1485014801',
      cpc_bid_micros: 1000000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      display_custom_bid_dimension: 0,
      effective_target_cpa_micros: 0,
      effective_target_cpa_source: 0,
      effective_target_roas_source: 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_sub_type: 0,
      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',
      serving_status: 2,
      start_date: '2018-07-24',
      status: 2,
      target_spend: { cpc_bid_ceiling_micros: 1000000 },
      url_custom_parameters: [],
      video_brand_safety_suitability: 0,
    },
    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: [],
      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
Immutable. The ad group ad to which the label is attached.
label string
Immutable. The label assigned to the ad group ad.
resource_name string
Immutable. 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~206217423725',
  label: 'customers/3827277046/labels/1285360183',
  resource_name: 'customers/3827277046/adGroupAdLabels/37706041345~206217423725~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~206217423725~1285360183'
)
// Example result
;({
  ad_group_ad: 'customers/3827277046/adGroupAds/37706041345~206217423725',
  label: 'customers/3827277046/labels/1285360183',
  resource_name: 'customers/3827277046/adGroupAdLabels/37706041345~206217423725~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~206217423725',
      label: 'customers/3827277046/labels/1285360183',
      resource_name: 'customers/3827277046/adGroupAdLabels/37706041345~206217423725~1285360183',
    },
    ad_group_ad: {
      ad: {
        added_by_google_ads: false,
        device_preference: 0,
        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: ['https://opteo.com'],
        id: 206217423725,
        resource_name: 'customers/3827277046/ads/206217423725',
        system_managed_resource_source: 0,
        type: 3,
        url_collections: [],
        url_custom_parameters: [],
      },
      ad_group: 'customers/3827277046/adGroups/37706041345',
      ad_strength: 0,
      policy_summary: {
        approval_status: 2,
        policy_topic_entries: [
          { topic: 'ONE_WEBSITE_PER_AD_GROUP', type: 2, evidences_list: [], constraints_list: [] },
        ],
        review_status: 3,
      },
      resource_name: 'customers/3827277046/adGroupAds/37706041345~206217423725',
      status: 4,
    },
    label: {
      id: 1285360183,
      name: 'My label',
      resource_name: 'customers/3827277046/labels/1285360183',
      status: 2,
      text_label: { background_color: '#336666', description: '' },
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/37706041345',
      campaign: 'customers/3827277046/campaigns/729684361',
      cpc_bid_micros: 4770000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      display_custom_bid_dimension: 0,
      effective_target_cpa_micros: 0,
      effective_target_cpa_source: 0,
      effective_target_roas_source: 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: [
          { targeting_dimension: 3, bid_only: false },
          { targeting_dimension: 4, bid_only: false },
          { targeting_dimension: 5, bid_only: true },
          { targeting_dimension: 6, bid_only: false },
          { targeting_dimension: 7, bid_only: false },
          { targeting_dimension: 8, bid_only: false },
        ],
      },
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 4,
      advertising_channel_sub_type: 0,
      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',
      serving_status: 2,
      start_date: '2017-01-04',
      status: 4,
      targeting_setting: { target_restrictions: [{ targeting_dimension: 3, bid_only: false }] },
      url_custom_parameters: [],
      video_brand_safety_suitability: 0,
    },
    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',
      final_url_suffix:
        'wickedsource=google&wickedid={creative}&wtm_term={ifsearch:{keyword}}{ifcontent:{placement}}&wtm_campaign={campaignid}&wtm_content={adgroupid}&wickedplacement={placement}&wickedkeyword={keyword}&gclid={gclid}',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      optimization_score: 0.8214771414132993,
      pay_per_conversion_eligibility_failure_reasons: [],
      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',
      tracking_url_template:
        'https://w.opteo.co/workers/ct?url={lpurl}&domain_id=123443&campaign_id={campaignid}&adgroup_id={adgroupid}&matchtype={matchtype}&network={network}&device={device}&keyword={keyword}&targetid={targetid}',
    },
  },
]

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~206217423725~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~206217423725~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~206217423725~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~206217423725~1285360183')

AdGroupBidModifier

The AdGroupBidModifier object

Fields

ONE of the following:
  • device object
    Immutable. A device criterion.
  • hotel_advance_booking_window object
    Immutable. Criterion for number of days prior to the stay the booking is being made.
  • hotel_check_in_day object
    Immutable. Criterion for day of the week the booking is for.
  • hotel_date_selection_type object
    Immutable. Criterion for hotel date selection (default dates vs. user selected).
  • hotel_length_of_stay object
    Immutable. Criterion for length of hotel stay in nights.
  • preferred_content object
    Immutable. A preferred content criterion.
ad_group string
Immutable. The ad group to which this criterion belongs.
base_ad_group string
Output only. 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
Output only. Bid modifier source.
  • 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.
criterion_id int64
Output only. The ID of the criterion to bid modify. This field is ignored for mutates.
resource_name string
Immutable. 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',
  bid_modifier_source: 0,
  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',
  bid_modifier_source: 0,
  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',
      bid_modifier_source: 0,
      criterion_id: 30000,
      device: { type: 4 },
      resource_name: 'customers/9262111890/adGroupBidModifiers/57176985017~30000',
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/9262111890/adGroups/57176985017',
      campaign: 'customers/9262111890/campaigns/1485014801',
      cpc_bid_micros: 10000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      display_custom_bid_dimension: 0,
      effective_target_cpa_micros: 0,
      effective_target_cpa_source: 0,
      effective_target_roas_source: 0,
      id: 57176985017,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/9262111890/adGroups/57176985017',
      status: 4,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { targeting_dimension: 5, bid_only: true },
          { targeting_dimension: 6, bid_only: true },
          { targeting_dimension: 8, bid_only: true },
          { targeting_dimension: 9, bid_only: true },
        ],
      },
      type: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_sub_type: 0,
      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',
      serving_status: 2,
      start_date: '2018-07-24',
      status: 2,
      target_spend: { cpc_bid_ceiling_micros: 1000000 },
      url_custom_parameters: [],
      video_brand_safety_suitability: 0,
    },
    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: [],
      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
    Immutable. Age range.
  • app_payment_model object
    Immutable. App Payment Model.
  • custom_affinity object
    Immutable. Custom Affinity.
  • custom_intent object
    Immutable. Custom Intent.
  • gender object
    Immutable. Gender.
  • income_range object
    Immutable. Income range.
  • keyword object
    Immutable. Keyword.
  • listing_group object
    Immutable. Listing group.
  • mobile_app_category object
    Immutable. Mobile app category.
  • mobile_application object
    Immutable. Mobile application.
  • parental_status object
    Immutable. Parental status.
  • placement object
    Immutable. Placement.
  • topic object
    Immutable. Topic.
  • user_interest object
    Immutable. User Interest.
  • user_list object
    Immutable. User List.
  • webpage object
    Immutable. Webpage
  • youtube_channel object
    Immutable. YouTube Channel.
  • youtube_video object
    Immutable. YouTube Video.
ad_group string
Immutable. The ad group to which the criterion belongs.
approval_status enum
Output only. Approval status of the criterion.
  • 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.
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
Output only. The ID of the criterion. This field is ignored for mutates.
disapproval_reasons array of strings
Output only. List of disapproval reasons of the criterion. The different reasons for disapproving a criterion can be found here: https://support.google.com/adspolicy/answer/6008942 This field is read-only.
effective_cpc_bid_micros int64
Output only. The effective CPC (cost-per-click) bid.
effective_cpc_bid_source enum
Output only. Source of the effective CPC bid.
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (5)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (6)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (7)
    The bid or target is defined on the ad group criterion.
effective_cpm_bid_micros int64
Output only. The effective CPM (cost-per-thousand viewable impressions) bid.
effective_cpm_bid_source enum
Output only. Source of the effective CPM bid.
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (5)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (6)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (7)
    The bid or target is defined on the ad group criterion.
effective_cpv_bid_micros int64
Output only. The effective CPV (cost-per-view) bid.
effective_cpv_bid_source enum
Output only. Source of the effective CPV bid.
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (5)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (6)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (7)
    The bid or target is defined on the ad group criterion.
effective_percent_cpc_bid_micros int64
Output only. The effective Percent CPC bid amount.
effective_percent_cpc_bid_source enum
Output only. Source of the effective Percent CPC bid.
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    Used for return value only. Represents value unknown in this version.
  • CAMPAIGN_BIDDING_STRATEGY (5)
    Effective bid or target is inherited from campaign bidding strategy.
  • AD_GROUP (6)
    The bid or target is defined on the ad group.
  • AD_GROUP_CRITERION (7)
    The bid or target is defined on the ad group criterion.
final_mobile_urls array of strings
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 of strings
The list of possible final URLs after all cross-domain redirects for the ad.
negative boolean
Immutable. 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
Output only. Estimates for criterion bids at various positions.
estimated_add_clicks_at_first_position_cpc int64
Output only. 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
Output only. 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
Output only. The estimate of the CPC bid required for ad to be shown on first page of search results.
first_position_cpc_micros int64
Output only. 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
Output only. 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
Output only. Information regarding the quality of the criterion.
creative_quality_score enum
Output only. The performance of the ad compared to other advertisers.
  • 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.
post_click_quality_score enum
Output only. The quality score of the landing page.
  • 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.
quality_score int32
Output only. The quality score. This field may not be populated if Google does not have enough information to determine a value.
search_predicted_ctr enum
Output only. The click-through rate compared to that of other advertisers.
  • 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.
resource_name string
Immutable. 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
The status of the criterion.
  • 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.
system_serving_status enum
Output only. Serving status of the criterion.
  • UNSPECIFIED (0)
    Not specified.
  • UNKNOWN (1)
    The value is unknown in this version.
  • ELIGIBLE (2)
    Eligible.
  • RARELY_SERVED (3)
    Low search volume.
tracking_url_template string
The URL template for constructing a tracking URL.
type enum
Output only. The type of the criterion.
  • 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.
url_custom_parameters array of objects
The list of mappings used to substitute custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls.
key string
The key matching the parameter tag name.
value string
The value to be substituted.
// Example AdGroupCriterion
const ad_group_criterion = {
  ad_group: 'customers/9262111890/adGroups/60170225920',
  approval_status: 4,
  criterion_id: 521456008776,
  disapproval_reasons: [],
  effective_cpc_bid_micros: 1000000,
  effective_cpc_bid_source: 6,
  effective_cpm_bid_micros: 10000,
  effective_cpm_bid_source: 6,
  effective_cpv_bid_source: 0,
  effective_percent_cpc_bid_source: 0,
  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,
  disapproval_reasons: [],
  effective_cpc_bid_micros: 1000000,
  effective_cpc_bid_source: 6,
  effective_cpm_bid_micros: 10000,
  effective_cpm_bid_source: 6,
  effective_cpv_bid_source: 0,
  effective_percent_cpc_bid_source: 0,
  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,
      disapproval_reasons: [],
      effective_cpc_bid_micros: 1000000,
      effective_cpc_bid_source: 6,
      effective_cpm_bid_micros: 10000,
      effective_cpm_bid_source: 6,
      effective_cpv_bid_source: 0,
      effective_percent_cpc_bid_source: 0,
      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: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/9262111890/adGroups/60170225920',
      campaign: 'customers/9262111890/campaigns/1485014801',
      cpc_bid_micros: 1000000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      display_custom_bid_dimension: 0,
      effective_target_cpa_micros: 0,
      effective_target_cpa_source: 0,
      effective_target_roas_source: 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_sub_type: 0,
      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',
      serving_status: 2,
      start_date: '2018-07-24',
      status: 2,
      target_spend: { cpc_bid_ceiling_micros: 1000000 },
      url_custom_parameters: [],
      video_brand_safety_suitability: 0,
    },
    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: [],
      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
Immutable. The ad group criterion to which the label is attached.
label string
Immutable. The label assigned to the ad group criterion.
resource_name string
Immutable. 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,
      disapproval_reasons: [],
      effective_cpc_bid_micros: 2880000,
      effective_cpc_bid_source: 7,
      effective_cpm_bid_micros: 10000,
      effective_cpm_bid_source: 6,
      effective_cpv_bid_source: 0,
      effective_percent_cpc_bid_source: 0,
      final_mobile_urls: [],
      final_urls: [],
      keyword: { match_type: 2, text: 'opteo adwords' },
      negative: false,
      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: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/45808681353',
      campaign: 'customers/3827277046/campaigns/881817006',
      cpc_bid_micros: 2720000,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 0,
      display_custom_bid_dimension: 0,
      effective_target_cpa_micros: 0,
      effective_target_cpa_source: 0,
      effective_target_roas_source: 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: [
          { targeting_dimension: 3, bid_only: false },
          { targeting_dimension: 4, bid_only: false },
          { targeting_dimension: 5, bid_only: true },
          { targeting_dimension: 6, bid_only: true },
          { targeting_dimension: 7, bid_only: false },
          { targeting_dimension: 8, bid_only: false },
        ],
      },
      type: 2,
      url_custom_parameters: [{ key: 'yy', value: '1' }],
    },
    campaign: {
      ad_serving_optimization_status: 5,
      advertising_channel_sub_type: 0,
      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',
      serving_status: 2,
      start_date: '2017-07-12',
      status: 3,
      targeting_setting: { target_restrictions: [{ targeting_dimension: 3, bid_only: 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: [],
      video_brand_safety_suitability: 0,
    },
    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',
      final_url_suffix:
        'wickedsource=google&wickedid={creative}&wtm_term={ifsearch:{keyword}}{ifcontent:{placement}}&wtm_campaign={campaignid}&wtm_content={adgroupid}&wickedplacement={placement}&wickedkeyword={keyword}&gclid={gclid}',
      has_partners_badge: false,
      id: 3827277046,
      manager: false,
      optimization_score: 0.8214771414132993,
      pay_per_conversion_eligibility_failure_reasons: [],
      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',
      tracking_url_template:
        'https://w.opteo.co/workers/ct?url={lpurl}&domain_id=123443&campaign_id={campaignid}&adgroup_id={adgroupid}&matchtype={matchtype}&network={network}&device={device}&keyword={keyword}&targetid={targetid}',
    },
  },
]

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
Output only. AdGroup ID of the simulation.
cpc_bid_point_list object
Output only. Simulation points if the simulation type is CPC_BID.
points array of objects
Projected metrics for a series of CPC bid amounts.
biddable_conversions double
Projected number of biddable conversions.
biddable_conversions_value double
Projected total value of biddable conversions.
clicks int64
Projected number of clicks.
cost_micros int64
Projected cost in micros.
cpc_bid_micros int64
The simulated CPC bid upon which projected metrics are based.
impressions int64
Projected number of impressions.
top_slot_impressions int64
Projected number of top slot impressions. Only search advertising channel type supports this field.
criterion_id int64
Output only. Criterion ID of the simulation.
end_date string
Output only. Last day on which the simulation is based, in YYYY-MM-DD format.
modification_method enum
Output only. How the simulation modifies the field.
  • 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.
resource_name string
Output only. 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
Output only. First day on which the simulation is based, in YYYY-MM-DD format.
type enum
Output only. The field that the simulation modifies.
  • 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.
  • TARGET_ROAS (6)
    The simulation is for a ROAS target.
// Example AdGroupCriterionSimulation
const ad_group_criterion_simulation = {
  ad_group_id: 77057369032,
  cpc_bid_point_list: {
    points: [
      {
        cpc_bid_micros: 2750000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 2,
        cost_micros: 1680000,
        impressions: 116,
        top_slot_impressions: 94,
      },
      {
        cpc_bid_micros: 3000000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 2,
        cost_micros: 5740000,
        impressions: 144,
        top_slot_impressions: 113,
      },
      {
        cpc_bid_micros: 3110000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 3,
        cost_micros: 10800000,
        impressions: 168,
        top_slot_impressions: 131,
      },
      {
        cpc_bid_micros: 4070000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 3,
        cost_micros: 15350000,
        impressions: 192,
        top_slot_impressions: 154,
      },
      {
        cpc_bid_micros: 5030000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 4,
        cost_micros: 22940000,
        impressions: 212,
        top_slot_impressions: 182,
      },
      {
        cpc_bid_micros: 6310000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 5,
        cost_micros: 38520000,
        impressions: 232,
        top_slot_impressions: 208,
      },
      {
        cpc_bid_micros: 9060000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 5,
        cost_micros: 50360000,
        impressions: 237,
        top_slot_impressions: 220,
      },
    ],
  },
  criterion_id: 391658604416,
  end_date: '2020-07-17',
  modification_method: 2,
  resource_name:
    'customers/3827277046/adGroupCriterionSimulations/77057369032~391658604416~CPC_BID~UNIFORM~20200711~20200717',
  start_date: '2020-07-11',
  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/77057369032~391658604416~CPC_BID~UNIFORM~20200711~20200717'
)
// Example result
;({
  ad_group_id: 77057369032,
  cpc_bid_point_list: {
    points: [
      {
        cpc_bid_micros: 2750000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 2,
        cost_micros: 1680000,
        impressions: 116,
        top_slot_impressions: 94,
      },
      {
        cpc_bid_micros: 3000000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 2,
        cost_micros: 5740000,
        impressions: 144,
        top_slot_impressions: 113,
      },
      {
        cpc_bid_micros: 3110000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 3,
        cost_micros: 10800000,
        impressions: 168,
        top_slot_impressions: 131,
      },
      {
        cpc_bid_micros: 4070000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 3,
        cost_micros: 15350000,
        impressions: 192,
        top_slot_impressions: 154,
      },
      {
        cpc_bid_micros: 5030000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 4,
        cost_micros: 22940000,
        impressions: 212,
        top_slot_impressions: 182,
      },
      {
        cpc_bid_micros: 6310000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 5,
        cost_micros: 38520000,
        impressions: 232,
        top_slot_impressions: 208,
      },
      {
        cpc_bid_micros: 9060000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 5,
        cost_micros: 50360000,
        impressions: 237,
        top_slot_impressions: 220,
      },
    ],
  },
  criterion_id: 391658604416,
  end_date: '2020-07-17',
  modification_method: 2,
  resource_name:
    'customers/3827277046/adGroupCriterionSimulations/77057369032~391658604416~CPC_BID~UNIFORM~20200711~20200717',
  start_date: '2020-07-11',
  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: 77057369032,
      cpc_bid_point_list: {
        points: [
          {
            cpc_bid_micros: 2750000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 2,
            cost_micros: 1680000,
            impressions: 116,
            top_slot_impressions: 94,
          },
          {
            cpc_bid_micros: 3000000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 2,
            cost_micros: 5740000,
            impressions: 144,
            top_slot_impressions: 113,
          },
          {
            cpc_bid_micros: 3110000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 3,
            cost_micros: 10800000,
            impressions: 168,
            top_slot_impressions: 131,
          },
          {
            cpc_bid_micros: 4070000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 3,
            cost_micros: 15350000,
            impressions: 192,
            top_slot_impressions: 154,
          },
          {
            cpc_bid_micros: 5030000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 4,
            cost_micros: 22940000,
            impressions: 212,
            top_slot_impressions: 182,
          },
          {
            cpc_bid_micros: 6310000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 5,
            cost_micros: 38520000,
            impressions: 232,
            top_slot_impressions: 208,
          },
          {
            cpc_bid_micros: 9060000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 5,
            cost_micros: 50360000,
            impressions: 237,
            top_slot_impressions: 220,
          },
        ],
      },
      criterion_id: 391658604416,
      end_date: '2020-07-17',
      modification_method: 2,
      resource_name:
        'customers/3827277046/adGroupCriterionSimulations/77057369032~391658604416~CPC_BID~UNIFORM~20200711~20200717',
      start_date: '2020-07-11',
      type: 2,
    },
    ad_group_criterion: {
      ad_group: 'customers/3827277046/adGroups/77057369032',
      approval_status: 2,
      criterion_id: 391658604416,
      disapproval_reasons: [],
      effective_cpc_bid_micros: 6310000,
      effective_cpc_bid_source: 6,
      effective_cpm_bid_micros: 10000000,
      effective_cpm_bid_source: 6,
      effective_cpv_bid_source: 0,
      effective_percent_cpc_bid_source: 0,
      final_mobile_urls: [],
      final_urls: [],
      keyword: { match_type: 4, text: '+google +ads +optimization' },
      negative: false,
      position_estimates: {
        estimated_add_clicks_at_first_position_cpc: -3,
        estimated_add_cost_at_first_position_cpc: -34860000,
        first_page_cpc_micros: 1470000,
        first_position_cpc_micros: 1470000,
        top_of_page_cpc_micros: 1470000,
      },
      quality_info