Overview

Features

Simple and easy-to-use API
Uses gRPC and Protocol Buffers internally (recommended by Google)
Typescript definitions for all Google Ads API resources, enums, and errors

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.

Core Resources directly map to entities in your account. Example: campaign, ad_group_criterion.
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.
Click & Search Term Resources are like core resources, except that they are by nature read-only. Example: click_view, search_term_view.
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:

Metrics hold data about the performance of your account, and change through time. Example: metrics.clicks or metrics.historical_quality_score.
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.
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:

A new budget with the temporary resource id -1 is created.
An existing campaign (id of 456) is updated to use the new budget (-1).
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
Output only. The adjusted spending limit in micros. One million is equivalent to one unit. If the approved spending limit is finite, the adjusted spending limit may vary depending on the types of adjustments applied to this budget, if applicable. The different kinds of adjustments are described here: https://support.google.com/google-ads/answer/1704323 For example, a debit adjustment reduces how much the account is allowed to spend.
adjusted_spending_limit_type enum
Output only. The adjusted spending limit as a well-defined type, e.g. INFINITE. This will only be populated if the adjusted spending limit is INFINITE, which is guaranteed to be true if the approved spending limit is 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.

ONE of the following:

approved_end_date_time string
Output only. The approved end time in yyyy-MM-dd HH:mm:ss format.
approved_end_time_type enum
Output only. The approved 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.

ONE of the following:

approved_spending_limit_micros int64
Output only. The approved spending limit in micros. One million is equivalent to one unit. This will only be populated if the proposed spending limit is finite, and will always be greater than or equal to the proposed spending limit.
approved_spending_limit_type enum
Output only. The approved spending limit as a well-defined type, e.g. INFINITE. This will only be populated if the approved spending limit is 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.

ONE of the following:

proposed_end_date_time string
Output only. The proposed end time in yyyy-MM-dd HH:mm:ss format.
proposed_end_time_type enum
Output only. The proposed 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.

ONE of the following:

proposed_spending_limit_micros int64
Output only. The proposed spending limit in micros. One million is equivalent to one unit.
proposed_spending_limit_type enum
Output only. The proposed 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.

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.

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.

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.

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
Output only. The approved end date time in yyyy-mm-dd hh:mm:ss format.
approved_end_time_type enum
Output only. The approved end date 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.

ONE of the following:

approved_spending_limit_micros int64
Output only. The approved spending limit in micros. One million is equivalent to one unit.
approved_spending_limit_type enum
Output only. The approved 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.

ONE of the following:

proposed_end_date_time string
Immutable. The proposed end date time in yyyy-mm-dd hh:mm:ss format.
proposed_end_time_type enum
Immutable. The proposed end date 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.

ONE of the following:

proposed_spending_limit_micros int64
Immutable. The proposed spending limit in micros. One million is equivalent to one unit.
proposed_spending_limit_type enum
Immutable. The proposed 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.

ONE of the following:

proposed_start_date_time string
Immutable. The proposed start date time in yyyy-mm-dd hh:mm:ss format.
proposed_start_time_type enum
Immutable. The proposed start date time as a well-defined type, e.g. NOW.
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.

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.

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.

// 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.

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')

Ad

Not to be confused with AdGroupAd, this entity only has two methods: get and update. It allows you to edit the creative part of an ad, such as the headline, description, or image. Editing an ad this way will not reset the metrics of the ad.

The Ad object

Fields

ONE of the following:

app_ad object
Details pertaining to an app ad.
Child Fields
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
html_5_media_bundles array of objects
List of media bundle assets that may be used with the ad.
asset string
The Asset resource name of this media bundle.
images array of objects
List of image assets that may be displayed with the ad.
asset string
The Asset resource name of this image.
mandatory_ad_text object
An optional text asset that, if specified, must always be displayed when the ad is served.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
youtube_videos array of objects
List of YouTube video assets that may be displayed with the ad.
asset string
The Asset resource name of this video.
app_engagement_ad object
Details pertaining to an app engagement ad.
Child Fields
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
images array of objects
List of image assets that may be displayed with the ad.
asset string
The Asset resource name of this image.
videos array of objects
List of video assets that may be displayed with the ad.
asset string
The Asset resource name of this video.
call_only_ad object
Details pertaining to a call-only ad.
Child Fields
business_name string
The business name in the ad.
call_tracked boolean
Whether to enable call tracking for the creative. Enabling call tracking also enables call conversions.
conversion_action string
The conversion action to attribute a call conversion to. If not set a default conversion action is used. This field only has effect if call_tracked is set to true. Otherwise this field is ignored.
conversion_reporting_state enum
The call conversion behavior of this call only ad. It can use its own call conversion setting, inherit the account level setting, or be disabled.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
DISABLED (2)
Call conversion action is disabled.
USE_ACCOUNT_LEVEL_CALL_CONVERSION_ACTION (3)
Call conversion action will use call conversion type set at the account level.
USE_RESOURCE_LEVEL_CALL_CONVERSION_ACTION (4)
Call conversion action will use call conversion type set at the resource (call only ads/call extensions) level.
country_code string
The country code in the ad.
description1 string
The first line of the ad's description.
description2 string
The second line of the ad's description.
disable_call_conversion boolean
Whether to disable call conversion for the creative. If set to true, disables call conversions even when call_tracked is true. If call_tracked is false, this field is ignored.
headline1 string
First headline in the ad.
headline2 string
Second headline in the ad.
phone_number string
The phone number in the ad.
phone_number_verification_url string
The URL to be used for phone number verification.
display_upload_ad object
Details pertaining to a display upload ad.
Child Fields
display_upload_product_type enum
The product type of this ad. See comments on the enum for details.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
HTML5_UPLOAD_AD (2)
HTML5 upload ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set.
DYNAMIC_HTML5_EDUCATION_AD (3)
Dynamic HTML5 education ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in an education campaign.
DYNAMIC_HTML5_FLIGHT_AD (4)
Dynamic HTML5 flight ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a flight campaign.
DYNAMIC_HTML5_HOTEL_RENTAL_AD (5)
Dynamic HTML5 hotel and rental ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a hotel campaign.
DYNAMIC_HTML5_JOB_AD (6)
Dynamic HTML5 job ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a job campaign.
DYNAMIC_HTML5_LOCAL_AD (7)
Dynamic HTML5 local ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a local campaign.
DYNAMIC_HTML5_REAL_ESTATE_AD (8)
Dynamic HTML5 real estate ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a real estate campaign.
DYNAMIC_HTML5_CUSTOM_AD (9)
Dynamic HTML5 custom ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a custom campaign.
DYNAMIC_HTML5_TRAVEL_AD (10)
Dynamic HTML5 travel ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a travel campaign.
DYNAMIC_HTML5_HOTEL_AD (11)
Dynamic HTML5 hotel ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a hotel campaign.
media_bundle object
A media bundle asset to be used in the ad. For information about the media bundle for HTML5_UPLOAD_AD see https://support.google.com/google-ads/answer/1722096 Media bundles that are part of dynamic product types use a special format that needs to be created through the Google Web Designer. See https://support.google.com/webdesigner/answer/7543898 for more information.
asset string
The Asset resource name of this media bundle.
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.
Child Fields
description string
The description of the ad.
description2 string
The second description of the ad.
expanded_text_ad object
Details pertaining to an expanded text ad.
Child Fields
description string
The description of the ad.
description2 string
The second description of the ad.
headline_part1 string
The first part of the ad's headline.
headline_part2 string
The second part of the ad's headline.
headline_part3 string
The third part of the ad's headline.
path1 string
The text that can appear alongside the ad's displayed URL.
path2 string
Additional text that can appear alongside the ad's displayed URL.
gmail_ad object
Immutable. Details pertaining to a Gmail ad.
Child Fields
header_image string
The MediaFile resource name of the header image. Valid image types are GIF, JPEG and PNG. The minimum size is 300x100 pixels and the aspect ratio must be between 3:1 and 5:1 (+-1%).
marketing_image string
The MediaFile resource name of the marketing image. Valid image types are GIF, JPEG and PNG. The image must either be landscape with a minimum size of 600x314 pixels and aspect ratio of 600:314 (+-1%) or square with a minimum size of 300x300 pixels and aspect ratio of 1:1 (+-1%)
marketing_image_description string
Description of the marketing image.
marketing_image_display_call_to_action object
Display-call-to-action of the marketing image.
text string
Text for the display-call-to-action.
text_color string
Text color for the display-call-to-action in hexadecimal, e.g. #ffffff for white.
url_collection_id string
Identifies the url collection in the ad.url_collections field. If not set the url defaults to final_url.
marketing_image_headline string
Headline of the marketing image.
product_images array of objects
Product images. Up to 15 images are supported.
description string
Description of the product.
display_call_to_action object
Display-call-to-action of the product image.
text string
Text for the display-call-to-action.
text_color string
Text color for the display-call-to-action in hexadecimal, e.g. #ffffff for white.
url_collection_id string
Identifies the url collection in the ad.url_collections field. If not set the url defaults to final_url.
product_image string
The MediaFile resource name of the product image. Valid image types are GIF, JPEG and PNG. The minimum size is 300x300 pixels and the aspect ratio must be 1:1 (+-1%).
product_videos array of objects
Product videos. Up to 7 videos are supported. At least one product video or a marketing image must be specified.
product_video string
The MediaFile resource name of a video which must be hosted on YouTube.
teaser object
The Gmail teaser.
business_name string
Business name of the advertiser.
description string
Description of the teaser.
headline string
Headline of the teaser.
logo_image string
The MediaFile resource name of the logo image. Valid image types are GIF, JPEG and PNG. The minimum size is 144x144 pixels and the aspect ratio must be 1:1 (+-1%).
hotel_ad object
Details pertaining to a hotel ad.
Child Fields
image_ad object
Immutable. Details pertaining to an Image ad.
Child Fields
ad_id_to_copy_image_from int64
An ad ID to copy the image from.
data byte
Raw image data as bytes.
image_url string
URL of the full size image.
media_file string
The MediaFile resource to use for the image.
mime_type enum
The mime type of the image.
UNSPECIFIED (0)
The mime type has not been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
IMAGE_JPEG (2)
MIME type of image/jpeg.
IMAGE_GIF (3)
MIME type of image/gif.
IMAGE_PNG (4)
MIME type of image/png.
FLASH (5)
MIME type of application/x-shockwave-flash.
TEXT_HTML (6)
MIME type of text/html.
PDF (7)
MIME type of application/pdf.
MSWORD (8)
MIME type of application/msword.
MSEXCEL (9)
MIME type of application/vnd.ms-excel.
RTF (10)
MIME type of application/rtf.
AUDIO_WAV (11)
MIME type of audio/wav.
AUDIO_MP3 (12)
MIME type of audio/mp3.
HTML5_AD_ZIP (13)
MIME type of application/x-html5-ad-zip.
name string
The name of the image. If the image was created from a MediaFile, this is the MediaFile's name. If the image was created from bytes, this is empty.
pixel_height int64
Height in pixels of the full size image.
pixel_width int64
Width in pixels of the full size image.
preview_image_url string
URL of the preview size image.
preview_pixel_height int64
Height in pixels of the preview size image.
preview_pixel_width int64
Width in pixels of the preview size image.
legacy_app_install_ad object
Immutable. Details pertaining to a legacy app install ad.
Child Fields
app_id string
The id of the mobile app.
app_store enum
The app store the mobile app is available in.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
APPLE_APP_STORE (2)
Apple iTunes.
GOOGLE_PLAY (3)
Google Play.
WINDOWS_STORE (4)
Windows Store.
WINDOWS_PHONE_STORE (5)
Windows Phone Store.
CN_APP_STORE (6)
The app is hosted in a Chinese app store.
description1 string
The first description line of the ad.
description2 string
The second description line of the ad.
headline string
The headline of the ad.
legacy_responsive_display_ad object
Details pertaining to a legacy responsive display ad.
Child Fields
accent_color string
The accent color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
allow_flexible_color boolean
Advertiser's consent to allow flexible color. When true, the ad may be served with different color if necessary. When false, the ad will be served with the specified colors or a neutral color. The default value is true. Must be true if main_color and accent_color are not set.
business_name string
The business name in the ad.
call_to_action_text string
The call-to-action text for the ad.
description string
The description of the ad.
format_setting enum
Specifies which format the ad will be served in. Default is ALL_FORMATS.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
ALL_FORMATS (2)
Text, image and native formats.
NON_NATIVE (3)
Text and image formats.
NATIVE (4)
Native format, i.e. the format rendering is controlled by the publisher and not by Google.
logo_image string
The MediaFile resource name of the logo image used in the ad.
long_headline string
The long version of the ad's headline.
main_color string
The main color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
marketing_image string
The MediaFile resource name of the marketing image used in the ad.
price_prefix string
Prefix before price. E.g. 'as low as'.
promo_text string
Promotion text used for dyanmic formats of responsive ads. For example 'Free two-day shipping'.
short_headline string
The short version of the ad's headline.
square_logo_image string
The MediaFile resource name of the square logo image used in the ad.
square_marketing_image string
The MediaFile resource name of the square marketing image used in the ad.
local_ad object
Details pertaining to a local ad.
Child Fields
call_to_actions array of objects
List of text assets for call-to-actions. When the ad serves the call-to-actions will be selected from this list. Call-to-actions are optional and at most 5 can be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list. At least 1 and at most 5 descriptions must be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list. At least 1 and at most 5 headlines must be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
logo_images array of objects
List of logo image assets that may be displayed with the ad. The images must be 128x128 pixels and not larger than 120KB. At least 1 and at most 5 image assets must be specified.
asset string
The Asset resource name of this image.
marketing_images array of objects
List of marketing image assets that may be displayed with the ad. The images must be 314x600 pixels or 320x320 pixels. At least 1 and at most 20 image assets must be specified.
asset string
The Asset resource name of this image.
path1 string
First part of optional text that may appear appended to the url displayed in the ad.
path2 string
Second part of optional text that may appear appended to the url displayed in the ad. This field can only be set when path1 is also set.
videos array of objects
List of YouTube video assets that may be displayed with the ad. Videos are optional and at most 20 can be specified.
asset string
The Asset resource name of this video.
responsive_display_ad object
Details pertaining to a responsive display ad.
Child Fields
accent_color string
The accent color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
allow_flexible_color boolean
Advertiser's consent to allow flexible color. When true, the ad may be served with different color if necessary. When false, the ad will be served with the specified colors or a neutral color. The default value is true. Must be true if main_color and accent_color are not set.
business_name string
The advertiser/brand name. Maximum display width is 25.
call_to_action_text string
The call-to-action text for the ad. Maximum display width is 30.
descriptions array of objects
Descriptive texts for the ad. The maximum length is 90 characters. At least 1 and max 5 headlines can be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
format_setting enum
Specifies which format the ad will be served in. Default is ALL_FORMATS.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
ALL_FORMATS (2)
Text, image and native formats.
NON_NATIVE (3)
Text and image formats.
NATIVE (4)
Native format, i.e. the format rendering is controlled by the publisher and not by Google.
headlines array of objects
Short format headlines for the ad. The maximum length is 30 characters. At least 1 and max 5 headlines can be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
logo_images array of objects
Logo images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 512x128 and the aspect ratio must be 4:1 (+-1%). Combined with square_logo_images the maximum is 5.
asset string
The Asset resource name of this image.
long_headline object
A required long format headline. The maximum length is 90 characters.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
main_color string
The main color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
marketing_images array of objects
Marketing images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 600x314 and the aspect ratio must be 1.91:1 (+-1%). At least one marketing_image is required. Combined with square_marketing_images the maximum is 15.
asset string
The Asset resource name of this image.
price_prefix string
Prefix before price. E.g. 'as low as'.
promo_text string
Promotion text used for dyanmic formats of responsive ads. For example 'Free two-day shipping'.
square_logo_images array of objects
Square logo images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 128x128 and the aspect ratio must be 1:1 (+-1%). Combined with square_logo_images the maximum is 5.
asset string
The Asset resource name of this image.
square_marketing_images array of objects
Square marketing images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 300x300 and the aspect ratio must be 1:1 (+-1%). At least one square marketing_image is required. Combined with marketing_images the maximum is 15.
asset string
The Asset resource name of this image.
youtube_videos array of objects
Optional YouTube videos for the ad. A maximum of 5 videos can be specified.
asset string
The Asset resource name of this video.
responsive_search_ad object
Details pertaining to a responsive search ad.
Child Fields
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
path1 string
First part of text that may appear appended to the url displayed in the ad.
path2 string
Second part of text that may appear appended to the url displayed in the ad. This field can only be set when path1 is also set.
shopping_comparison_listing_ad object
Details pertaining to a Shopping Comparison Listing ad.
Child Fields
headline string
Headline of the ad. This field is required. Allowed length is between 25 and 45 characters.
shopping_product_ad object
Details pertaining to a Shopping product ad.
Child Fields
shopping_smart_ad object
Details pertaining to a Smart Shopping ad.
Child Fields
text_ad object
Immutable. Details pertaining to a text ad.
Child Fields
description1 string
The first line of the ad's description.
description2 string
The second line of the ad's description.
headline string
The headline of the ad.
video_ad object
Details pertaining to a Video ad.
Child Fields
bumper object
Video bumper in-stream ad format.
companion_banner string
The MediaFile resource name of the companion banner used with the ad.
discovery object
Video TrueView discovery ad format.
description1 string
First text line for a TrueView video discovery ad.
description2 string
Second text line for a TrueView video discovery ad.
headline string
The headline of the ad.
in_stream object
Video TrueView in-stream ad format.
action_button_label string
Label on the CTA (call-to-action) button taking the user to the video ad's final URL. Required for TrueView for action campaigns, optional otherwise.
action_headline string
Additional text displayed with the CTA (call-to-action) button to give context and encourage clicking on the button.
companion_banner string
The MediaFile resource name of the companion banner used with the ad.
media_file string
The MediaFile resource to use for the video.
non_skippable object
Video non-skippable in-stream ad format.
companion_banner string
The MediaFile resource name of the companion banner used with the ad.
out_stream object
Video out-stream ad format.
description string
The description line.
headline string
The headline of the 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.

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.

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.

tracking_url_template string

The URL template for constructing a tracking URL.

type enum

Output only. The type of 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.

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.

// Example Ad
const ad = {
  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: [],
}

Get an Ad

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

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.

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.

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.

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.

explorer_auto_optimizer_setting object

Settings for the Display Campaign Optimizer, initially termed "Explorer".

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.

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.

target_restrictions array of objects

The per-targeting-dimension setting to restrict the reach of your campaign or ad group.

tracking_url_template string

The URL template for constructing a tracking URL.

type enum

Immutable. The type of the ad 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.

// 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.

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.
Child Fields
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
html_5_media_bundles array of objects
List of media bundle assets that may be used with the ad.
asset string
The Asset resource name of this media bundle.
images array of objects
List of image assets that may be displayed with the ad.
asset string
The Asset resource name of this image.
mandatory_ad_text object
An optional text asset that, if specified, must always be displayed when the ad is served.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
youtube_videos array of objects
List of YouTube video assets that may be displayed with the ad.
asset string
The Asset resource name of this video.
app_engagement_ad object
Details pertaining to an app engagement ad.
Child Fields
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
images array of objects
List of image assets that may be displayed with the ad.
asset string
The Asset resource name of this image.
videos array of objects
List of video assets that may be displayed with the ad.
asset string
The Asset resource name of this video.
call_only_ad object
Details pertaining to a call-only ad.
Child Fields
business_name string
The business name in the ad.
call_tracked boolean
Whether to enable call tracking for the creative. Enabling call tracking also enables call conversions.
conversion_action string
The conversion action to attribute a call conversion to. If not set a default conversion action is used. This field only has effect if call_tracked is set to true. Otherwise this field is ignored.
conversion_reporting_state enum
The call conversion behavior of this call only ad. It can use its own call conversion setting, inherit the account level setting, or be disabled.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
DISABLED (2)
Call conversion action is disabled.
USE_ACCOUNT_LEVEL_CALL_CONVERSION_ACTION (3)
Call conversion action will use call conversion type set at the account level.
USE_RESOURCE_LEVEL_CALL_CONVERSION_ACTION (4)
Call conversion action will use call conversion type set at the resource (call only ads/call extensions) level.
country_code string
The country code in the ad.
description1 string
The first line of the ad's description.
description2 string
The second line of the ad's description.
disable_call_conversion boolean
Whether to disable call conversion for the creative. If set to true, disables call conversions even when call_tracked is true. If call_tracked is false, this field is ignored.
headline1 string
First headline in the ad.
headline2 string
Second headline in the ad.
phone_number string
The phone number in the ad.
phone_number_verification_url string
The URL to be used for phone number verification.
display_upload_ad object
Details pertaining to a display upload ad.
Child Fields
display_upload_product_type enum
The product type of this ad. See comments on the enum for details.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
HTML5_UPLOAD_AD (2)
HTML5 upload ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set.
DYNAMIC_HTML5_EDUCATION_AD (3)
Dynamic HTML5 education ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in an education campaign.
DYNAMIC_HTML5_FLIGHT_AD (4)
Dynamic HTML5 flight ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a flight campaign.
DYNAMIC_HTML5_HOTEL_RENTAL_AD (5)
Dynamic HTML5 hotel and rental ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a hotel campaign.
DYNAMIC_HTML5_JOB_AD (6)
Dynamic HTML5 job ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a job campaign.
DYNAMIC_HTML5_LOCAL_AD (7)
Dynamic HTML5 local ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a local campaign.
DYNAMIC_HTML5_REAL_ESTATE_AD (8)
Dynamic HTML5 real estate ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a real estate campaign.
DYNAMIC_HTML5_CUSTOM_AD (9)
Dynamic HTML5 custom ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a custom campaign.
DYNAMIC_HTML5_TRAVEL_AD (10)
Dynamic HTML5 travel ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a travel campaign.
DYNAMIC_HTML5_HOTEL_AD (11)
Dynamic HTML5 hotel ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a hotel campaign.
media_bundle object
A media bundle asset to be used in the ad. For information about the media bundle for HTML5_UPLOAD_AD see https://support.google.com/google-ads/answer/1722096 Media bundles that are part of dynamic product types use a special format that needs to be created through the Google Web Designer. See https://support.google.com/webdesigner/answer/7543898 for more information.
asset string
The Asset resource name of this media bundle.
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.
Child Fields
description string
The description of the ad.
description2 string
The second description of the ad.
expanded_text_ad object
Details pertaining to an expanded text ad.
Child Fields
description string
The description of the ad.
description2 string
The second description of the ad.
headline_part1 string
The first part of the ad's headline.
headline_part2 string
The second part of the ad's headline.
headline_part3 string
The third part of the ad's headline.
path1 string
The text that can appear alongside the ad's displayed URL.
path2 string
Additional text that can appear alongside the ad's displayed URL.
gmail_ad object
Immutable. Details pertaining to a Gmail ad.
Child Fields
header_image string
The MediaFile resource name of the header image. Valid image types are GIF, JPEG and PNG. The minimum size is 300x100 pixels and the aspect ratio must be between 3:1 and 5:1 (+-1%).
marketing_image string
The MediaFile resource name of the marketing image. Valid image types are GIF, JPEG and PNG. The image must either be landscape with a minimum size of 600x314 pixels and aspect ratio of 600:314 (+-1%) or square with a minimum size of 300x300 pixels and aspect ratio of 1:1 (+-1%)
marketing_image_description string
Description of the marketing image.
marketing_image_display_call_to_action object
Display-call-to-action of the marketing image.
text string
Text for the display-call-to-action.
text_color string
Text color for the display-call-to-action in hexadecimal, e.g. #ffffff for white.
url_collection_id string
Identifies the url collection in the ad.url_collections field. If not set the url defaults to final_url.
marketing_image_headline string
Headline of the marketing image.
product_images array of objects
Product images. Up to 15 images are supported.
description string
Description of the product.
display_call_to_action object
Display-call-to-action of the product image.
text string
Text for the display-call-to-action.
text_color string
Text color for the display-call-to-action in hexadecimal, e.g. #ffffff for white.
url_collection_id string
Identifies the url collection in the ad.url_collections field. If not set the url defaults to final_url.
product_image string
The MediaFile resource name of the product image. Valid image types are GIF, JPEG and PNG. The minimum size is 300x300 pixels and the aspect ratio must be 1:1 (+-1%).
product_videos array of objects
Product videos. Up to 7 videos are supported. At least one product video or a marketing image must be specified.
product_video string
The MediaFile resource name of a video which must be hosted on YouTube.
teaser object
The Gmail teaser.
business_name string
Business name of the advertiser.
description string
Description of the teaser.
headline string
Headline of the teaser.
logo_image string
The MediaFile resource name of the logo image. Valid image types are GIF, JPEG and PNG. The minimum size is 144x144 pixels and the aspect ratio must be 1:1 (+-1%).
hotel_ad object
Details pertaining to a hotel ad.
Child Fields
image_ad object
Immutable. Details pertaining to an Image ad.
Child Fields
ad_id_to_copy_image_from int64
An ad ID to copy the image from.
data byte
Raw image data as bytes.
image_url string
URL of the full size image.
media_file string
The MediaFile resource to use for the image.
mime_type enum
The mime type of the image.
UNSPECIFIED (0)
The mime type has not been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
IMAGE_JPEG (2)
MIME type of image/jpeg.
IMAGE_GIF (3)
MIME type of image/gif.
IMAGE_PNG (4)
MIME type of image/png.
FLASH (5)
MIME type of application/x-shockwave-flash.
TEXT_HTML (6)
MIME type of text/html.
PDF (7)
MIME type of application/pdf.
MSWORD (8)
MIME type of application/msword.
MSEXCEL (9)
MIME type of application/vnd.ms-excel.
RTF (10)
MIME type of application/rtf.
AUDIO_WAV (11)
MIME type of audio/wav.
AUDIO_MP3 (12)
MIME type of audio/mp3.
HTML5_AD_ZIP (13)
MIME type of application/x-html5-ad-zip.
name string
The name of the image. If the image was created from a MediaFile, this is the MediaFile's name. If the image was created from bytes, this is empty.
pixel_height int64
Height in pixels of the full size image.
pixel_width int64
Width in pixels of the full size image.
preview_image_url string
URL of the preview size image.
preview_pixel_height int64
Height in pixels of the preview size image.
preview_pixel_width int64
Width in pixels of the preview size image.
legacy_app_install_ad object
Immutable. Details pertaining to a legacy app install ad.
Child Fields
app_id string
The id of the mobile app.
app_store enum
The app store the mobile app is available in.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
APPLE_APP_STORE (2)
Apple iTunes.
GOOGLE_PLAY (3)
Google Play.
WINDOWS_STORE (4)
Windows Store.
WINDOWS_PHONE_STORE (5)
Windows Phone Store.
CN_APP_STORE (6)
The app is hosted in a Chinese app store.
description1 string
The first description line of the ad.
description2 string
The second description line of the ad.
headline string
The headline of the ad.
legacy_responsive_display_ad object
Details pertaining to a legacy responsive display ad.
Child Fields
accent_color string
The accent color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
allow_flexible_color boolean
Advertiser's consent to allow flexible color. When true, the ad may be served with different color if necessary. When false, the ad will be served with the specified colors or a neutral color. The default value is true. Must be true if main_color and accent_color are not set.
business_name string
The business name in the ad.
call_to_action_text string
The call-to-action text for the ad.
description string
The description of the ad.
format_setting enum
Specifies which format the ad will be served in. Default is ALL_FORMATS.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
ALL_FORMATS (2)
Text, image and native formats.
NON_NATIVE (3)
Text and image formats.
NATIVE (4)
Native format, i.e. the format rendering is controlled by the publisher and not by Google.
logo_image string
The MediaFile resource name of the logo image used in the ad.
long_headline string
The long version of the ad's headline.
main_color string
The main color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
marketing_image string
The MediaFile resource name of the marketing image used in the ad.
price_prefix string
Prefix before price. E.g. 'as low as'.
promo_text string
Promotion text used for dyanmic formats of responsive ads. For example 'Free two-day shipping'.
short_headline string
The short version of the ad's headline.
square_logo_image string
The MediaFile resource name of the square logo image used in the ad.
square_marketing_image string
The MediaFile resource name of the square marketing image used in the ad.
local_ad object
Details pertaining to a local ad.
Child Fields
call_to_actions array of objects
List of text assets for call-to-actions. When the ad serves the call-to-actions will be selected from this list. Call-to-actions are optional and at most 5 can be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list. At least 1 and at most 5 descriptions must be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list. At least 1 and at most 5 headlines must be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
logo_images array of objects
List of logo image assets that may be displayed with the ad. The images must be 128x128 pixels and not larger than 120KB. At least 1 and at most 5 image assets must be specified.
asset string
The Asset resource name of this image.
marketing_images array of objects
List of marketing image assets that may be displayed with the ad. The images must be 314x600 pixels or 320x320 pixels. At least 1 and at most 20 image assets must be specified.
asset string
The Asset resource name of this image.
path1 string
First part of optional text that may appear appended to the url displayed in the ad.
path2 string
Second part of optional text that may appear appended to the url displayed in the ad. This field can only be set when path1 is also set.
videos array of objects
List of YouTube video assets that may be displayed with the ad. Videos are optional and at most 20 can be specified.
asset string
The Asset resource name of this video.
responsive_display_ad object
Details pertaining to a responsive display ad.
Child Fields
accent_color string
The accent color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
allow_flexible_color boolean
Advertiser's consent to allow flexible color. When true, the ad may be served with different color if necessary. When false, the ad will be served with the specified colors or a neutral color. The default value is true. Must be true if main_color and accent_color are not set.
business_name string
The advertiser/brand name. Maximum display width is 25.
call_to_action_text string
The call-to-action text for the ad. Maximum display width is 30.
descriptions array of objects
Descriptive texts for the ad. The maximum length is 90 characters. At least 1 and max 5 headlines can be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
format_setting enum
Specifies which format the ad will be served in. Default is ALL_FORMATS.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
ALL_FORMATS (2)
Text, image and native formats.
NON_NATIVE (3)
Text and image formats.
NATIVE (4)
Native format, i.e. the format rendering is controlled by the publisher and not by Google.
headlines array of objects
Short format headlines for the ad. The maximum length is 30 characters. At least 1 and max 5 headlines can be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
logo_images array of objects
Logo images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 512x128 and the aspect ratio must be 4:1 (+-1%). Combined with square_logo_images the maximum is 5.
asset string
The Asset resource name of this image.
long_headline object
A required long format headline. The maximum length is 90 characters.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
main_color string
The main color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
marketing_images array of objects
Marketing images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 600x314 and the aspect ratio must be 1.91:1 (+-1%). At least one marketing_image is required. Combined with square_marketing_images the maximum is 15.
asset string
The Asset resource name of this image.
price_prefix string
Prefix before price. E.g. 'as low as'.
promo_text string
Promotion text used for dyanmic formats of responsive ads. For example 'Free two-day shipping'.
square_logo_images array of objects
Square logo images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 128x128 and the aspect ratio must be 1:1 (+-1%). Combined with square_logo_images the maximum is 5.
asset string
The Asset resource name of this image.
square_marketing_images array of objects
Square marketing images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 300x300 and the aspect ratio must be 1:1 (+-1%). At least one square marketing_image is required. Combined with marketing_images the maximum is 15.
asset string
The Asset resource name of this image.
youtube_videos array of objects
Optional YouTube videos for the ad. A maximum of 5 videos can be specified.
asset string
The Asset resource name of this video.
responsive_search_ad object
Details pertaining to a responsive search ad.
Child Fields
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
path1 string
First part of text that may appear appended to the url displayed in the ad.
path2 string
Second part of text that may appear appended to the url displayed in the ad. This field can only be set when path1 is also set.
shopping_comparison_listing_ad object
Details pertaining to a Shopping Comparison Listing ad.
Child Fields
headline string
Headline of the ad. This field is required. Allowed length is between 25 and 45 characters.
shopping_product_ad object
Details pertaining to a Shopping product ad.
Child Fields
shopping_smart_ad object
Details pertaining to a Smart Shopping ad.
Child Fields
text_ad object
Immutable. Details pertaining to a text ad.
Child Fields
description1 string
The first line of the ad's description.
description2 string
The second line of the ad's description.
headline string
The headline of the ad.
video_ad object
Details pertaining to a Video ad.
Child Fields
bumper object
Video bumper in-stream ad format.
companion_banner string
The MediaFile resource name of the companion banner used with the ad.
discovery object
Video TrueView discovery ad format.
description1 string
First text line for a TrueView video discovery ad.
description2 string
Second text line for a TrueView video discovery ad.
headline string
The headline of the ad.
in_stream object
Video TrueView in-stream ad format.
action_button_label string
Label on the CTA (call-to-action) button taking the user to the video ad's final URL. Required for TrueView for action campaigns, optional otherwise.
action_headline string
Additional text displayed with the CTA (call-to-action) button to give context and encourage clicking on the button.
companion_banner string
The MediaFile resource name of the companion banner used with the ad.
media_file string
The MediaFile resource to use for the video.
non_skippable object
Video non-skippable in-stream ad format.
companion_banner string
The MediaFile resource name of the companion banner used with the ad.
out_stream object
Video out-stream ad format.
description string
The description line.
headline string
The headline of the 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.

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.

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.

tracking_url_template string

The URL template for constructing a tracking URL.

type enum

Output only. The type of 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.

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.

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.

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.

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).

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.

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.

destination_text_list object

The text in the destination of the resource that is causing a policy finding.

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.

website_list object

List of websites linked with this resource.

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.

review_status enum

Output only. Where in the review process this ad is.

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.

// 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.

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.

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.
Child Fields
type enum
Type of the device.
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.
hotel_advance_booking_window object
Immutable. Criterion for number of days prior to the stay the booking is being made.
Child Fields
max_days int64
High end of the number of days prior to the stay.
min_days int64
Low end of the number of days prior to the stay.
hotel_check_in_day object
Immutable. Criterion for day of the week the booking is for.
Child Fields
day_of_week enum
The day of the week.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
MONDAY (2)
Monday.
TUESDAY (3)
Tuesday.
WEDNESDAY (4)
Wednesday.
THURSDAY (5)
Thursday.
FRIDAY (6)
Friday.
SATURDAY (7)
Saturday.
SUNDAY (8)
Sunday.
hotel_date_selection_type object
Immutable. Criterion for hotel date selection (default dates vs. user selected).
Child Fields
type enum
Type of the hotel date selection
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
DEFAULT_SELECTION (50)
Dates selected by default.
USER_SELECTED (51)
Dates selected by the user.
hotel_length_of_stay object
Immutable. Criterion for length of hotel stay in nights.
Child Fields
max_nights int64
High end of the number of nights in the stay.
min_nights int64
Low end of the number of nights in the stay.
preferred_content object
Immutable. A preferred content criterion.
Child Fields
type enum
Type of the preferred content.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
YOUTUBE_TOP_CONTENT (400)
Represents top content on YouTube.

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.

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.

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.
Child Fields
type enum
Type of the age range.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
AGE_RANGE_18_24 (503001)
Between 18 and 24 years old.
AGE_RANGE_25_34 (503002)
Between 25 and 34 years old.
AGE_RANGE_35_44 (503003)
Between 35 and 44 years old.
AGE_RANGE_45_54 (503004)
Between 45 and 54 years old.
AGE_RANGE_55_64 (503005)
Between 55 and 64 years old.
AGE_RANGE_65_UP (503006)
65 years old and beyond.
AGE_RANGE_UNDETERMINED (503999)
Undetermined age range.
app_payment_model object
Immutable. App Payment Model.
Child Fields
type enum
Type of the app payment model.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
PAID (30)
Represents paid-for apps.
custom_affinity object
Immutable. Custom Affinity.
Child Fields
custom_affinity string
The CustomInterest resource name.
custom_intent object
Immutable. Custom Intent.
Child Fields
custom_intent string
The CustomInterest resource name.
gender object
Immutable. Gender.
Child Fields
type enum
Type of the gender.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
MALE (10)
Male.
FEMALE (11)
Female.
UNDETERMINED (20)
Undetermined gender.
income_range object
Immutable. Income range.
Child Fields
type enum
Type of the income range.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
INCOME_RANGE_0_50 (510001)
0%-50%.
INCOME_RANGE_50_60 (510002)
50% to 60%.
INCOME_RANGE_60_70 (510003)
60% to 70%.
INCOME_RANGE_70_80 (510004)
70% to 80%.
INCOME_RANGE_80_90 (510005)
80% to 90%.
INCOME_RANGE_90_UP (510006)
Greater than 90%.
INCOME_RANGE_UNDETERMINED (510000)
Undetermined income range.
keyword object
Immutable. Keyword.
Child Fields
match_type enum
The match type of the keyword.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EXACT (2)
Exact match.
PHRASE (3)
Phrase match.
BROAD (4)
Broad match.
text string
The text of the keyword (at most 80 characters and 10 words).
listing_group object
Immutable. Listing group.
Child Fields
case_value object
Dimension value with which this listing group is refining its parent. Undefined for the root group.
hotel_city object
City the hotel is located in.
city_criterion string
The Geo Target Constant resource name.
hotel_class object
Class of the hotel as a number of stars 1 to 5.
value int64
Long value of the hotel class.
hotel_country_region object
Country or Region the hotel is located in.
country_region_criterion string
The Geo Target Constant resource name.
hotel_id object
Advertiser-specific hotel ID.
value string
String value of the hotel ID.
hotel_state object
State the hotel is located in.
state_criterion string
The Geo Target Constant resource name.
product_bidding_category object
Bidding category of a product offer.
country_code string
Two-letter upper-case country code of the product bidding category. It must match the campaign.shopping_setting.sales_country field.
id int64
ID of the product bidding category. This ID is equivalent to the google_product_category ID as described in this article: https://support.google.com/merchants/answer/6324436
level enum
Level of the product bidding category.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
LEVEL1 (7)
Level 1.
LEVEL2 (8)
Level 2.
LEVEL3 (9)
Level 3.
LEVEL4 (10)
Level 4.
LEVEL5 (11)
Level 5.
product_brand object
Brand of a product offer.
value string
String value of the product brand.
product_channel object
Locality of a product offer.
channel enum
Value of the locality.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
ONLINE (2)
The item is sold online.
LOCAL (3)
The item is sold in local stores.
product_channel_exclusivity object
Availability of a product offer.
channel_exclusivity enum
Value of the availability.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
SINGLE_CHANNEL (2)
The item is sold through one channel only, either local stores or online as indicated by its ProductChannel.
MULTI_CHANNEL (3)
The item is matched to its online or local stores counterpart, indicating it is available for purchase in both ShoppingProductChannels.
product_condition object
Condition of a product offer.
condition enum
Value of the condition.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
NEW (3)
The product condition is new.
REFURBISHED (4)
The product condition is refurbished.
USED (5)
The product condition is used.
product_custom_attribute object
Custom attribute of a product offer.
index enum
Indicates the index of the custom attribute.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
INDEX0 (7)
First product custom attribute.
INDEX1 (8)
Second product custom attribute.
INDEX2 (9)
Third product custom attribute.
INDEX3 (10)
Fourth product custom attribute.
INDEX4 (11)
Fifth product custom attribute.
value string
String value of the product custom attribute.
product_item_id object
Item id of a product offer.
value string
Value of the id.
product_type object
Type of a product offer.
level enum
Level of the type.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
LEVEL1 (7)
Level 1.
LEVEL2 (8)
Level 2.
LEVEL3 (9)
Level 3.
LEVEL4 (10)
Level 4.
LEVEL5 (11)
Level 5.
value string
Value of the type.
unknown_listing_dimension object
Unknown dimension. Set when no other listing dimension is set.
parent_ad_group_criterion string
Resource name of ad group criterion which is the parent listing group subdivision. Null for the root group.
type enum
Type of the listing group.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
SUBDIVISION (2)
Subdivision of products along some listing dimension. These nodes are not used by serving to target listing entries, but is purely to define the structure of the tree.
UNIT (3)
Listing group unit that defines a bid.
mobile_app_category object
Immutable. Mobile app category.
Child Fields
mobile_app_category_constant string
The mobile app category constant resource name.
mobile_application object
Immutable. Mobile application.
Child Fields
app_id string
A string that uniquely identifies a mobile application to Google Ads API. The format of this string is "{platform}-{platform_native_id}", where platform is "1" for iOS apps and "2" for Android apps, and where platform_native_id is the mobile application identifier native to the corresponding platform. For iOS, this native identifier is the 9 digit string that appears at the end of an App Store URL (e.g., "476943146" for "Flood-It! 2" whose App Store link is "http://itunes.apple.com/us/app/flood-it!-2/id476943146"). For Android, this native identifier is the application's package name (e.g., "com.labpixies.colordrips" for "Color Drips" given Google Play link "https://play.google.com/store/apps/details?id=com.labpixies.colordrips"). A well formed app id for Google Ads API would thus be "1-476943146" for iOS and "2-com.labpixies.colordrips" for Android. This field is required and must be set in CREATE operations.
name string
Name of this mobile application.
parental_status object
Immutable. Parental status.
Child Fields
type enum
Type of the parental status.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
PARENT (300)
Parent.
NOT_A_PARENT (301)
Not a parent.
UNDETERMINED (302)
Undetermined parental status.
placement object
Immutable. Placement.
Child Fields
url string
URL of the placement. For example, "http://www.domain.com".
topic object
Immutable. Topic.
Child Fields
path array of strings
The category to target or exclude. Each subsequent element in the array describes a more specific sub-category. For example, "Pets & Animals", "Pets", "Dogs" represents the "Pets & Animals/Pets/Dogs" category.
topic_constant string
The Topic Constant resource name.
user_interest object
Immutable. User Interest.
Child Fields
user_interest_category string
The UserInterest resource name.
user_list object
Immutable. User List.
Child Fields
user_list string
The User List resource name.
webpage object
Immutable. Webpage
Child Fields
conditions array of objects
Conditions, or logical expressions, for webpage targeting. The list of webpage targeting conditions are and-ed together when evaluated for targeting. This field is required for CREATE operations and is prohibited on UPDATE operations.
argument string
Argument of webpage targeting condition.
operand enum
Operand of webpage targeting condition.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
URL (2)
Operand denoting a webpage URL targeting condition.
CATEGORY (3)
Operand denoting a webpage category targeting condition.
PAGE_TITLE (4)
Operand denoting a webpage title targeting condition.
PAGE_CONTENT (5)
Operand denoting a webpage content targeting condition.
CUSTOM_LABEL (6)
Operand denoting a webpage custom label targeting condition.
operator enum
Operator of webpage targeting condition.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EQUALS (2)
The argument web condition is equal to the compared web condition.
CONTAINS (3)
The argument web condition is part of the compared web condition.
criterion_name string
The name of the criterion that is defined by this parameter. The name value will be used for identifying, sorting and filtering criteria with this type of parameters. This field is required for CREATE operations and is prohibited on UPDATE operations.
youtube_channel object
Immutable. YouTube Channel.
Child Fields
channel_id string
The YouTube uploader channel id or the channel code of a YouTube channel.
youtube_video object
Immutable. YouTube Video.
Child Fields
video_id string
YouTube video id as it appears on the YouTube watch page.

ad_group string

Immutable. The ad group to which the criterion belongs.

approval_status enum

Output only. Approval status of the criterion.

bid_modifier double

The modifier for the bid when the criterion matches. The modifier must be in the range: 0.1 - 10.0. Most targetable criteria types support modifiers.

cpc_bid_micros int64

The CPC (cost-per-click) bid.

cpm_bid_micros int64

The CPM (cost-per-thousand viewable impressions) bid.

cpv_bid_micros int64

The CPV (cost-per-view) bid.

criterion_id int64

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.

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.

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.

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.

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.

quality_info object

Output only. Information regarding the quality of the criterion.

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.

system_serving_status enum

Output only. Serving status of the criterion.

tracking_url_template string

The URL template for constructing a tracking URL.

type enum

Output only. The type of the criterion.

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.

// 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.

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.

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.

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.

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.

// 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.

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: {
        creative_quality_score: 4,
        post_click_quality_score: 3,
        quality_score: 5,
        search_predicted_ctr: 2,
      },
      resource_name: 'customers/3827277046/adGroupCriteria/77057369032~391658604416',
      status: 2,
      system_serving_status: 2,
      type: 2,
      url_custom_parameters: [],
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/77057369032',
      campaign: 'customers/3827277046/campaigns/2081620945',
      cpc_bid_micros: 6310000,
      cpm_bid_micros: 10000000,
      cpv_bid_micros: 0,
      display_custom_bid_dimension: 0,
      effective_target_cpa_micros: 12000000,
      effective_target_cpa_source: 6,
      effective_target_roas_source: 0,
      explorer_auto_optimizer_setting: { opt_in: false },
      id: 77057369032,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/77057369032',
      status: 2,
      target_cpa_micros: 12000000,
      target_cpm_micros: 10000,
      targeting_setting: {
        target_restrictions: [
          { targeting_dimension: 3, bid_only: true },
          { 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: 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/3827277046/campaigns/2081620945',
      bidding_strategy_type: 3,
      campaign_budget: 'customers/3827277046/campaignBudgets/6449346159',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 5, positive_geo_target_type: 7 },
      id: 2081620945,
      labels: [
        'customers/3827277046/labels/3889728216',
        'customers/3827277046/labels/3889728468',
        'customers/3827277046/labels/3889728480',
      ],
      manual_cpc: { enhanced_cpc_enabled: true },
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: false,
      },
      optimization_score: 0.7376711477461586,
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/2081620945',
      serving_status: 2,
      start_date: '2019-07-30',
      status: 2,
      targeting_setting: { target_restrictions: [{ targeting_dimension: 3, bid_only: true }] },
      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}',
    },
  },
]

AdGroupExtensionSetting

The AdGroupExtensionSetting object

Fields

ad_group string

Immutable. The resource name of the ad group. The linked extension feed items will serve under this ad group. AdGroup resource names have the form: customers/{customer_id}/adGroups/{ad_group_id}

device enum

The device for which the extensions will serve. Optional.

extension_feed_items array of strings

The resource names of the extension feed items to serve under the ad group. ExtensionFeedItem resource names have the form: customers/{customer_id}/extensionFeedItems/{feed_item_id}

extension_type enum

Immutable. The extension type of the ad group extension setting.

resource_name string

Immutable. The resource name of the ad group extension setting. AdGroupExtensionSetting resource names have the form: customers/{customer_id}/adGroupExtensionSettings/{ad_group_id}~{extension_type}

// Example AdGroupExtensionSetting
const ad_group_extension_setting = {
  ad_group: 'customers/3827277046/adGroups/69639056828',
  device: 0,
  extension_feed_items: [
    'customers/3827277046/extensionFeedItems/48199744867',
    'customers/3827277046/extensionFeedItems/48199839565',
    'customers/3827277046/extensionFeedItems/48200356726',
    'customers/3827277046/extensionFeedItems/48200575108',
    'customers/3827277046/extensionFeedItems/48200618792',
  ],
  extension_type: 10,
  resource_name: 'customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK',
}

Get an AdGroupExtensionSetting

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

Arguments

resource_name required

The resource_name of that AdGroupExtensionSetting

Returns

Returns that AdGroupExtensionSetting as an object.

// Getting the entity
let result = await customer.adGroupExtensionSettings.get(
  'customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK'
)

// Example result
;({
  ad_group: 'customers/3827277046/adGroups/69639056828',
  device: 0,
  extension_feed_items: [
    'customers/3827277046/extensionFeedItems/48199744867',
    'customers/3827277046/extensionFeedItems/48199839565',
    'customers/3827277046/extensionFeedItems/48200356726',
    'customers/3827277046/extensionFeedItems/48200575108',
    'customers/3827277046/extensionFeedItems/48200618792',
  ],
  extension_type: 10,
  resource_name: 'customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK',
})

List every instance of AdGroupExtensionSetting

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

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

Arguments

options optional

Object of the form { limit, order_by, constraints }:
- limit optional, number
  
  Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.
- order_by optional, string
  
  The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.
- constraints optional, array/object
  
  A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupExtensionSettings.list({
  constraints: [
    {
      key: 'ad_group_extension_setting.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_extension_setting.some_field.sub_field',
})

// Example result
;[
  {
    ad_group_extension_setting: {
      ad_group: 'customers/3827277046/adGroups/69639056828',
      device: 0,
      extension_feed_items: [
        'customers/3827277046/extensionFeedItems/48199744867',
        'customers/3827277046/extensionFeedItems/48199839565',
        'customers/3827277046/extensionFeedItems/48200356726',
        'customers/3827277046/extensionFeedItems/48200575108',
        'customers/3827277046/extensionFeedItems/48200618792',
      ],
      extension_type: 10,
      resource_name: 'customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK',
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/69639056828',
      campaign: 'customers/3827277046/campaigns/954460701',
      cpc_bid_micros: 4500000,
      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: 69639056828,
      labels: ['customers/3827277046/labels/3345231412'],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/69639056828',
      status: 2,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { 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: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 5,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/954460701',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/3827277046/campaignBudgets/1234926420',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 7 },
      id: 954460701,
      labels: ['customers/3827277046/labels/3889728471'],
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: false,
      },
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/954460701',
      serving_status: 2,
      start_date: '2017-10-13',
      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 AdGroupExtensionSetting

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

Arguments

entity required

The AdGroupExtensionSetting object or array of objects.
options optional

Object of the form { validate_only, partial_failure }:
- validate_only optional, boolean
  
  When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.
- partial_failure optional, boolean
  
  Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

results

An array of the resource_names created.
partial_failure_error

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

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

// Creating the entity

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

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

// Passing in an array of entities to create, validating only
const result = await customer.adGroupExtensionSettings.create(
  [ad_group_extension_setting, other_ad_group_extension_setting],
  {
    validate_only: true,
  }
)

// Example result
{
	results : ['customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupExtensionSetting

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

Arguments

entity required

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

Object of the form { validate_only, partial_failure }:
- validate_only optional, boolean
  
  When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.
- partial_failure optional, boolean
  
  Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

results

An array of the resource_names updated.
partial_failure_error

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

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

// Updating the entity

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

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

// Passing in an array of entities to update, validating only
const result = await customer.adGroupExtensionSettings.update(
  [ad_group_extension_setting, other_ad_group_extension_setting],
  {
    validate_only: true,
  }
)

// Example result
{
	results : ['customers/3827277046/adGroupExtensionSettings/69639056828~SITELINK'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupExtensionSetting

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

Arguments

resource_name required

The resource_name of that AdGroupExtensionSetting

Returns

Nothing

// Deleting the entity

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

AdGroupFeed

The AdGroupFeed object

Fields

ad_group string

Immutable. The ad group being linked to the feed.

feed string

Immutable. The feed being linked to the ad group.

matching_function object

Matching function associated with the AdGroupFeed. The matching function is used to filter the set of feed items selected. Required.

placeholder_types array of strings

Indicates which placeholder types the feed may populate under the connected ad group. Required.

resource_name string

Immutable. The resource name of the ad group feed. Ad group feed resource names have the form: `customers/{customer_id}/adGroupFeeds/{ad_group_id}~{feed_id}

status enum

Output only. Status of the ad group feed. This field is read-only.

// Example AdGroupFeed
const ad_group_feed = {
  ad_group: 'customers/3827277046/adGroups/69639056828',
  feed: 'customers/3827277046/feeds/43009393',
  matching_function: {
    function_string: 'IN(FEED_ITEM_ID,{48200575108,48199744867,48200356726,48199839565,48200618792})',
    left_operands: [{ request_context_operand: { context_type: 2 } }],
    operator: 2,
    right_operands: [
      { constant_operand: { long_value: 48200575108 } },
      { constant_operand: { long_value: 48199744867 } },
      { constant_operand: { long_value: 48200356726 } },
      { constant_operand: { long_value: 48199839565 } },
      { constant_operand: { long_value: 48200618792 } },
    ],
  },
  placeholder_types: [],
  resource_name: 'customers/3827277046/adGroupFeeds/69639056828~43009393',
  status: 2,
}

Get an AdGroupFeed

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

Arguments

resource_name required

The resource_name of that AdGroupFeed

Returns

Returns that AdGroupFeed as an object.

// Getting the entity
let result = await customer.adGroupFeeds.get('customers/3827277046/adGroupFeeds/69639056828~43009393')

// Example result
;({
  ad_group: 'customers/3827277046/adGroups/69639056828',
  feed: 'customers/3827277046/feeds/43009393',
  matching_function: {
    function_string: 'IN(FEED_ITEM_ID,{48200575108,48199744867,48200356726,48199839565,48200618792})',
    left_operands: [{ request_context_operand: { context_type: 2 } }],
    operator: 2,
    right_operands: [
      { constant_operand: { long_value: 48200575108 } },
      { constant_operand: { long_value: 48199744867 } },
      { constant_operand: { long_value: 48200356726 } },
      { constant_operand: { long_value: 48199839565 } },
      { constant_operand: { long_value: 48200618792 } },
    ],
  },
  placeholder_types: [],
  resource_name: 'customers/3827277046/adGroupFeeds/69639056828~43009393',
  status: 2,
})

List every instance of AdGroupFeed

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

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

Arguments

options optional

Object of the form { limit, order_by, constraints }:
- limit optional, number
  
  Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.
- order_by optional, string
  
  The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.
- constraints optional, array/object
  
  A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupFeeds.list({
  constraints: [
    {
      key: 'ad_group_feed.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_feed.some_field.sub_field',
})

// Example result
;[
  {
    ad_group_feed: {
      ad_group: 'customers/3827277046/adGroups/69639056828',
      feed: 'customers/3827277046/feeds/43009393',
      matching_function: {
        function_string: 'IN(FEED_ITEM_ID,{48200575108,48199744867,48200356726,48199839565,48200618792})',
        left_operands: [{ request_context_operand: { context_type: 2 } }],
        operator: 2,
        right_operands: [
          { constant_operand: { long_value: 48200575108 } },
          { constant_operand: { long_value: 48199744867 } },
          { constant_operand: { long_value: 48200356726 } },
          { constant_operand: { long_value: 48199839565 } },
          { constant_operand: { long_value: 48200618792 } },
        ],
      },
      placeholder_types: [],
      resource_name: 'customers/3827277046/adGroupFeeds/69639056828~43009393',
      status: 2,
    },
    feed: {
      attributes: [
        { id: 1, name: 'SitelinkName', type: 4, is_part_of_key: false },
        { id: 2, name: 'SitelinkUrl', type: 6, is_part_of_key: false },
        { id: 3, name: 'SitelinkDescription1', type: 4, is_part_of_key: false },
        { id: 4, name: 'SitelinkDescription2', type: 4, is_part_of_key: false },
        { id: 5, name: 'SitelinkFinalUrls', type: 12, is_part_of_key: false },
        { id: 6, name: 'SitelinkFinalMobileUrls', type: 12, is_part_of_key: false },
        { id: 7, name: 'SitelinkTrackingUrl', type: 6, is_part_of_key: false },
        { id: 8, name: 'SitelinkFinalUrlSuffix', type: 4, is_part_of_key: false },
      ],
      id: 43009393,
      name: 'My feed',
      origin: 3,
      resource_name: 'customers/3827277046/feeds/43009393',
      status: 2,
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/69639056828',
      campaign: 'customers/3827277046/campaigns/954460701',
      cpc_bid_micros: 4500000,
      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: 69639056828,
      labels: ['customers/3827277046/labels/3345231412'],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/69639056828',
      status: 2,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { 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: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 5,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/954460701',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/3827277046/campaignBudgets/1234926420',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 7 },
      id: 954460701,
      labels: ['customers/3827277046/labels/3889728471'],
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: false,
      },
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/954460701',
      serving_status: 2,
      start_date: '2017-10-13',
      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 AdGroupFeed

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

Arguments

entity required

The AdGroupFeed object or array of objects.
options optional

Object of the form { validate_only, partial_failure }:
- validate_only optional, boolean
  
  When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.
- partial_failure optional, boolean
  
  Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

results

An array of the resource_names created.
partial_failure_error

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

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

// Creating the entity

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

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

// Passing in an array of entities to create, validating only
const result = await customer.adGroupFeeds.create([ad_group_feed, other_ad_group_feed], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/adGroupFeeds/69639056828~43009393'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupFeed

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

Arguments

entity required

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

Object of the form { validate_only, partial_failure }:
- validate_only optional, boolean
  
  When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.
- partial_failure optional, boolean
  
  Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

results

An array of the resource_names updated.
partial_failure_error

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

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

// Updating the entity

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

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

// Passing in an array of entities to update, validating only
const result = await customer.adGroupFeeds.update([ad_group_feed, other_ad_group_feed], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/adGroupFeeds/69639056828~43009393'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupFeed

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

Arguments

resource_name required

The resource_name of that AdGroupFeed

Returns

Nothing

// Deleting the entity

await customer.adGroupFeeds.delete('customers/3827277046/adGroupFeeds/69639056828~43009393')

AdGroupLabel

The AdGroupLabel object

Fields

ad_group string

Immutable. The ad group to which the label is attached.

label string

Immutable. The label assigned to the ad group.

resource_name string

Immutable. The resource name of the ad group label. Ad group label resource names have the form: customers/{customer_id}/adGroupLabels/{ad_group_id}~{label_id}

// Example AdGroupLabel
const ad_group_label = {
  ad_group: 'customers/3827277046/adGroups/69639056828',
  label: 'customers/3827277046/labels/3345231412',
  resource_name: 'customers/3827277046/adGroupLabels/69639056828~3345231412',
}

Get an AdGroupLabel

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

Arguments

resource_name required

The resource_name of that AdGroupLabel

Returns

Returns that AdGroupLabel as an object.

// Getting the entity
let result = await customer.adGroupLabels.get('customers/3827277046/adGroupLabels/69639056828~3345231412')

// Example result
;({
  ad_group: 'customers/3827277046/adGroups/69639056828',
  label: 'customers/3827277046/labels/3345231412',
  resource_name: 'customers/3827277046/adGroupLabels/69639056828~3345231412',
})

List every instance of AdGroupLabel

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

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

Arguments

options optional

Object of the form { limit, order_by, constraints }:
- limit optional, number
  
  Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.
- order_by optional, string
  
  The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.
- constraints optional, array/object
  
  A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupLabels.list({
  constraints: [
    {
      key: 'ad_group_label.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_label.some_field.sub_field',
})

// Example result
;[
  {
    ad_group_label: {
      ad_group: 'customers/3827277046/adGroups/69639056828',
      label: 'customers/3827277046/labels/3345231412',
      resource_name: 'customers/3827277046/adGroupLabels/69639056828~3345231412',
    },
    label: {
      id: 3345231412,
      name: 'My label',
      resource_name: 'customers/3827277046/labels/3345231412',
      status: 2,
      text_label: {
        background_color: '#e993eb',
        description: 'Adgroups where Chloe will write new ads that kick butt.',
      },
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/69639056828',
      campaign: 'customers/3827277046/campaigns/954460701',
      cpc_bid_micros: 4500000,
      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: 69639056828,
      labels: ['customers/3827277046/labels/3345231412'],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/69639056828',
      status: 2,
      target_cpa_micros: 0,
      targeting_setting: {
        target_restrictions: [
          { 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: 2,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 5,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/954460701',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/3827277046/campaignBudgets/1234926420',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 4, positive_geo_target_type: 7 },
      id: 954460701,
      labels: ['customers/3827277046/labels/3889728471'],
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: false,
      },
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/954460701',
      serving_status: 2,
      start_date: '2017-10-13',
      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 AdGroupLabel

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

Arguments

entity required

The AdGroupLabel object or array of objects.
options optional

Object of the form { validate_only, partial_failure }:
- validate_only optional, boolean
  
  When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.
- partial_failure optional, boolean
  
  Only useful when passing in an array of entities. When false, a single failure in the array of entities to create will cause the whole operation to be rolled back. When true, the system will still create the non-failed entities. Defaults to false.

Returns

results

An array of the resource_names created.
partial_failure_error

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

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

// Creating the entity

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

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

// Passing in an array of entities to create, validating only
const result = await customer.adGroupLabels.create([ad_group_label, other_ad_group_label], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/adGroupLabels/69639056828~3345231412'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an AdGroupLabel

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

Arguments

entity required

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

Object of the form { validate_only, partial_failure }:
- validate_only optional, boolean
  
  When true, only checks whether the operation is valid. Makes no changes to your google ads account. Defaults to false.
- partial_failure optional, boolean
  
  Only useful when passing in an array of entities. When false, a single failure in the array of entities to update will cause the whole operation to be rolled back. When true, the system will still update the non-failed entities. Defaults to false.

Returns

results

An array of the resource_names updated.
partial_failure_error

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

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

// Updating the entity

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

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

// Passing in an array of entities to update, validating only
const result = await customer.adGroupLabels.update([ad_group_label, other_ad_group_label], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/adGroupLabels/69639056828~3345231412'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an AdGroupLabel

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

Arguments

resource_name required

The resource_name of that AdGroupLabel

Returns

Nothing

// Deleting the entity

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

AdGroupSimulation

The AdGroupSimulation object

Fields

ONE of the following:

cpc_bid_point_list object
Output only. Simulation points if the simulation type is CPC_BID.
Child Fields
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.
cpv_bid_point_list object
Output only. Simulation points if the simulation type is CPV_BID.
Child Fields
points array of objects
Projected metrics for a series of CPV bid amounts.
cost_micros int64
Projected cost in micros.
cpv_bid_micros int64
The simulated CPV bid upon which projected metrics are based.
impressions int64
Projected number of impressions.
views int64
Projected number of views.
target_cpa_point_list object
Output only. Simulation points if the simulation type is TARGET_CPA.
Child Fields
points array of objects
Projected metrics for a series of target CPA 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.
impressions int64
Projected number of impressions.
target_cpa_micros int64
The simulated target CPA upon which projected metrics are based.
top_slot_impressions int64
Projected number of top slot impressions. Only search advertising channel type supports this field.
target_roas_point_list object
Output only. Simulation points if the simulation type is TARGET_ROAS.
Child Fields
points array of objects
Projected metrics for a series of target ROAS 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.
impressions int64
Projected number of impressions.
target_roas double
The simulated target ROAS upon which projected metrics are based.
top_slot_impressions int64
Projected number of top slot impressions. Only Search advertising channel type supports this field.

ad_group_id int64

Output only. Ad group 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.

resource_name string

Output only. The resource name of the ad group simulation. Ad group simulation resource names have the form: customers/{customer_id}/adGroupSimulations/{ad_group_id}~{type}~{modification_method}~{start_date}~{end_date}

start_date string

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.

// Example AdGroupSimulation
const ad_group_simulation = {
  ad_group_id: 77057363752,
  cpc_bid_point_list: {
    points: [
      {
        cpc_bid_micros: 1820000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 7,
        cost_micros: 10540000,
        impressions: 151,
        top_slot_impressions: 103,
      },
      {
        cpc_bid_micros: 1910000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 9,
        cost_micros: 16740000,
        impressions: 187,
        top_slot_impressions: 138,
      },
      {
        cpc_bid_micros: 3830000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 13,
        cost_micros: 32520000,
        impressions: 218,
        top_slot_impressions: 170,
      },
      {
        cpc_bid_micros: 4610000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 16,
        cost_micros: 53450000,
        impressions: 250,
        top_slot_impressions: 200,
      },
      {
        cpc_bid_micros: 5500000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 17,
        cost_micros: 66370000,
        impressions: 280,
        top_slot_impressions: 233,
      },
      {
        cpc_bid_micros: 9600000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 19,
        cost_micros: 127600000,
        impressions: 299,
        top_slot_impressions: 276,
      },
      {
        cpc_bid_micros: 11750000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 20,
        cost_micros: 153720000,
        impressions: 304,
        top_slot_impressions: 281,
      },
    ],
  },
  end_date: '2020-07-17',
  modification_method: 2,
  resource_name: 'customers/3827277046/adGroupSimulations/77057363752~CPC_BID~UNIFORM~20200711~20200717',
  start_date: '2020-07-11',
  type: 2,
}

Get an AdGroupSimulation

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

Arguments

resource_name required

The resource_name of that AdGroupSimulation

Returns

Returns that AdGroupSimulation as an object.

// Getting the entity
let result = await customer.adGroupSimulations.get(
  'customers/3827277046/adGroupSimulations/77057363752~CPC_BID~UNIFORM~20200711~20200717'
)

// Example result
;({
  ad_group_id: 77057363752,
  cpc_bid_point_list: {
    points: [
      {
        cpc_bid_micros: 1820000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 7,
        cost_micros: 10540000,
        impressions: 151,
        top_slot_impressions: 103,
      },
      {
        cpc_bid_micros: 1910000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 9,
        cost_micros: 16740000,
        impressions: 187,
        top_slot_impressions: 138,
      },
      {
        cpc_bid_micros: 3830000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 13,
        cost_micros: 32520000,
        impressions: 218,
        top_slot_impressions: 170,
      },
      {
        cpc_bid_micros: 4610000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 16,
        cost_micros: 53450000,
        impressions: 250,
        top_slot_impressions: 200,
      },
      {
        cpc_bid_micros: 5500000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 17,
        cost_micros: 66370000,
        impressions: 280,
        top_slot_impressions: 233,
      },
      {
        cpc_bid_micros: 9600000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 19,
        cost_micros: 127600000,
        impressions: 299,
        top_slot_impressions: 276,
      },
      {
        cpc_bid_micros: 11750000,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 20,
        cost_micros: 153720000,
        impressions: 304,
        top_slot_impressions: 281,
      },
    ],
  },
  end_date: '2020-07-17',
  modification_method: 2,
  resource_name: 'customers/3827277046/adGroupSimulations/77057363752~CPC_BID~UNIFORM~20200711~20200717',
  start_date: '2020-07-11',
  type: 2,
})

List every instance of AdGroupSimulation

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

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

Arguments

options optional

Object of the form { limit, order_by, constraints }:
- limit optional, number
  
  Number of rows to return. Equivalent to the limit in customer.report(). Defaults to no limit.
- order_by optional, string
  
  The field to sort the returned rows by. Equivalent to the order_by in customer.report(). By default, no sorting is applied.
- constraints optional, array/object
  
  A constraints array or object. See the customer.report() documentation for details. By default, all entities are returned.

Returns

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.adGroupSimulations.list({
  constraints: [
    {
      key: 'ad_group_simulation.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'ad_group_simulation.some_field.sub_field',
})

// Example result
;[
  {
    ad_group_simulation: {
      ad_group_id: 77057363752,
      cpc_bid_point_list: {
        points: [
          {
            cpc_bid_micros: 1820000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 7,
            cost_micros: 10540000,
            impressions: 151,
            top_slot_impressions: 103,
          },
          {
            cpc_bid_micros: 1910000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 9,
            cost_micros: 16740000,
            impressions: 187,
            top_slot_impressions: 138,
          },
          {
            cpc_bid_micros: 3830000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 13,
            cost_micros: 32520000,
            impressions: 218,
            top_slot_impressions: 170,
          },
          {
            cpc_bid_micros: 4610000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 16,
            cost_micros: 53450000,
            impressions: 250,
            top_slot_impressions: 200,
          },
          {
            cpc_bid_micros: 5500000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 17,
            cost_micros: 66370000,
            impressions: 280,
            top_slot_impressions: 233,
          },
          {
            cpc_bid_micros: 9600000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 19,
            cost_micros: 127600000,
            impressions: 299,
            top_slot_impressions: 276,
          },
          {
            cpc_bid_micros: 11750000,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 20,
            cost_micros: 153720000,
            impressions: 304,
            top_slot_impressions: 281,
          },
        ],
      },
      end_date: '2020-07-17',
      modification_method: 2,
      resource_name: 'customers/3827277046/adGroupSimulations/77057363752~CPC_BID~UNIFORM~20200711~20200717',
      start_date: '2020-07-11',
      type: 2,
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/77057363752',
      campaign: 'customers/3827277046/campaigns/2081620948',
      cpc_bid_micros: 9600000,
      cpm_bid_micros: 10000000,
      cpv_bid_micros: 0,
      display_custom_bid_dimension: 0,
      effective_target_cpa_micros: 12000000,
      effective_target_cpa_source: 6,
      effective_target_roas_source: 0,
      explorer_auto_optimizer_setting: { opt_in: false },
      id: 77057363752,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/77057363752',
      status: 2,
      target_cpa_micros: 12000000,
      target_cpm_micros: 10000000,
      targeting_setting: {
        target_restrictions: [
          { targeting_dimension: 3, bid_only: true },
          { 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: 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/3827277046/campaigns/2081620948',
      bidding_strategy_type: 3,
      campaign_budget: 'customers/3827277046/campaignBudgets/6449346162',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 5, positive_geo_target_type: 7 },
      id: 2081620948,
      labels: [
        'customers/3827277046/labels/3889728216',
        'customers/3827277046/labels/3889728468',
        'customers/3827277046/labels/3889728480',
      ],
      manual_cpc: { enhanced_cpc_enabled: true },
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: false,
      },
      optimization_score: 0.8309262174345264,
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/2081620948',
      serving_status: 2,
      start_date: '2019-07-30',
      status: 2,
      targeting_setting: { target_restrictions: [{ targeting_dimension: 3, bid_only: true }] },
      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}',
    },
  },
]

Asset

The Asset object

Fields

ONE of the following:

book_on_google_asset object
A book on google asset.
Child Fields
image_asset object
Output only. An image asset.
Child Fields
data byte
The raw bytes data of an image. This field is mutate only.
file_size int64
File size of the image asset in bytes.
full_size object
Metadata for this image at its original size.
height_pixels int64
Height of the image.
url string
A URL that returns the image with this height and width.
width_pixels int64
Width of the image.
mime_type enum
MIME type of the image asset.
UNSPECIFIED (0)
The mime type has not been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
IMAGE_JPEG (2)
MIME type of image/jpeg.
IMAGE_GIF (3)
MIME type of image/gif.
IMAGE_PNG (4)
MIME type of image/png.
FLASH (5)
MIME type of application/x-shockwave-flash.
TEXT_HTML (6)
MIME type of text/html.
PDF (7)
MIME type of application/pdf.
MSWORD (8)
MIME type of application/msword.
MSEXCEL (9)
MIME type of application/vnd.ms-excel.
RTF (10)
MIME type of application/rtf.
AUDIO_WAV (11)
MIME type of audio/wav.
AUDIO_MP3 (12)
MIME type of audio/mp3.
HTML5_AD_ZIP (13)
MIME type of application/x-html5-ad-zip.
media_bundle_asset object
Immutable. A media bundle asset.
Child Fields
data byte
Media bundle (ZIP file) asset data. The format of the uploaded ZIP file depends on the ad field where it will be used. For more information on the format, see the documentation of the ad field where you plan on using the MediaBundleAsset. This field is mutate only.
text_asset object
Output only. A text asset.
Child Fields
text string
Text content of the text asset.
youtube_video_asset object
Immutable. A YouTube video asset.
Child Fields
youtube_video_id string
YouTube video id. This is the 11 character string value used in the YouTube video URL.

id int64

Output only. The ID of the asset.

name string

Optional name of the asset.

resource_name string

Immutable. The resource name of the asset. Asset resource names have the form: customers/{customer_id}/assets/{asset_id}

type enum

Output only. Type of the asset.

// Example Asset
const asset = {
  id: 225386305,
  image_asset: {
    file_size: 472254,
    full_size: {
      height_pixels: 628,
      url: 'https://tpc.googlesyndication.com/simgad/11290736009894828590',
      width_pixels: 1200,
    },
    mime_type: 4,
  },
  name: '',
  resource_name: 'customers/3827277046/assets/225386305',
  type: 4,
}

Get an Asset

The customer.assets.get(resource_name) method returns the Asset identified by a resource_name.

Arguments

resource_name required

The resource_name of that Asset

Returns

Returns that Asset as an object.

// Getting the entity
let result = await customer.assets.get('customers/3827277046/assets/225386305')

// Example result
;({
  id: 225386305,
  image_asset: {
    file_size: 472254,
    full_size: {
      height_pixels: 628,
      url: 'https://tpc.googlesyndication.com/simgad/11290736009894828590',
      width_pixels: 1200,
    },
    mime_type: 4,
  },
  name: '',
  resource_name: 'customers/3827277046/assets/225386305',
  type: 4,
})

List every instance of Asset

The customer.assets.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 Asset.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.assets.list({
  constraints: [
    {
      key: 'asset.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'asset.some_field.sub_field',
})

// Example result
;[
  {
    asset: {
      id: 225386305,
      image_asset: {
        file_size: 472254,
        full_size: {
          height_pixels: 628,
          url: 'https://tpc.googlesyndication.com/simgad/11290736009894828590',
          width_pixels: 1200,
        },
        mime_type: 4,
      },
      name: '',
      resource_name: 'customers/3827277046/assets/225386305',
      type: 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 Asset

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.assets.create([asset, other_asset], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/assets/225386305'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update an Asset

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

Arguments

entity required

The Asset 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 asset = {
  resource_name: 'customers/3827277046/assets/225386305', // 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.assets.update(asset)

// Passing in an array of entities to update, validating only
const result = await customer.assets.update([asset, other_asset], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/assets/225386305'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete an Asset

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

Returns

Nothing

// Deleting the entity

await customer.assets.delete('customers/3827277046/assets/225386305')

BiddingStrategy

The BiddingStrategy object

Fields

ONE of the following:

enhanced_cpc object
A bidding strategy that raises bids for clicks that seem more likely to lead to a conversion and lowers them for clicks where they seem less likely.
Child Fields
target_cpa object
A bidding strategy that sets bids to help get as many conversions as possible at the target cost-per-acquisition (CPA) you set.
Child Fields
cpc_bid_ceiling_micros int64
Maximum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.
cpc_bid_floor_micros int64
Minimum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.
target_cpa_micros int64
Average CPA target. This target should be greater than or equal to minimum billable unit based on the currency for the account.
target_impression_share object
A bidding strategy that automatically optimizes towards a desired percentage of impressions.
Child Fields
cpc_bid_ceiling_micros int64
The highest CPC bid the automated bidding system is permitted to specify. This is a required field entered by the advertiser that sets the ceiling and specified in local micros.
location enum
The targeted location on the search results page.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
ANYWHERE_ON_PAGE (2)
Any location on the web page.
TOP_OF_PAGE (3)
Top box of ads.
ABSOLUTE_TOP_OF_PAGE (4)
Top slot in the top box of ads.
location_fraction_micros int64
The desired fraction of ads to be shown in the targeted location in micros. E.g. 1% equals 10,000.
target_roas object
A bidding strategy that helps you maximize revenue while averaging a specific target Return On Ad Spend (ROAS).
Child Fields
cpc_bid_ceiling_micros int64
Maximum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.
cpc_bid_floor_micros int64
Minimum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.
target_roas double
Required. The desired revenue (based on conversion data) per unit of spend. Value must be between 0.01 and 1000.0, inclusive.
target_spend object
A bid strategy that sets your bids to help get as many clicks as possible within your budget.
Child Fields
cpc_bid_ceiling_micros int64
Maximum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.
target_spend_micros int64
The spend target under which to maximize clicks. A TargetSpend bidder will attempt to spend the smaller of this value or the natural throttling spend amount. If not specified, the budget is used as the spend target.

campaign_count int64

Output only. The number of campaigns attached to this bidding strategy. This field is read-only.

id int64

Output only. The ID of the bidding strategy.

name string

The name of the bidding strategy. All bidding strategies within an account must be named distinctly. The length of this string should be between 1 and 255, inclusive, in UTF-8 bytes, (trimmed).

non_removed_campaign_count int64

Output only. The number of non-removed campaigns attached to this bidding strategy. This field is read-only.

resource_name string

Immutable. The resource name of the bidding strategy. Bidding strategy resource names have the form: customers/{customer_id}/biddingStrategies/{bidding_strategy_id}

status enum

Output only. The status of the bidding strategy. This field is read-only.

type enum

Output only. The type of the bidding strategy. Create a bidding strategy by setting the bidding scheme. This field is read-only.

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
COMMISSION (16)
Commission is an automatic bidding strategy in which the advertiser pays a certain portion of the conversion value.
ENHANCED_CPC (2)
Enhanced CPC is a bidding strategy that raises bids for clicks that seem more likely to lead to a conversion and lowers them for clicks where they seem less likely.
MANUAL_CPC (3)
Manual click based bidding where user pays per click.
MANUAL_CPM (4)
Manual impression based bidding where user pays per thousand impressions.
MANUAL_CPV (13)
A bidding strategy that pays a configurable amount per video view.
MAXIMIZE_CONVERSIONS (10)
A bidding strategy that automatically maximizes number of conversions given a daily budget.
MAXIMIZE_CONVERSION_VALUE (11)
An automated bidding strategy that automatically sets bids to maximize revenue while spending your budget.
PAGE_ONE_PROMOTED (5)
Page-One Promoted bidding scheme, which sets max cpc bids to target impressions on page one or page one promoted slots on google.com. This enum value is deprecated.
PERCENT_CPC (12)
Percent Cpc is bidding strategy where bids are a fraction of the advertised price for some good or service.
TARGET_CPA (6)
Target CPA is an automated bid strategy that sets bids to help get as many conversions as possible at the target cost-per-acquisition (CPA) you set.
TARGET_CPM (14)
Target CPM is an automated bid strategy that sets bids to help get as many impressions as possible at the target cost per one thousand impressions (CPM) you set.
TARGET_IMPRESSION_SHARE (15)
An automated bidding strategy that sets bids so that a certain percentage of search ads are shown at the top of the first page (or other targeted location).
TARGET_OUTRANK_SHARE (7)
Target Outrank Share is an automated bidding strategy that sets bids based on the target fraction of auctions where the advertiser should outrank a specific competitor. This enum value is deprecated.
TARGET_ROAS (8)
Target ROAS is an automated bidding strategy that helps you maximize revenue while averaging a specific target Return On Average Spend (ROAS).
TARGET_SPEND (9)
Target Spend is an automated bid strategy that sets your bids to help get as many clicks as possible within your budget.

// Example BiddingStrategy
const bidding_strategy = {
  campaign_count: 7,
  id: 2039955526,
  name: 'My bidding strategy',
  non_removed_campaign_count: 7,
  resource_name: 'customers/3827277046/biddingStrategies/2039955526',
  status: 2,
  target_impression_share: { cpc_bid_ceiling_micros: 10000000, location: 4, location_fraction_micros: 900000 },
  type: 15,
}

Get a BiddingStrategy

The customer.biddingStrategies.get(resource_name) method returns the BiddingStrategy identified by a resource_name.

Arguments

resource_name required

The resource_name of that BiddingStrategy

Returns

Returns that BiddingStrategy as an object.

// Getting the entity
let result = await customer.biddingStrategies.get('customers/3827277046/biddingStrategies/2039955526')

// Example result
;({
  campaign_count: 7,
  id: 2039955526,
  name: 'My bidding strategy',
  non_removed_campaign_count: 7,
  resource_name: 'customers/3827277046/biddingStrategies/2039955526',
  status: 2,
  target_impression_share: { cpc_bid_ceiling_micros: 10000000, location: 4, location_fraction_micros: 900000 },
  type: 15,
})

List every instance of BiddingStrategy

The customer.biddingStrategies.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 BiddingStrategy.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.biddingStrategies.list({
  constraints: [
    {
      key: 'bidding_strategy.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'bidding_strategy.some_field.sub_field',
})

// Example result
;[
  {
    bidding_strategy: {
      campaign_count: 7,
      id: 2039955526,
      name: 'My bidding strategy',
      non_removed_campaign_count: 7,
      resource_name: 'customers/3827277046/biddingStrategies/2039955526',
      status: 2,
      target_impression_share: { cpc_bid_ceiling_micros: 10000000, location: 4, location_fraction_micros: 900000 },
      type: 15,
    },
    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 a BiddingStrategy

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.biddingStrategies.create([bidding_strategy, other_bidding_strategy], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/biddingStrategies/2039955526'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a BiddingStrategy

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

Arguments

entity required

The BiddingStrategy 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 bidding_strategy = {
  resource_name: 'customers/3827277046/biddingStrategies/2039955526', // 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.biddingStrategies.update(bidding_strategy)

// Passing in an array of entities to update, validating only
const result = await customer.biddingStrategies.update([bidding_strategy, other_bidding_strategy], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/biddingStrategies/2039955526'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a BiddingStrategy

The customer.biddingStrategies.delete(resource_name) sets the status field of a BiddingStrategy 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 BiddingStrategy

Returns

Nothing

// Deleting the entity

await customer.biddingStrategies.delete('customers/3827277046/biddingStrategies/2039955526')

BillingSetup

The BillingSetup object

Fields

ONE of the following:

end_date_time string
Output only. The end date time in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss format.
end_time_type enum
Output only. The end time as a type. The only possible value is 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.

ONE of the following:

start_date_time string
Immutable. The start date time in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss format. Only a future time is allowed.
start_time_type enum
Immutable. The start time as a type. Only NOW is allowed.
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.

id int64

Output only. The ID of the billing setup.

payments_account string

Immutable. The resource name of the payments account associated with this billing setup. Payments resource names have the form: customers/{customer_id}/paymentsAccounts/{payments_account_id} When setting up billing, this is used to signup with an existing payments account (and then payments_account_info should not be set). When getting a billing setup, this and payments_account_info will be populated.

payments_account_info object

Immutable. The payments account information associated with this billing setup. When setting up billing, this is used to signup with a new payments account (and then payments_account should not be set). When getting a billing setup, this and payments_account will be populated.

resource_name string

Immutable. The resource name of the billing setup. BillingSetup resource names have the form: customers/{customer_id}/billingSetups/{billing_setup_id}

status enum

Output only. The status of the billing setup.

// Example BillingSetup
const billing_setup = {
  end_time_type: 3,
  id: 465508048,
  resource_name: 'customers/9262111890/billingSetups/465508048',
  start_date_time: '2018-07-23 15:51:33',
  status: 2,
}

Get a BillingSetup

The customer.billingSetups.get(resource_name) method returns the BillingSetup identified by a resource_name.

Arguments

resource_name required

The resource_name of that BillingSetup

Returns

Returns that BillingSetup as an object.

// Getting the entity
let result = await customer.billingSetups.get('customers/9262111890/billingSetups/465508048')

// Example result
;({
  end_time_type: 3,
  id: 465508048,
  resource_name: 'customers/9262111890/billingSetups/465508048',
  start_date_time: '2018-07-23 15:51:33',
  status: 2,
})

List every instance of BillingSetup

The customer.billingSetups.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 BillingSetup.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.billingSetups.list({
  constraints: [
    {
      key: 'billing_setup.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'billing_setup.some_field.sub_field',
})

// Example result
;[
  {
    billing_setup: {
      end_time_type: 3,
      id: 465508048,
      resource_name: 'customers/9262111890/billingSetups/465508048',
      start_date_time: '2018-07-23 15:51:33',
      status: 2,
    },
    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 a BillingSetup

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.billingSetups.create([billing_setup, other_billing_setup], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/billingSetups/465508048'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a BillingSetup

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

Arguments

entity required

The BillingSetup 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 billing_setup = {
  resource_name: 'customers/9262111890/billingSetups/465508048', // 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.billingSetups.update(billing_setup)

// Passing in an array of entities to update, validating only
const result = await customer.billingSetups.update([billing_setup, other_billing_setup], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/billingSetups/465508048'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a BillingSetup

The customer.billingSetups.delete(resource_name) sets the status field of a BillingSetup 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 BillingSetup

Returns

Nothing

// Deleting the entity

await customer.billingSetups.delete('customers/9262111890/billingSetups/465508048')

Campaign

The Campaign object

Fields

ONE of the following:

bidding_strategy string
Portfolio bidding strategy used by campaign.
commission object
Commission is an automatic bidding strategy in which the advertiser pays a certain portion of the conversion value.
Child Fields
commission_rate_micros int64
Commission rate defines the portion of the conversion value that the advertiser will be billed. A commission rate of x should be passed into this field as (x * 1,000,000). For example, 106,000 represents a commission rate of 0.106 (10.6%).
manual_cpc object
Standard Manual CPC bidding strategy. Manual click-based bidding where user pays per click.
Child Fields
enhanced_cpc_enabled boolean
Whether bids are to be enhanced based on conversion optimizer data.
manual_cpm object
Standard Manual CPM bidding strategy. Manual impression-based bidding where user pays per thousand impressions.
Child Fields
manual_cpv object
Output only. A bidding strategy that pays a configurable amount per video view.
Child Fields
maximize_conversion_value object
Standard Maximize Conversion Value bidding strategy that automatically sets bids to maximize revenue while spending your budget.
Child Fields
target_roas double
The target return on ad spend (ROAS) option. If set, the bid strategy will maximize revenue while averaging the target return on ad spend. If the target ROAS is high, the bid strategy may not be able to spend the full budget. If the target ROAS is not set, the bid strategy will aim to achieve the highest possible ROAS for the budget.
maximize_conversions object
Standard Maximize Conversions bidding strategy that automatically maximizes number of conversions given a daily budget.
Child Fields
percent_cpc object
Standard Percent Cpc bidding strategy where bids are a fraction of the advertised price for some good or service.
Child Fields
cpc_bid_ceiling_micros int64
Maximum bid limit that can be set by the bid strategy. This is an optional field entered by the advertiser and specified in local micros. Note: A zero value is interpreted in the same way as having bid_ceiling undefined.
enhanced_cpc_enabled boolean
Adjusts the bid for each auction upward or downward, depending on the likelihood of a conversion. Individual bids may exceed cpc_bid_ceiling_micros, but the average bid amount for a campaign should not.
target_cpa object
Standard Target CPA bidding strategy that automatically sets bids to help get as many conversions as possible at the target cost-per-acquisition (CPA) you set.
Child Fields
cpc_bid_ceiling_micros int64
Maximum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.
cpc_bid_floor_micros int64
Minimum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.
target_cpa_micros int64
Average CPA target. This target should be greater than or equal to minimum billable unit based on the currency for the account.
target_cpm object
A bidding strategy that automatically optimizes cost per thousand impressions.
Child Fields
target_impression_share object
Target Impression Share bidding strategy. An automated bidding strategy that sets bids to achieve a desired percentage of impressions.
Child Fields
cpc_bid_ceiling_micros int64
The highest CPC bid the automated bidding system is permitted to specify. This is a required field entered by the advertiser that sets the ceiling and specified in local micros.
location enum
The targeted location on the search results page.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
ANYWHERE_ON_PAGE (2)
Any location on the web page.
TOP_OF_PAGE (3)
Top box of ads.
ABSOLUTE_TOP_OF_PAGE (4)
Top slot in the top box of ads.
location_fraction_micros int64
The desired fraction of ads to be shown in the targeted location in micros. E.g. 1% equals 10,000.
target_roas object
Standard Target ROAS bidding strategy that automatically maximizes revenue while averaging a specific target return on ad spend (ROAS).
Child Fields
cpc_bid_ceiling_micros int64
Maximum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.
cpc_bid_floor_micros int64
Minimum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.
target_roas double
Required. The desired revenue (based on conversion data) per unit of spend. Value must be between 0.01 and 1000.0, inclusive.
target_spend object
Standard Target Spend bidding strategy that automatically sets your bids to help get as many clicks as possible within your budget.
Child Fields
cpc_bid_ceiling_micros int64
Maximum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.
target_spend_micros int64
The spend target under which to maximize clicks. A TargetSpend bidder will attempt to spend the smaller of this value or the natural throttling spend amount. If not specified, the budget is used as the spend target.

ad_serving_optimization_status enum

The ad serving optimization status of the campaign.

advertising_channel_sub_type enum

Immutable. Optional refinement to advertising_channel_type. Must be a valid sub-type of the parent channel type. Can be set only when creating campaigns. After campaign is created, the field can not be changed.

advertising_channel_type enum

Immutable. The primary serving target for ads within the campaign. The targeting options can be refined in network_settings. This field is required and should not be empty when creating new campaigns. Can be set only when creating campaigns. After the campaign is created, the field can not be changed.

app_campaign_setting object

The setting related to App Campaign.

base_campaign string

Output only. The resource name of the base campaign of a draft or experiment campaign. For base campaigns, this is equal to resource_name. This field is read-only.

bidding_strategy_type enum

Output only. The type of bidding strategy. A bidding strategy can be created by setting either the bidding scheme to create a standard bidding strategy or the bidding_strategy field to create a portfolio bidding strategy. This field is read-only.

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
COMMISSION (16)
Commission is an automatic bidding strategy in which the advertiser pays a certain portion of the conversion value.
ENHANCED_CPC (2)
Enhanced CPC is a bidding strategy that raises bids for clicks that seem more likely to lead to a conversion and lowers them for clicks where they seem less likely.
MANUAL_CPC (3)
Manual click based bidding where user pays per click.
MANUAL_CPM (4)
Manual impression based bidding where user pays per thousand impressions.
MANUAL_CPV (13)
A bidding strategy that pays a configurable amount per video view.
MAXIMIZE_CONVERSIONS (10)
A bidding strategy that automatically maximizes number of conversions given a daily budget.
MAXIMIZE_CONVERSION_VALUE (11)
An automated bidding strategy that automatically sets bids to maximize revenue while spending your budget.
PAGE_ONE_PROMOTED (5)
Page-One Promoted bidding scheme, which sets max cpc bids to target impressions on page one or page one promoted slots on google.com. This enum value is deprecated.
PERCENT_CPC (12)
Percent Cpc is bidding strategy where bids are a fraction of the advertised price for some good or service.
TARGET_CPA (6)
Target CPA is an automated bid strategy that sets bids to help get as many conversions as possible at the target cost-per-acquisition (CPA) you set.
TARGET_CPM (14)
Target CPM is an automated bid strategy that sets bids to help get as many impressions as possible at the target cost per one thousand impressions (CPM) you set.
TARGET_IMPRESSION_SHARE (15)
An automated bidding strategy that sets bids so that a certain percentage of search ads are shown at the top of the first page (or other targeted location).
TARGET_OUTRANK_SHARE (7)
Target Outrank Share is an automated bidding strategy that sets bids based on the target fraction of auctions where the advertiser should outrank a specific competitor. This enum value is deprecated.
TARGET_ROAS (8)
Target ROAS is an automated bidding strategy that helps you maximize revenue while averaging a specific target Return On Average Spend (ROAS).
TARGET_SPEND (9)
Target Spend is an automated bid strategy that sets your bids to help get as many clicks as possible within your budget.

campaign_budget string

The budget of the campaign.

dynamic_search_ads_setting object

The setting for controlling Dynamic Search Ads (DSA).

end_date string

The date when campaign ended. This field must not be used in WHERE clauses.

experiment_type enum

Output only. The type of campaign: normal, draft, or experiment.

final_url_suffix string

Suffix used to append query parameters to landing pages that are served with parallel tracking.

frequency_caps array of objects

A list that limits how often each user will see this campaign's ads.

geo_target_type_setting object

The setting for ads geotargeting.

hotel_setting object

Immutable. The hotel setting for the campaign.

id int64

Output only. The ID of the campaign.

labels array of strings

Output only. The resource names of labels attached to this campaign.

local_campaign_setting object

The setting for local campaign.

name string

The name of the campaign. This field is required and should not be empty when creating new campaigns. It must not contain any null (code point 0x0), NL line feed (code point 0xA) or carriage return (code point 0xD) characters.

network_settings object

The network settings for the campaign.

optimization_goal_setting object

Optimization goal setting for this campaign, which includes a set of optimization goal types.

optimization_score double

Output only. Optimization score of the campaign. Optimization score is an estimate of how well a campaign is set to perform. It ranges from 0% (0.0) to 100% (1.0), with 100% indicating that the campaign is performing at full potential. See "About optimization score" at https://support.google.com/google-ads/answer/9061546. This field is read-only.

payment_mode enum

Payment mode for the campaign.

real_time_bidding_setting object

Settings for Real-Time Bidding, a feature only available for campaigns targeting the Ad Exchange network.

resource_name string

Immutable. The resource name of the campaign. Campaign resource names have the form: customers/{customer_id}/campaigns/{campaign_id}

selective_optimization object

Selective optimization setting for this campaign, which includes a set of conversion actions to optimize this campaign towards.

serving_status enum

Output only. The ad serving status of the campaign.

shopping_setting object

The setting for controlling Shopping campaigns.

start_date string

The date when campaign started. This field must not be used in WHERE clauses.

status enum

The status of the campaign. When a new campaign is added, the status defaults to ENABLED.

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.

target_restrictions array of objects

The per-targeting-dimension setting to restrict the reach of your campaign or ad group.

tracking_setting object

Output only. Campaign-level settings for tracking information.

tracking_url_template string

The URL template for constructing a tracking URL.

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.

vanity_pharma object

Describes how unbranded pharma ads will be displayed.

vanity_pharma_display_url_mode enum

The display mode for vanity pharma URLs.

vanity_pharma_text enum

The text that will be displayed in display URL of the text ad when website description is the selected display mode for vanity pharma URLs.

video_brand_safety_suitability enum

Output only. 3-Tier Brand Safety setting for the campaign.

// Example Campaign
const campaign = {
  ad_serving_optimization_status: 2,
  advertising_channel_sub_type: 0,
  advertising_channel_type: 3,
  base_campaign: 'customers/9262111890/campaigns/1568629385',
  bidding_strategy_type: 9,
  campaign_budget: 'customers/9262111890/campaignBudgets/1624493702',
  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: 1568629385,
  labels: [],
  name: 'My campaign',
  network_settings: {
    target_content_network: true,
    target_google_search: false,
    target_partner_search_network: false,
    target_search_network: false,
  },
  payment_mode: 4,
  resource_name: 'customers/9262111890/campaigns/1568629385',
  serving_status: 2,
  start_date: '2018-09-19',
  status: 4,
  target_spend: { cpc_bid_ceiling_micros: 1000000 },
  url_custom_parameters: [],
  video_brand_safety_suitability: 0,
}

Get a Campaign

The customer.campaigns.get(resource_name) method returns the Campaign identified by a resource_name.

Arguments

resource_name required

The resource_name of that Campaign

Returns

Returns that Campaign as an object.

// Getting the entity
let result = await customer.campaigns.get('customers/9262111890/campaigns/1568629385')

// Example result
;({
  ad_serving_optimization_status: 2,
  advertising_channel_sub_type: 0,
  advertising_channel_type: 3,
  base_campaign: 'customers/9262111890/campaigns/1568629385',
  bidding_strategy_type: 9,
  campaign_budget: 'customers/9262111890/campaignBudgets/1624493702',
  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: 1568629385,
  labels: [],
  name: 'My campaign',
  network_settings: {
    target_content_network: true,
    target_google_search: false,
    target_partner_search_network: false,
    target_search_network: false,
  },
  payment_mode: 4,
  resource_name: 'customers/9262111890/campaigns/1568629385',
  serving_status: 2,
  start_date: '2018-09-19',
  status: 4,
  target_spend: { cpc_bid_ceiling_micros: 1000000 },
  url_custom_parameters: [],
  video_brand_safety_suitability: 0,
})

List every instance of Campaign

The customer.campaigns.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 Campaign.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.campaigns.list({
  constraints: [
    {
      key: 'campaign.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'campaign.some_field.sub_field',
})

// Example result
;[
  {
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 3,
      base_campaign: 'customers/9262111890/campaigns/1568629385',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/9262111890/campaignBudgets/1624493702',
      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: 1568629385,
      labels: [],
      name: 'My campaign',
      network_settings: {
        target_content_network: true,
        target_google_search: false,
        target_partner_search_network: false,
        target_search_network: false,
      },
      payment_mode: 4,
      resource_name: 'customers/9262111890/campaigns/1568629385',
      serving_status: 2,
      start_date: '2018-09-19',
      status: 4,
      target_spend: { cpc_bid_ceiling_micros: 1000000 },
      url_custom_parameters: [],
      video_brand_safety_suitability: 0,
    },
    campaign_budget: {
      amount_micros: 12000000,
      delivery_method: 2,
      explicitly_shared: false,
      has_recommended_budget: false,
      id: 1624493702,
      name: 'My campaign budget',
      period: 2,
      reference_count: 0,
      resource_name: 'customers/9262111890/campaignBudgets/1624493702',
      status: 3,
      type: 2,
    },
    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 a Campaign

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.campaigns.create([campaign, other_campaign], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/campaigns/1568629385'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a Campaign

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

Arguments

entity required

The Campaign 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 campaign = {
  resource_name: 'customers/9262111890/campaigns/1568629385', // 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.campaigns.update(campaign)

// Passing in an array of entities to update, validating only
const result = await customer.campaigns.update([campaign, other_campaign], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/campaigns/1568629385'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a Campaign

The customer.campaigns.delete(resource_name) sets the status field of a Campaign 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 Campaign

Returns

Nothing

// Deleting the entity

await customer.campaigns.delete('customers/9262111890/campaigns/1568629385')

CampaignBidModifier

The CampaignBidModifier object

Fields

bid_modifier double

The modifier for the bid when the criterion matches.

campaign string

Output only. The campaign to which this criterion belongs.

criterion_id int64

Output only. The ID of the criterion to bid modify. This field is ignored for mutates.

interaction_type object

Immutable. Criterion for interaction type. Only supported for search campaigns.

resource_name string

Immutable. The resource name of the campaign bid modifier. Campaign bid modifier resource names have the form: customers/{customer_id}/campaignBidModifiers/{campaign_id}~{criterion_id}

// Example CampaignBidModifier
const campaign_bid_modifier = {
  campaign: 'customers/3827277046/campaigns/881817006',
  criterion_id: 8000,
  resource_name: 'customers/3827277046/campaignBidModifiers/881817006~8000',
}

Get a CampaignBidModifier

The customer.campaignBidModifiers.get(resource_name) method returns the CampaignBidModifier identified by a resource_name.

Arguments

resource_name required

The resource_name of that CampaignBidModifier

Returns

Returns that CampaignBidModifier as an object.

// Getting the entity
let result = await customer.campaignBidModifiers.get('customers/3827277046/campaignBidModifiers/881817006~8000')

// Example result
;({
  campaign: 'customers/3827277046/campaigns/881817006',
  criterion_id: 8000,
  resource_name: 'customers/3827277046/campaignBidModifiers/881817006~8000',
})

List every instance of CampaignBidModifier

The customer.campaignBidModifiers.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 CampaignBidModifier.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.campaignBidModifiers.list({
  constraints: [
    {
      key: 'campaign_bid_modifier.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'campaign_bid_modifier.some_field.sub_field',
})

// Example result
;[
  {
    campaign_bid_modifier: {
      campaign: 'customers/3827277046/campaigns/881817006',
      criterion_id: 8000,
      resource_name: 'customers/3827277046/campaignBidModifiers/881817006~8000',
    },
    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 a CampaignBidModifier

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.campaignBidModifiers.create([campaign_bid_modifier, other_campaign_bid_modifier], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/campaignBidModifiers/881817006~8000'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CampaignBidModifier

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

Arguments

entity required

The CampaignBidModifier 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 campaign_bid_modifier = {
  resource_name: 'customers/3827277046/campaignBidModifiers/881817006~8000', // 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.campaignBidModifiers.update(campaign_bid_modifier)

// Passing in an array of entities to update, validating only
const result = await customer.campaignBidModifiers.update([campaign_bid_modifier, other_campaign_bid_modifier], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/campaignBidModifiers/881817006~8000'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CampaignBidModifier

The customer.campaignBidModifiers.delete(resource_name) sets the status field of a CampaignBidModifier 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 CampaignBidModifier

Returns

Nothing

// Deleting the entity

await customer.campaignBidModifiers.delete('customers/3827277046/campaignBidModifiers/881817006~8000')

CampaignBudget

The CampaignBudget object

Fields

amount_micros int64

The amount of the budget, in the local currency for the account. Amount is specified in micros, where one million is equivalent to one currency unit. Monthly spend is capped at 30.4 times this amount.

delivery_method enum

The delivery method that determines the rate at which the campaign budget is spent. Defaults to STANDARD if unspecified in a create operation.

explicitly_shared boolean

Specifies whether the budget is explicitly shared. Defaults to true if unspecified in a create operation. If true, the budget was created with the purpose of sharing across one or more campaigns. If false, the budget was created with the intention of only being used with a single campaign. The budget's name and status will stay in sync with the campaign's name and status. Attempting to share the budget with a second campaign will result in an error. A non-shared budget can become an explicitly shared. The same operation must also assign the budget a name. A shared campaign budget can never become non-shared.

has_recommended_budget boolean

Output only. Indicates whether there is a recommended budget for this campaign budget. This field is read-only.

id int64

Output only. The ID of the campaign budget. A campaign budget is created using the CampaignBudgetService create operation and is assigned a budget ID. A budget ID can be shared across different campaigns; the system will then allocate the campaign budget among different campaigns to get optimum results.

name string

The name of the campaign budget. When creating a campaign budget through CampaignBudgetService, every explicitly shared campaign budget must have a non-null, non-empty name. Campaign budgets that are not explicitly shared derive their name from the attached campaign's name. The length of this string must be between 1 and 255, inclusive, in UTF-8 bytes, (trimmed).

period enum

Immutable. Period over which to spend the budget. Defaults to DAILY if not specified.

recommended_budget_amount_micros int64

Output only. The recommended budget amount. If no recommendation is available, this will be set to the budget amount. Amount is specified in micros, where one million is equivalent to one currency unit. This field is read-only.

recommended_budget_estimated_change_weekly_clicks int64

Output only. The estimated change in weekly clicks if the recommended budget is applied. This field is read-only.

recommended_budget_estimated_change_weekly_cost_micros int64

Output only. The estimated change in weekly cost in micros if the recommended budget is applied. One million is equivalent to one currency unit. This field is read-only.

recommended_budget_estimated_change_weekly_interactions int64

Output only. The estimated change in weekly interactions if the recommended budget is applied. This field is read-only.

recommended_budget_estimated_change_weekly_views int64

Output only. The estimated change in weekly views if the recommended budget is applied. This field is read-only.

reference_count int64

Output only. The number of campaigns actively using the budget. This field is read-only.

resource_name string

Immutable. The resource name of the campaign budget. Campaign budget resource names have the form: customers/{customer_id}/campaignBudgets/{budget_id}

status enum

Output only. The status of this campaign budget. This field is read-only.

total_amount_micros int64

The lifetime amount of the budget, in the local currency for the account. Amount is specified in micros, where one million is equivalent to one currency unit.

type enum

Immutable. The type of the campaign budget.

// Example CampaignBudget
const campaign_budget = {
  amount_micros: 12000000,
  delivery_method: 2,
  explicitly_shared: false,
  has_recommended_budget: false,
  id: 1624493702,
  name: 'My campaign budget',
  period: 2,
  reference_count: 0,
  resource_name: 'customers/9262111890/campaignBudgets/1624493702',
  status: 3,
  type: 2,
}

Get a CampaignBudget

The customer.campaignBudgets.get(resource_name) method returns the CampaignBudget identified by a resource_name.

Arguments

resource_name required

The resource_name of that CampaignBudget

Returns

Returns that CampaignBudget as an object.

// Getting the entity
let result = await customer.campaignBudgets.get('customers/9262111890/campaignBudgets/1624493702')

// Example result
;({
  amount_micros: 12000000,
  delivery_method: 2,
  explicitly_shared: false,
  has_recommended_budget: false,
  id: 1624493702,
  name: 'My campaign budget',
  period: 2,
  reference_count: 0,
  resource_name: 'customers/9262111890/campaignBudgets/1624493702',
  status: 3,
  type: 2,
})

List every instance of CampaignBudget

The customer.campaignBudgets.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 CampaignBudget.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.campaignBudgets.list({
  constraints: [
    {
      key: 'campaign_budget.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'campaign_budget.some_field.sub_field',
})

// Example result
;[
  {
    campaign_budget: {
      amount_micros: 12000000,
      delivery_method: 2,
      explicitly_shared: false,
      has_recommended_budget: false,
      id: 1624493702,
      name: 'My campaign budget',
      period: 2,
      reference_count: 0,
      resource_name: 'customers/9262111890/campaignBudgets/1624493702',
      status: 3,
      type: 2,
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 3,
      base_campaign: 'customers/9262111890/campaigns/1568629385',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/9262111890/campaignBudgets/1624493702',
      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: 1568629385,
      labels: [],
      name: 'My campaign',
      network_settings: {
        target_content_network: true,
        target_google_search: false,
        target_partner_search_network: false,
        target_search_network: false,
      },
      payment_mode: 4,
      resource_name: 'customers/9262111890/campaigns/1568629385',
      serving_status: 2,
      start_date: '2018-09-19',
      status: 4,
      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 a CampaignBudget

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.campaignBudgets.create([campaign_budget, other_campaign_budget], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/campaignBudgets/1624493702'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CampaignBudget

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

Arguments

entity required

The CampaignBudget 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 campaign_budget = {
  resource_name: 'customers/9262111890/campaignBudgets/1624493702', // 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.campaignBudgets.update(campaign_budget)

// Passing in an array of entities to update, validating only
const result = await customer.campaignBudgets.update([campaign_budget, other_campaign_budget], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/campaignBudgets/1624493702'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CampaignBudget

The customer.campaignBudgets.delete(resource_name) sets the status field of a CampaignBudget 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 CampaignBudget

Returns

Nothing

// Deleting the entity

await customer.campaignBudgets.delete('customers/9262111890/campaignBudgets/1624493702')

CampaignCriterion

The CampaignCriterion object

Fields

ONE of the following:

ad_schedule object
Immutable. Ad Schedule.
Child Fields
day_of_week enum
Day of the week the schedule applies to. This field is required for CREATE operations and is prohibited on UPDATE operations.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
MONDAY (2)
Monday.
TUESDAY (3)
Tuesday.
WEDNESDAY (4)
Wednesday.
THURSDAY (5)
Thursday.
FRIDAY (6)
Friday.
SATURDAY (7)
Saturday.
SUNDAY (8)
Sunday.
end_hour int32
Ending hour in 24 hour time; 24 signifies end of the day. This field must be between 0 and 24, inclusive. This field is required for CREATE operations and is prohibited on UPDATE operations.
end_minute enum
Minutes after the end hour at which this schedule ends. The schedule is exclusive of the end minute. This field is required for CREATE operations and is prohibited on UPDATE operations.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
ZERO (2)
Zero minutes past the hour.
FIFTEEN (3)
Fifteen minutes past the hour.
THIRTY (4)
Thirty minutes past the hour.
FORTY_FIVE (5)
Forty-five minutes past the hour.
start_hour int32
Starting hour in 24 hour time. This field must be between 0 and 23, inclusive. This field is required for CREATE operations and is prohibited on UPDATE operations.
start_minute enum
Minutes after the start hour at which this schedule starts. This field is required for CREATE operations and is prohibited on UPDATE operations.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
ZERO (2)
Zero minutes past the hour.
FIFTEEN (3)
Fifteen minutes past the hour.
THIRTY (4)
Thirty minutes past the hour.
FORTY_FIVE (5)
Forty-five minutes past the hour.
age_range object
Immutable. Age range.
Child Fields
type enum
Type of the age range.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
AGE_RANGE_18_24 (503001)
Between 18 and 24 years old.
AGE_RANGE_25_34 (503002)
Between 25 and 34 years old.
AGE_RANGE_35_44 (503003)
Between 35 and 44 years old.
AGE_RANGE_45_54 (503004)
Between 45 and 54 years old.
AGE_RANGE_55_64 (503005)
Between 55 and 64 years old.
AGE_RANGE_65_UP (503006)
65 years old and beyond.
AGE_RANGE_UNDETERMINED (503999)
Undetermined age range.
carrier object
Immutable. Carrier.
Child Fields
carrier_constant string
The Carrier constant resource name.
content_label object
Immutable. ContentLabel.
Child Fields
type enum
Content label type, required for CREATE operations.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
SEXUALLY_SUGGESTIVE (2)
Sexually suggestive content.
BELOW_THE_FOLD (3)
Below the fold placement.
PARKED_DOMAIN (4)
Parked domain.
JUVENILE (6)
Juvenile, gross & bizarre content.
PROFANITY (7)
Profanity & rough language.
TRAGEDY (8)
Death & tragedy.
VIDEO (9)
Video.
VIDEO_RATING_DV_G (10)
Content rating: G.
VIDEO_RATING_DV_PG (11)
Content rating: PG.
VIDEO_RATING_DV_T (12)
Content rating: T.
VIDEO_RATING_DV_MA (13)
Content rating: MA.
VIDEO_NOT_YET_RATED (14)
Content rating: not yet rated.
EMBEDDED_VIDEO (15)
Embedded video.
LIVE_STREAMING_VIDEO (16)
Live streaming video.
SOCIAL_ISSUES (17)
Sensitive social issues.
custom_affinity object
Immutable. Custom Affinity.
Child Fields
custom_affinity string
The CustomInterest resource name.
device object
Immutable. Device.
Child Fields
type enum
Type of the device.
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.
gender object
Immutable. Gender.
Child Fields
type enum
Type of the gender.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
MALE (10)
Male.
FEMALE (11)
Female.
UNDETERMINED (20)
Undetermined gender.
income_range object
Immutable. Income range.
Child Fields
type enum
Type of the income range.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
INCOME_RANGE_0_50 (510001)
0%-50%.
INCOME_RANGE_50_60 (510002)
50% to 60%.
INCOME_RANGE_60_70 (510003)
60% to 70%.
INCOME_RANGE_70_80 (510004)
70% to 80%.
INCOME_RANGE_80_90 (510005)
80% to 90%.
INCOME_RANGE_90_UP (510006)
Greater than 90%.
INCOME_RANGE_UNDETERMINED (510000)
Undetermined income range.
ip_block object
Immutable. IpBlock.
Child Fields
ip_address string
The IP address of this IP block.
keyword object
Immutable. Keyword.
Child Fields
match_type enum
The match type of the keyword.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EXACT (2)
Exact match.
PHRASE (3)
Phrase match.
BROAD (4)
Broad match.
text string
The text of the keyword (at most 80 characters and 10 words).
language object
Immutable. Language.
Child Fields
language_constant string
The language constant resource name.
listing_scope object
Immutable. Listing scope.
Child Fields
dimensions array of objects
Scope of the campaign criterion.
hotel_city object
City the hotel is located in.
city_criterion string
The Geo Target Constant resource name.
hotel_class object
Class of the hotel as a number of stars 1 to 5.
value int64
Long value of the hotel class.
hotel_country_region object
Country or Region the hotel is located in.
country_region_criterion string
The Geo Target Constant resource name.
hotel_id object
Advertiser-specific hotel ID.
value string
String value of the hotel ID.
hotel_state object
State the hotel is located in.
state_criterion string
The Geo Target Constant resource name.
product_bidding_category object
Bidding category of a product offer.
country_code string
Two-letter upper-case country code of the product bidding category. It must match the campaign.shopping_setting.sales_country field.
id int64
ID of the product bidding category. This ID is equivalent to the google_product_category ID as described in this article: https://support.google.com/merchants/answer/6324436
level enum
Level of the product bidding category.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
LEVEL1 (7)
Level 1.
LEVEL2 (8)
Level 2.
LEVEL3 (9)
Level 3.
LEVEL4 (10)
Level 4.
LEVEL5 (11)
Level 5.
product_brand object
Brand of a product offer.
value string
String value of the product brand.
product_channel object
Locality of a product offer.
channel enum
Value of the locality.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
ONLINE (2)
The item is sold online.
LOCAL (3)
The item is sold in local stores.
product_channel_exclusivity object
Availability of a product offer.
channel_exclusivity enum
Value of the availability.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
SINGLE_CHANNEL (2)
The item is sold through one channel only, either local stores or online as indicated by its ProductChannel.
MULTI_CHANNEL (3)
The item is matched to its online or local stores counterpart, indicating it is available for purchase in both ShoppingProductChannels.
product_condition object
Condition of a product offer.
condition enum
Value of the condition.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
NEW (3)
The product condition is new.
REFURBISHED (4)
The product condition is refurbished.
USED (5)
The product condition is used.
product_custom_attribute object
Custom attribute of a product offer.
index enum
Indicates the index of the custom attribute.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
INDEX0 (7)
First product custom attribute.
INDEX1 (8)
Second product custom attribute.
INDEX2 (9)
Third product custom attribute.
INDEX3 (10)
Fourth product custom attribute.
INDEX4 (11)
Fifth product custom attribute.
value string
String value of the product custom attribute.
product_item_id object
Item id of a product offer.
value string
Value of the id.
product_type object
Type of a product offer.
level enum
Level of the type.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
LEVEL1 (7)
Level 1.
LEVEL2 (8)
Level 2.
LEVEL3 (9)
Level 3.
LEVEL4 (10)
Level 4.
LEVEL5 (11)
Level 5.
value string
Value of the type.
unknown_listing_dimension object
Unknown dimension. Set when no other listing dimension is set.
location object
Immutable. Location.
Child Fields
geo_target_constant string
The geo target constant resource name.
location_group object
Immutable. Location Group
Child Fields
feed string
Feed specifying locations for targeting. This is required and must be set in CREATE operations.
geo_target_constants array of strings
Geo target constant(s) restricting the scope of the geographic area within the feed. Currently only one geo target constant is allowed.
radius int64
Distance in units specifying the radius around targeted locations. This is required and must be set in CREATE operations.
radius_units enum
Unit of the radius, miles and meters supported currently. This is required and must be set in CREATE operations.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
METERS (2)
Meters
MILES (3)
Miles
mobile_app_category object
Immutable. Mobile app category.
Child Fields
mobile_app_category_constant string
The mobile app category constant resource name.
mobile_application object
Immutable. Mobile application.
Child Fields
app_id string
A string that uniquely identifies a mobile application to Google Ads API. The format of this string is "{platform}-{platform_native_id}", where platform is "1" for iOS apps and "2" for Android apps, and where platform_native_id is the mobile application identifier native to the corresponding platform. For iOS, this native identifier is the 9 digit string that appears at the end of an App Store URL (e.g., "476943146" for "Flood-It! 2" whose App Store link is "http://itunes.apple.com/us/app/flood-it!-2/id476943146"). For Android, this native identifier is the application's package name (e.g., "com.labpixies.colordrips" for "Color Drips" given Google Play link "https://play.google.com/store/apps/details?id=com.labpixies.colordrips"). A well formed app id for Google Ads API would thus be "1-476943146" for iOS and "2-com.labpixies.colordrips" for Android. This field is required and must be set in CREATE operations.
name string
Name of this mobile application.
mobile_device object
Immutable. Mobile Device.
Child Fields
mobile_device_constant string
The mobile device constant resource name.
operating_system_version object
Immutable. Operating system version.
Child Fields
operating_system_version_constant string
The operating system version constant resource name.
parental_status object
Immutable. Parental status.
Child Fields
type enum
Type of the parental status.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
PARENT (300)
Parent.
NOT_A_PARENT (301)
Not a parent.
UNDETERMINED (302)
Undetermined parental status.
placement object
Immutable. Placement.
Child Fields
url string
URL of the placement. For example, "http://www.domain.com".
proximity object
Immutable. Proximity.
Child Fields
address object
Full address.
city_name string
Name of the city.
country_code string
Country code.
postal_code string
Postal code.
province_code string
Province or state code.
province_name string
Province or state name.
street_address string
Street address line 1.
street_address2 string
Street address line 2. This field is write-only. It is only used for calculating the longitude and latitude of an address when geo_point is empty.
geo_point object
Latitude and longitude.
latitude_in_micro_degrees int32
Micro degrees for the latitude.
longitude_in_micro_degrees int32
Micro degrees for the longitude.
radius double
The radius of the proximity.
radius_units enum
The unit of measurement of the radius. Default is KILOMETERS.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
MILES (2)
Miles
KILOMETERS (3)
Kilometers
topic object
Immutable. Topic.
Child Fields
path array of strings
The category to target or exclude. Each subsequent element in the array describes a more specific sub-category. For example, "Pets & Animals", "Pets", "Dogs" represents the "Pets & Animals/Pets/Dogs" category.
topic_constant string
The Topic Constant resource name.
user_interest object
Immutable. User Interest.
Child Fields
user_interest_category string
The UserInterest resource name.
user_list object
Immutable. User List.
Child Fields
user_list string
The User List resource name.
webpage object
Immutable. Webpage.
Child Fields
conditions array of objects
Conditions, or logical expressions, for webpage targeting. The list of webpage targeting conditions are and-ed together when evaluated for targeting. This field is required for CREATE operations and is prohibited on UPDATE operations.
argument string
Argument of webpage targeting condition.
operand enum
Operand of webpage targeting condition.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
URL (2)
Operand denoting a webpage URL targeting condition.
CATEGORY (3)
Operand denoting a webpage category targeting condition.
PAGE_TITLE (4)
Operand denoting a webpage title targeting condition.
PAGE_CONTENT (5)
Operand denoting a webpage content targeting condition.
CUSTOM_LABEL (6)
Operand denoting a webpage custom label targeting condition.
operator enum
Operator of webpage targeting condition.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EQUALS (2)
The argument web condition is equal to the compared web condition.
CONTAINS (3)
The argument web condition is part of the compared web condition.
criterion_name string
The name of the criterion that is defined by this parameter. The name value will be used for identifying, sorting and filtering criteria with this type of parameters. This field is required for CREATE operations and is prohibited on UPDATE operations.
youtube_channel object
Immutable. YouTube Channel.
Child Fields
channel_id string
The YouTube uploader channel id or the channel code of a YouTube channel.
youtube_video object
Immutable. YouTube Video.
Child Fields
video_id string
YouTube video id as it appears on the YouTube watch page.

bid_modifier float

The modifier for the bids when the criterion matches. The modifier must be in the range: 0.1 - 10.0. Most targetable criteria types support modifiers. Use 0 to opt out of a Device type.

campaign string

Immutable. The campaign to which the criterion belongs.

criterion_id int64

Output only. The ID of the criterion. This field is ignored during mutate.

negative boolean

Immutable. Whether to target (false) or exclude (true) the criterion.

resource_name string

Immutable. The resource name of the campaign criterion. Campaign criterion resource names have the form: customers/{customer_id}/campaignCriteria/{campaign_id}~{criterion_id}

status enum

The status of the criterion.

type enum

Output only. The type of the criterion.

// Example CampaignCriterion
const campaign_criterion = {
  campaign: 'customers/9262111890/campaigns/1483704368',
  criterion_id: 1000,
  language: { language_constant: 'languageConstants/1000' },
  negative: false,
  resource_name: 'customers/9262111890/campaignCriteria/1483704368~1000',
  status: 2,
  type: 20,
}

Get a CampaignCriterion

The customer.campaignCriteria.get(resource_name) method returns the CampaignCriterion identified by a resource_name.

Arguments

resource_name required

The resource_name of that CampaignCriterion

Returns

Returns that CampaignCriterion as an object.

// Getting the entity
let result = await customer.campaignCriteria.get('customers/9262111890/campaignCriteria/1483704368~1000')

// Example result
;({
  campaign: 'customers/9262111890/campaigns/1483704368',
  criterion_id: 1000,
  language: { language_constant: 'languageConstants/1000' },
  negative: false,
  resource_name: 'customers/9262111890/campaignCriteria/1483704368~1000',
  status: 2,
  type: 20,
})

List every instance of CampaignCriterion

The customer.campaignCriteria.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 CampaignCriterion.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.campaignCriteria.list({
  constraints: [
    {
      key: 'campaign_criterion.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'campaign_criterion.some_field.sub_field',
})

// Example result
;[
  {
    campaign_criterion: {
      campaign: 'customers/9262111890/campaigns/1483704368',
      criterion_id: 1000,
      language: { language_constant: 'languageConstants/1000' },
      negative: false,
      resource_name: 'customers/9262111890/campaignCriteria/1483704368~1000',
      status: 2,
      type: 20,
    },
    language_constant: {
      code: 'en',
      id: 1000,
      name: 'My language constant',
      resource_name: 'languageConstants/1000',
      targetable: true,
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 2,
      base_campaign: 'customers/9262111890/campaigns/1483704368',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/9262111890/campaignBudgets/1547508174',
      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: 1483704368,
      labels: [],
      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/9262111890/campaigns/1483704368',
      serving_status: 2,
      start_date: '2018-07-23',
      status: 2,
      target_spend: { cpc_bid_ceiling_micros: 12000000 },
      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 a CampaignCriterion

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.campaignCriteria.create([campaign_criterion, other_campaign_criterion], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/campaignCriteria/1483704368~1000'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CampaignCriterion

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

Arguments

entity required

The CampaignCriterion 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 campaign_criterion = {
  resource_name: 'customers/9262111890/campaignCriteria/1483704368~1000', // 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.campaignCriteria.update(campaign_criterion)

// Passing in an array of entities to update, validating only
const result = await customer.campaignCriteria.update([campaign_criterion, other_campaign_criterion], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/campaignCriteria/1483704368~1000'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CampaignCriterion

The customer.campaignCriteria.delete(resource_name) sets the status field of a CampaignCriterion 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 CampaignCriterion

Returns

Nothing

// Deleting the entity

await customer.campaignCriteria.delete('customers/9262111890/campaignCriteria/1483704368~1000')

CampaignCriterionSimulation

The CampaignCriterionSimulation object

Fields

bid_modifier_point_list object

Output only. Simulation points if the simulation type is BID_MODIFIER.

campaign_id int64

Output only. Campaign ID of the simulation.

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.

resource_name string

Output only. The resource name of the campaign criterion simulation. Campaign criterion simulation resource names have the form:

customers/{customer_id}/campaignCriterionSimulations/{campaign_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.

// Example CampaignCriterionSimulation
const campaign_criterion_simulation = {
  bid_modifier_point_list: {
    points: [
      {
        bid_modifier: 0.2,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 3,
        cost_micros: 3630000,
        impressions: 141,
        top_slot_impressions: 94,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 70,
        parent_cost_micros: 451520000,
        parent_impressions: 1605,
        parent_top_slot_impressions: 1349,
        parent_required_budget_micros: 88250000,
      },
      {
        bid_modifier: 0.34,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 3,
        cost_micros: 3630000,
        impressions: 157,
        top_slot_impressions: 114,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 70,
        parent_cost_micros: 451520000,
        parent_impressions: 1621,
        parent_top_slot_impressions: 1369,
        parent_required_budget_micros: 88250000,
      },
      {
        bid_modifier: 0.45,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 5,
        cost_micros: 13060000,
        impressions: 176,
        top_slot_impressions: 131,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 72,
        parent_cost_micros: 460950000,
        parent_impressions: 1640,
        parent_top_slot_impressions: 1386,
        parent_required_budget_micros: 88250000,
      },
      {
        bid_modifier: 0.48,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 6,
        cost_micros: 16090000,
        impressions: 190,
        top_slot_impressions: 149,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 73,
        parent_cost_micros: 463980000,
        parent_impressions: 1654,
        parent_top_slot_impressions: 1404,
        parent_required_budget_micros: 88250000,
      },
      {
        bid_modifier: 0.49,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 7,
        cost_micros: 19470000,
        impressions: 204,
        top_slot_impressions: 163,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 74,
        parent_cost_micros: 467360000,
        parent_impressions: 1668,
        parent_top_slot_impressions: 1418,
        parent_required_budget_micros: 88250000,
      },
      {
        bid_modifier: 0.59,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 8,
        cost_micros: 25000000,
        impressions: 220,
        top_slot_impressions: 181,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 75,
        parent_cost_micros: 472890000,
        parent_impressions: 1684,
        parent_top_slot_impressions: 1436,
        parent_required_budget_micros: 90410000,
      },
      {
        bid_modifier: 0.77,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 9,
        cost_micros: 37330000,
        impressions: 236,
        top_slot_impressions: 201,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 76,
        parent_cost_micros: 485220000,
        parent_impressions: 1700,
        parent_top_slot_impressions: 1456,
        parent_required_budget_micros: 91090000,
      },
      {
        bid_modifier: 1,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 9,
        cost_micros: 48160000,
        impressions: 252,
        top_slot_impressions: 220,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 76,
        parent_cost_micros: 496050000,
        parent_impressions: 1716,
        parent_top_slot_impressions: 1475,
        parent_required_budget_micros: 92690000,
      },
      {
        bid_modifier: 1.82,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 10,
        cost_micros: 84630000,
        impressions: 272,
        top_slot_impressions: 234,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 77,
        parent_cost_micros: 532520000,
        parent_impressions: 1736,
        parent_top_slot_impressions: 1489,
        parent_required_budget_micros: 94830000,
      },
      {
        bid_modifier: 4.51,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 10,
        cost_micros: 89710000,
        impressions: 296,
        top_slot_impressions: 244,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 77,
        parent_cost_micros: 537600000,
        parent_impressions: 1760,
        parent_top_slot_impressions: 1499,
        parent_required_budget_micros: 99910000,
      },
    ],
  },
  campaign_id: 2081620945,
  criterion_id: 30001,
  end_date: '2020-07-17',
  modification_method: 2,
  resource_name:
    'customers/3827277046/campaignCriterionSimulations/2081620945~30001~BID_MODIFIER~UNIFORM~20200711~20200717',
  start_date: '2020-07-11',
  type: 5,
}

Get a CampaignCriterionSimulation

The customer.campaignCriterionSimulations.get(resource_name) method returns the CampaignCriterionSimulation identified by a resource_name.

Arguments

resource_name required

The resource_name of that CampaignCriterionSimulation

Returns

Returns that CampaignCriterionSimulation as an object.

// Getting the entity
let result = await customer.campaignCriterionSimulations.get(
  'customers/3827277046/campaignCriterionSimulations/2081620945~30001~BID_MODIFIER~UNIFORM~20200711~20200717'
)

// Example result
;({
  bid_modifier_point_list: {
    points: [
      {
        bid_modifier: 0.2,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 3,
        cost_micros: 3630000,
        impressions: 141,
        top_slot_impressions: 94,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 70,
        parent_cost_micros: 451520000,
        parent_impressions: 1605,
        parent_top_slot_impressions: 1349,
        parent_required_budget_micros: 88250000,
      },
      {
        bid_modifier: 0.34,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 3,
        cost_micros: 3630000,
        impressions: 157,
        top_slot_impressions: 114,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 70,
        parent_cost_micros: 451520000,
        parent_impressions: 1621,
        parent_top_slot_impressions: 1369,
        parent_required_budget_micros: 88250000,
      },
      {
        bid_modifier: 0.45,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 5,
        cost_micros: 13060000,
        impressions: 176,
        top_slot_impressions: 131,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 72,
        parent_cost_micros: 460950000,
        parent_impressions: 1640,
        parent_top_slot_impressions: 1386,
        parent_required_budget_micros: 88250000,
      },
      {
        bid_modifier: 0.48,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 6,
        cost_micros: 16090000,
        impressions: 190,
        top_slot_impressions: 149,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 73,
        parent_cost_micros: 463980000,
        parent_impressions: 1654,
        parent_top_slot_impressions: 1404,
        parent_required_budget_micros: 88250000,
      },
      {
        bid_modifier: 0.49,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 7,
        cost_micros: 19470000,
        impressions: 204,
        top_slot_impressions: 163,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 74,
        parent_cost_micros: 467360000,
        parent_impressions: 1668,
        parent_top_slot_impressions: 1418,
        parent_required_budget_micros: 88250000,
      },
      {
        bid_modifier: 0.59,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 8,
        cost_micros: 25000000,
        impressions: 220,
        top_slot_impressions: 181,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 75,
        parent_cost_micros: 472890000,
        parent_impressions: 1684,
        parent_top_slot_impressions: 1436,
        parent_required_budget_micros: 90410000,
      },
      {
        bid_modifier: 0.77,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 9,
        cost_micros: 37330000,
        impressions: 236,
        top_slot_impressions: 201,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 76,
        parent_cost_micros: 485220000,
        parent_impressions: 1700,
        parent_top_slot_impressions: 1456,
        parent_required_budget_micros: 91090000,
      },
      {
        bid_modifier: 1,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 9,
        cost_micros: 48160000,
        impressions: 252,
        top_slot_impressions: 220,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 76,
        parent_cost_micros: 496050000,
        parent_impressions: 1716,
        parent_top_slot_impressions: 1475,
        parent_required_budget_micros: 92690000,
      },
      {
        bid_modifier: 1.82,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 10,
        cost_micros: 84630000,
        impressions: 272,
        top_slot_impressions: 234,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 77,
        parent_cost_micros: 532520000,
        parent_impressions: 1736,
        parent_top_slot_impressions: 1489,
        parent_required_budget_micros: 94830000,
      },
      {
        bid_modifier: 4.51,
        biddable_conversions: 0,
        biddable_conversions_value: 0,
        clicks: 10,
        cost_micros: 89710000,
        impressions: 296,
        top_slot_impressions: 244,
        parent_biddable_conversions: 0,
        parent_biddable_conversions_value: 0,
        parent_clicks: 77,
        parent_cost_micros: 537600000,
        parent_impressions: 1760,
        parent_top_slot_impressions: 1499,
        parent_required_budget_micros: 99910000,
      },
    ],
  },
  campaign_id: 2081620945,
  criterion_id: 30001,
  end_date: '2020-07-17',
  modification_method: 2,
  resource_name:
    'customers/3827277046/campaignCriterionSimulations/2081620945~30001~BID_MODIFIER~UNIFORM~20200711~20200717',
  start_date: '2020-07-11',
  type: 5,
})

List every instance of CampaignCriterionSimulation

The customer.campaignCriterionSimulations.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 CampaignCriterionSimulation.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.campaignCriterionSimulations.list({
  constraints: [
    {
      key: 'campaign_criterion_simulation.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'campaign_criterion_simulation.some_field.sub_field',
})

// Example result
;[
  {
    campaign_criterion_simulation: {
      bid_modifier_point_list: {
        points: [
          {
            bid_modifier: 0.2,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 3,
            cost_micros: 3630000,
            impressions: 141,
            top_slot_impressions: 94,
            parent_biddable_conversions: 0,
            parent_biddable_conversions_value: 0,
            parent_clicks: 70,
            parent_cost_micros: 451520000,
            parent_impressions: 1605,
            parent_top_slot_impressions: 1349,
            parent_required_budget_micros: 88250000,
          },
          {
            bid_modifier: 0.34,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 3,
            cost_micros: 3630000,
            impressions: 157,
            top_slot_impressions: 114,
            parent_biddable_conversions: 0,
            parent_biddable_conversions_value: 0,
            parent_clicks: 70,
            parent_cost_micros: 451520000,
            parent_impressions: 1621,
            parent_top_slot_impressions: 1369,
            parent_required_budget_micros: 88250000,
          },
          {
            bid_modifier: 0.45,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 5,
            cost_micros: 13060000,
            impressions: 176,
            top_slot_impressions: 131,
            parent_biddable_conversions: 0,
            parent_biddable_conversions_value: 0,
            parent_clicks: 72,
            parent_cost_micros: 460950000,
            parent_impressions: 1640,
            parent_top_slot_impressions: 1386,
            parent_required_budget_micros: 88250000,
          },
          {
            bid_modifier: 0.48,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 6,
            cost_micros: 16090000,
            impressions: 190,
            top_slot_impressions: 149,
            parent_biddable_conversions: 0,
            parent_biddable_conversions_value: 0,
            parent_clicks: 73,
            parent_cost_micros: 463980000,
            parent_impressions: 1654,
            parent_top_slot_impressions: 1404,
            parent_required_budget_micros: 88250000,
          },
          {
            bid_modifier: 0.49,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 7,
            cost_micros: 19470000,
            impressions: 204,
            top_slot_impressions: 163,
            parent_biddable_conversions: 0,
            parent_biddable_conversions_value: 0,
            parent_clicks: 74,
            parent_cost_micros: 467360000,
            parent_impressions: 1668,
            parent_top_slot_impressions: 1418,
            parent_required_budget_micros: 88250000,
          },
          {
            bid_modifier: 0.59,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 8,
            cost_micros: 25000000,
            impressions: 220,
            top_slot_impressions: 181,
            parent_biddable_conversions: 0,
            parent_biddable_conversions_value: 0,
            parent_clicks: 75,
            parent_cost_micros: 472890000,
            parent_impressions: 1684,
            parent_top_slot_impressions: 1436,
            parent_required_budget_micros: 90410000,
          },
          {
            bid_modifier: 0.77,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 9,
            cost_micros: 37330000,
            impressions: 236,
            top_slot_impressions: 201,
            parent_biddable_conversions: 0,
            parent_biddable_conversions_value: 0,
            parent_clicks: 76,
            parent_cost_micros: 485220000,
            parent_impressions: 1700,
            parent_top_slot_impressions: 1456,
            parent_required_budget_micros: 91090000,
          },
          {
            bid_modifier: 1,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 9,
            cost_micros: 48160000,
            impressions: 252,
            top_slot_impressions: 220,
            parent_biddable_conversions: 0,
            parent_biddable_conversions_value: 0,
            parent_clicks: 76,
            parent_cost_micros: 496050000,
            parent_impressions: 1716,
            parent_top_slot_impressions: 1475,
            parent_required_budget_micros: 92690000,
          },
          {
            bid_modifier: 1.82,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 10,
            cost_micros: 84630000,
            impressions: 272,
            top_slot_impressions: 234,
            parent_biddable_conversions: 0,
            parent_biddable_conversions_value: 0,
            parent_clicks: 77,
            parent_cost_micros: 532520000,
            parent_impressions: 1736,
            parent_top_slot_impressions: 1489,
            parent_required_budget_micros: 94830000,
          },
          {
            bid_modifier: 4.51,
            biddable_conversions: 0,
            biddable_conversions_value: 0,
            clicks: 10,
            cost_micros: 89710000,
            impressions: 296,
            top_slot_impressions: 244,
            parent_biddable_conversions: 0,
            parent_biddable_conversions_value: 0,
            parent_clicks: 77,
            parent_cost_micros: 537600000,
            parent_impressions: 1760,
            parent_top_slot_impressions: 1499,
            parent_required_budget_micros: 99910000,
          },
        ],
      },
      campaign_id: 2081620945,
      criterion_id: 30001,
      end_date: '2020-07-17',
      modification_method: 2,
      resource_name:
        'customers/3827277046/campaignCriterionSimulations/2081620945~30001~BID_MODIFIER~UNIFORM~20200711~20200717',
      start_date: '2020-07-11',
      type: 5,
    },
    campaign_criterion: {
      campaign: 'customers/3827277046/campaigns/2081620945',
      criterion_id: 30001,
      device: { type: 2 },
      negative: false,
      resource_name: 'customers/3827277046/campaignCriteria/2081620945~30001',
      status: 2,
      type: 6,
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 2,
      base_campaign: 'customers/3827277046/campaigns/2081620945',
      bidding_strategy_type: 3,
      campaign_budget: 'customers/3827277046/campaignBudgets/6449346159',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 5, positive_geo_target_type: 7 },
      id: 2081620945,
      labels: [
        'customers/3827277046/labels/3889728216',
        'customers/3827277046/labels/3889728468',
        'customers/3827277046/labels/3889728480',
      ],
      manual_cpc: { enhanced_cpc_enabled: true },
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: false,
      },
      optimization_score: 0.7376711477461586,
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/2081620945',
      serving_status: 2,
      start_date: '2019-07-30',
      status: 2,
      targeting_setting: { target_restrictions: [{ targeting_dimension: 3, bid_only: true }] },
      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}',
    },
  },
]

CampaignExtensionSetting

The CampaignExtensionSetting object

Fields

campaign string

Immutable. The resource name of the campaign. The linked extension feed items will serve under this campaign. Campaign resource names have the form: customers/{customer_id}/campaigns/{campaign_id}

device enum

The device for which the extensions will serve. Optional.

extension_feed_items array of strings

The resource names of the extension feed items to serve under the campaign. ExtensionFeedItem resource names have the form: customers/{customer_id}/extensionFeedItems/{feed_item_id}

extension_type enum

Immutable. The extension type of the customer extension setting.

resource_name string

Immutable. The resource name of the campaign extension setting. CampaignExtensionSetting resource names have the form: customers/{customer_id}/campaignExtensionSettings/{campaign_id}~{extension_type}

// Example CampaignExtensionSetting
const campaign_extension_setting = {
  campaign: 'customers/9262111890/campaigns/1483704368',
  device: 0,
  extension_feed_items: [
    'customers/9262111890/extensionFeedItems/51842193961',
    'customers/9262111890/extensionFeedItems/51842200495',
    'customers/9262111890/extensionFeedItems/51844020102',
    'customers/9262111890/extensionFeedItems/51844028388',
  ],
  extension_type: 10,
  resource_name: 'customers/9262111890/campaignExtensionSettings/1483704368~SITELINK',
}

Get a CampaignExtensionSetting

The customer.campaignExtensionSettings.get(resource_name) method returns the CampaignExtensionSetting identified by a resource_name.

Arguments

resource_name required

The resource_name of that CampaignExtensionSetting

Returns

Returns that CampaignExtensionSetting as an object.

// Getting the entity
let result = await customer.campaignExtensionSettings.get(
  'customers/9262111890/campaignExtensionSettings/1483704368~SITELINK'
)

// Example result
;({
  campaign: 'customers/9262111890/campaigns/1483704368',
  device: 0,
  extension_feed_items: [
    'customers/9262111890/extensionFeedItems/51842193961',
    'customers/9262111890/extensionFeedItems/51842200495',
    'customers/9262111890/extensionFeedItems/51844020102',
    'customers/9262111890/extensionFeedItems/51844028388',
  ],
  extension_type: 10,
  resource_name: 'customers/9262111890/campaignExtensionSettings/1483704368~SITELINK',
})

List every instance of CampaignExtensionSetting

The customer.campaignExtensionSettings.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 CampaignExtensionSetting.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.campaignExtensionSettings.list({
  constraints: [
    {
      key: 'campaign_extension_setting.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'campaign_extension_setting.some_field.sub_field',
})

// Example result
;[
  {
    campaign_extension_setting: {
      campaign: 'customers/9262111890/campaigns/1483704368',
      device: 0,
      extension_feed_items: [
        'customers/9262111890/extensionFeedItems/51842193961',
        'customers/9262111890/extensionFeedItems/51842200495',
        'customers/9262111890/extensionFeedItems/51844020102',
        'customers/9262111890/extensionFeedItems/51844028388',
      ],
      extension_type: 10,
      resource_name: 'customers/9262111890/campaignExtensionSettings/1483704368~SITELINK',
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 2,
      base_campaign: 'customers/9262111890/campaigns/1483704368',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/9262111890/campaignBudgets/1547508174',
      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: 1483704368,
      labels: [],
      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/9262111890/campaigns/1483704368',
      serving_status: 2,
      start_date: '2018-07-23',
      status: 2,
      target_spend: { cpc_bid_ceiling_micros: 12000000 },
      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 a CampaignExtensionSetting

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.campaignExtensionSettings.create(
  [campaign_extension_setting, other_campaign_extension_setting],
  {
    validate_only: true,
  }
)

// Example result
{
	results : ['customers/9262111890/campaignExtensionSettings/1483704368~SITELINK'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CampaignExtensionSetting

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

Arguments

entity required

The CampaignExtensionSetting 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 campaign_extension_setting = {
  resource_name: 'customers/9262111890/campaignExtensionSettings/1483704368~SITELINK', // The resource_name is required
  // ...any other fields that you would like to update
}

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

// Passing in an array of entities to update, validating only
const result = await customer.campaignExtensionSettings.update(
  [campaign_extension_setting, other_campaign_extension_setting],
  {
    validate_only: true,
  }
)

// Example result
{
	results : ['customers/9262111890/campaignExtensionSettings/1483704368~SITELINK'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CampaignExtensionSetting

The customer.campaignExtensionSettings.delete(resource_name) sets the status field of a CampaignExtensionSetting 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 CampaignExtensionSetting

Returns

Nothing

// Deleting the entity

await customer.campaignExtensionSettings.delete('customers/9262111890/campaignExtensionSettings/1483704368~SITELINK')

CampaignFeed

The CampaignFeed object

Fields

campaign string

Immutable. The campaign to which the CampaignFeed belongs.

feed string

Immutable. The feed to which the CampaignFeed belongs.

matching_function object

Matching function associated with the CampaignFeed. The matching function is used to filter the set of feed items selected. Required.

placeholder_types array of strings

Indicates which placeholder types the feed may populate under the connected campaign. Required.

resource_name string

Immutable. The resource name of the campaign feed. Campaign feed resource names have the form: `customers/{customer_id}/campaignFeeds/{campaign_id}~{feed_id}

status enum

Output only. Status of the campaign feed. This field is read-only.

// Example CampaignFeed
const campaign_feed = {
  campaign: 'customers/9262111890/campaigns/1483704368',
  feed: 'customers/9262111890/feeds/82896692',
  matching_function: {
    function_string: 'IN(FEED_ITEM_ID,{51842193961,51842200495,51844020102,51844028388})',
    left_operands: [{ request_context_operand: { context_type: 2 } }],
    operator: 2,
    right_operands: [
      { constant_operand: { long_value: 51842193961 } },
      { constant_operand: { long_value: 51842200495 } },
      { constant_operand: { long_value: 51844020102 } },
      { constant_operand: { long_value: 51844028388 } },
    ],
  },
  placeholder_types: [],
  resource_name: 'customers/9262111890/campaignFeeds/1483704368~82896692',
  status: 2,
}

Get a CampaignFeed

The customer.campaignFeeds.get(resource_name) method returns the CampaignFeed identified by a resource_name.

Arguments

resource_name required

The resource_name of that CampaignFeed

Returns

Returns that CampaignFeed as an object.

// Getting the entity
let result = await customer.campaignFeeds.get('customers/9262111890/campaignFeeds/1483704368~82896692')

// Example result
;({
  campaign: 'customers/9262111890/campaigns/1483704368',
  feed: 'customers/9262111890/feeds/82896692',
  matching_function: {
    function_string: 'IN(FEED_ITEM_ID,{51842193961,51842200495,51844020102,51844028388})',
    left_operands: [{ request_context_operand: { context_type: 2 } }],
    operator: 2,
    right_operands: [
      { constant_operand: { long_value: 51842193961 } },
      { constant_operand: { long_value: 51842200495 } },
      { constant_operand: { long_value: 51844020102 } },
      { constant_operand: { long_value: 51844028388 } },
    ],
  },
  placeholder_types: [],
  resource_name: 'customers/9262111890/campaignFeeds/1483704368~82896692',
  status: 2,
})

List every instance of CampaignFeed

The customer.campaignFeeds.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 CampaignFeed.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.campaignFeeds.list({
  constraints: [
    {
      key: 'campaign_feed.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'campaign_feed.some_field.sub_field',
})

// Example result
;[
  {
    campaign_feed: {
      campaign: 'customers/9262111890/campaigns/1483704368',
      feed: 'customers/9262111890/feeds/82896692',
      matching_function: {
        function_string: 'IN(FEED_ITEM_ID,{51842193961,51842200495,51844020102,51844028388})',
        left_operands: [{ request_context_operand: { context_type: 2 } }],
        operator: 2,
        right_operands: [
          { constant_operand: { long_value: 51842193961 } },
          { constant_operand: { long_value: 51842200495 } },
          { constant_operand: { long_value: 51844020102 } },
          { constant_operand: { long_value: 51844028388 } },
        ],
      },
      placeholder_types: [],
      resource_name: 'customers/9262111890/campaignFeeds/1483704368~82896692',
      status: 2,
    },
    feed: {
      attributes: [
        { id: 1, name: 'SitelinkName', type: 4, is_part_of_key: false },
        { id: 2, name: 'SitelinkUrl', type: 6, is_part_of_key: false },
        { id: 3, name: 'SitelinkDescription1', type: 4, is_part_of_key: false },
        { id: 4, name: 'SitelinkDescription2', type: 4, is_part_of_key: false },
        { id: 5, name: 'SitelinkFinalUrls', type: 12, is_part_of_key: false },
        { id: 6, name: 'SitelinkFinalMobileUrls', type: 12, is_part_of_key: false },
        { id: 7, name: 'SitelinkTrackingUrl', type: 6, is_part_of_key: false },
        { id: 8, name: 'SitelinkFinalUrlSuffix', type: 4, is_part_of_key: false },
      ],
      id: 82896692,
      name: 'My feed',
      origin: 3,
      resource_name: 'customers/9262111890/feeds/82896692',
      status: 2,
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 2,
      base_campaign: 'customers/9262111890/campaigns/1483704368',
      bidding_strategy_type: 9,
      campaign_budget: 'customers/9262111890/campaignBudgets/1547508174',
      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: 1483704368,
      labels: [],
      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/9262111890/campaigns/1483704368',
      serving_status: 2,
      start_date: '2018-07-23',
      status: 2,
      target_spend: { cpc_bid_ceiling_micros: 12000000 },
      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 a CampaignFeed

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.campaignFeeds.create([campaign_feed, other_campaign_feed], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/campaignFeeds/1483704368~82896692'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CampaignFeed

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

Arguments

entity required

The CampaignFeed 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 campaign_feed = {
  resource_name: 'customers/9262111890/campaignFeeds/1483704368~82896692', // 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.campaignFeeds.update(campaign_feed)

// Passing in an array of entities to update, validating only
const result = await customer.campaignFeeds.update([campaign_feed, other_campaign_feed], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/campaignFeeds/1483704368~82896692'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CampaignFeed

The customer.campaignFeeds.delete(resource_name) sets the status field of a CampaignFeed 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 CampaignFeed

Returns

Nothing

// Deleting the entity

await customer.campaignFeeds.delete('customers/9262111890/campaignFeeds/1483704368~82896692')

CampaignLabel

The CampaignLabel object

Fields

campaign string

Immutable. The campaign to which the label is attached.

label string

Immutable. The label assigned to the campaign.

resource_name string

Immutable. Name of the resource. Campaign label resource names have the form: customers/{customer_id}/campaignLabels/{campaign_id}~{label_id}

// Example CampaignLabel
const campaign_label = {
  campaign: 'customers/3827277046/campaigns/881817006',
  label: 'customers/3827277046/labels/898377018',
  resource_name: 'customers/3827277046/campaignLabels/881817006~898377018',
}

Get a CampaignLabel

The customer.campaignLabels.get(resource_name) method returns the CampaignLabel identified by a resource_name.

Arguments

resource_name required

The resource_name of that CampaignLabel

Returns

Returns that CampaignLabel as an object.

// Getting the entity
let result = await customer.campaignLabels.get('customers/3827277046/campaignLabels/881817006~898377018')

// Example result
;({
  campaign: 'customers/3827277046/campaigns/881817006',
  label: 'customers/3827277046/labels/898377018',
  resource_name: 'customers/3827277046/campaignLabels/881817006~898377018',
})

List every instance of CampaignLabel

The customer.campaignLabels.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 CampaignLabel.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.campaignLabels.list({
  constraints: [
    {
      key: 'campaign_label.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'campaign_label.some_field.sub_field',
})

// Example result
;[
  {
    campaign_label: {
      campaign: 'customers/3827277046/campaigns/881817006',
      label: 'customers/3827277046/labels/898377018',
      resource_name: 'customers/3827277046/campaignLabels/881817006~898377018',
    },
    label: {
      id: 898377018,
      name: 'My label',
      resource_name: 'customers/3827277046/labels/898377018',
      status: 2,
      text_label: { background_color: '#ccccff', description: '' },
    },
    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 a CampaignLabel

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.campaignLabels.create([campaign_label, other_campaign_label], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/campaignLabels/881817006~898377018'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CampaignLabel

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

Arguments

entity required

The CampaignLabel 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 campaign_label = {
  resource_name: 'customers/3827277046/campaignLabels/881817006~898377018', // 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.campaignLabels.update(campaign_label)

// Passing in an array of entities to update, validating only
const result = await customer.campaignLabels.update([campaign_label, other_campaign_label], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/campaignLabels/881817006~898377018'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CampaignLabel

The customer.campaignLabels.delete(resource_name) sets the status field of a CampaignLabel 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 CampaignLabel

Returns

Nothing

// Deleting the entity

await customer.campaignLabels.delete('customers/3827277046/campaignLabels/881817006~898377018')

CampaignSharedSet

The CampaignSharedSet object

Fields

campaign string

Immutable. The campaign to which the campaign shared set belongs.

resource_name string

Immutable. The resource name of the campaign shared set. Campaign shared set resource names have the form: customers/{customer_id}/campaignSharedSets/{campaign_id}~{shared_set_id}

shared_set string

Immutable. The shared set associated with the campaign. This may be a negative keyword shared set of another customer. This customer should be a manager of the other customer, otherwise the campaign shared set will exist but have no serving effect. Only negative keyword shared sets can be associated with Shopping campaigns. Only negative placement shared sets can be associated with Display mobile app campaigns.

status enum

Output only. The status of this campaign shared set. Read only.

// Example CampaignSharedSet
const campaign_shared_set = {
  campaign: 'customers/9262111890/campaigns/1485014801',
  resource_name: 'customers/9262111890/campaignSharedSets/1485014801~1788591305',
  shared_set: 'customers/9262111890/sharedSets/1788591305',
  status: 3,
}

Get a CampaignSharedSet

The customer.campaignSharedSets.get(resource_name) method returns the CampaignSharedSet identified by a resource_name.

Arguments

resource_name required

The resource_name of that CampaignSharedSet

Returns

Returns that CampaignSharedSet as an object.

// Getting the entity
let result = await customer.campaignSharedSets.get('customers/9262111890/campaignSharedSets/1485014801~1788591305')

// Example result
;({
  campaign: 'customers/9262111890/campaigns/1485014801',
  resource_name: 'customers/9262111890/campaignSharedSets/1485014801~1788591305',
  shared_set: 'customers/9262111890/sharedSets/1788591305',
  status: 3,
})

List every instance of CampaignSharedSet

The customer.campaignSharedSets.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 CampaignSharedSet.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.campaignSharedSets.list({
  constraints: [
    {
      key: 'campaign_shared_set.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'campaign_shared_set.some_field.sub_field',
})

// Example result
;[
  {
    campaign_shared_set: {
      campaign: 'customers/9262111890/campaigns/1485014801',
      resource_name: 'customers/9262111890/campaignSharedSets/1485014801~1788591305',
      shared_set: 'customers/9262111890/sharedSets/1788591305',
      status: 3,
    },
    shared_set: {
      id: 1788591305,
      member_count: 6,
      name: 'My shared set',
      reference_count: 0,
      resource_name: 'customers/9262111890/sharedSets/1788591305',
      status: 2,
      type: 2,
    },
    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 a CampaignSharedSet

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.campaignSharedSets.create([campaign_shared_set, other_campaign_shared_set], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/campaignSharedSets/1485014801~1788591305'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CampaignSharedSet

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

Arguments

entity required

The CampaignSharedSet 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 campaign_shared_set = {
  resource_name: 'customers/9262111890/campaignSharedSets/1485014801~1788591305', // 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.campaignSharedSets.update(campaign_shared_set)

// Passing in an array of entities to update, validating only
const result = await customer.campaignSharedSets.update([campaign_shared_set, other_campaign_shared_set], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/campaignSharedSets/1485014801~1788591305'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CampaignSharedSet

The customer.campaignSharedSets.delete(resource_name) sets the status field of a CampaignSharedSet 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 CampaignSharedSet

Returns

Nothing

// Deleting the entity

await customer.campaignSharedSets.delete('customers/9262111890/campaignSharedSets/1485014801~1788591305')

CarrierConstant

The CarrierConstant object

Fields

country_code string

Output only. The country code of the country where the carrier is located, e.g., "AR", "FR", etc.

id int64

Output only. The ID of the carrier criterion.

name string

Output only. The full name of the carrier in English.

resource_name string

Output only. The resource name of the carrier criterion. Carrier criterion resource names have the form: carrierConstants/{criterion_id}

// Example CarrierConstant
const carrier_constant = {
  country_code: 'TW',
  id: 70720,
  name: 'Long Distance & Mobile Business Group',
  resource_name: 'carrierConstants/70720',
}

Get a CarrierConstant

The customer.carrierConstants.get(resource_name) method returns the CarrierConstant identified by a resource_name.

Arguments

resource_name required

The resource_name of that CarrierConstant

Returns

Returns that CarrierConstant as an object.

// Getting the entity
let result = await customer.carrierConstants.get('carrierConstants/70720')

// Example result
;({
  country_code: 'TW',
  id: 70720,
  name: 'Long Distance & Mobile Business Group',
  resource_name: 'carrierConstants/70720',
})

List every instance of CarrierConstant

The customer.carrierConstants.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 CarrierConstant.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.carrierConstants.list({
  constraints: [
    {
      key: 'carrier_constant.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'carrier_constant.some_field.sub_field',
})

// Example result
;[
  {
    carrier_constant: {
      country_code: 'TW',
      id: 70720,
      name: 'Long Distance & Mobile Business Group',
      resource_name: 'carrierConstants/70720',
    },
  },
]

ChangeStatus

The ChangeStatus object

Fields

ad_group string

Output only. The AdGroup affected by this change.

ad_group_ad string

Output only. The AdGroupAd affected by this change.

ad_group_bid_modifier string

Output only. The AdGroupBidModifier affected by this change.

ad_group_criterion string

Output only. The AdGroupCriterion affected by this change.

ad_group_feed string

Output only. The AdGroupFeed affected by this change.

campaign string

Output only. The Campaign affected by this change.

campaign_criterion string

Output only. The CampaignCriterion affected by this change.

campaign_feed string

Output only. The CampaignFeed affected by this change.

feed string

Output only. The Feed affected by this change.

feed_item string

Output only. The FeedItem affected by this change.

last_change_date_time string

Output only. Time at which the most recent change has occurred on this resource.

resource_name string

Output only. The resource name of the change status. Change status resource names have the form: customers/{customer_id}/changeStatus/{change_status_id}

resource_status enum

Output only. Represents the status of the changed resource.

resource_type enum

Output only. Represents the type of the changed resource. This dictates what fields will be set. For example, for AD_GROUP, campaign and ad_group fields will be set.

// Example ChangeStatus
const change_status = {
  feed: 'customers/9262111890/feeds/82896692',
  feed_item: 'customers/9262111890/feedItems/82896692~51844020102',
  last_change_date_time: '2020-07-13 09:01:10.844783',
  resource_name: 'customers/9262111890/changeStatus/1594627270844783-10-82896692-51844020102',
  resource_status: 3,
  resource_type: 10,
}

Get a ChangeStatus

The customer.changeStatus.get(resource_name) method returns the ChangeStatus identified by a resource_name.

Arguments

resource_name required

The resource_name of that ChangeStatus

Returns

Returns that ChangeStatus as an object.

// Getting the entity
let result = await customer.changeStatus.get(
  'customers/9262111890/changeStatus/1594627270844783-10-82896692-51844020102'
)

// Example result
;({
  feed: 'customers/9262111890/feeds/82896692',
  feed_item: 'customers/9262111890/feedItems/82896692~51844020102',
  last_change_date_time: '2020-07-13 09:01:10.844783',
  resource_name: 'customers/9262111890/changeStatus/1594627270844783-10-82896692-51844020102',
  resource_status: 3,
  resource_type: 10,
})

List every instance of ChangeStatus

The customer.changeStatus.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 ChangeStatus.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.changeStatus.list({
  constraints: [
    {
      key: 'change_status.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'change_status.some_field.sub_field',
})

// Example result
;[
  {
    change_status: {
      feed: 'customers/9262111890/feeds/82896692',
      feed_item: 'customers/9262111890/feedItems/82896692~51844020102',
      last_change_date_time: '2020-07-13 09:01:10.844783',
      resource_name: 'customers/9262111890/changeStatus/1594627270844783-10-82896692-51844020102',
      resource_status: 3,
      resource_type: 10,
    },
    feed: {
      attributes: [
        { id: 1, name: 'SitelinkName', type: 4, is_part_of_key: false },
        { id: 2, name: 'SitelinkUrl', type: 6, is_part_of_key: false },
        { id: 3, name: 'SitelinkDescription1', type: 4, is_part_of_key: false },
        { id: 4, name: 'SitelinkDescription2', type: 4, is_part_of_key: false },
        { id: 5, name: 'SitelinkFinalUrls', type: 12, is_part_of_key: false },
        { id: 6, name: 'SitelinkFinalMobileUrls', type: 12, is_part_of_key: false },
        { id: 7, name: 'SitelinkTrackingUrl', type: 6, is_part_of_key: false },
        { id: 8, name: 'SitelinkFinalUrlSuffix', type: 4, is_part_of_key: false },
      ],
      id: 82896692,
      name: 'My feed',
      origin: 3,
      resource_name: 'customers/9262111890/feeds/82896692',
      status: 2,
    },
    feed_item: {
      attribute_values: [
        {
          feed_attribute_id: 1,
          string_value: 'my sitelink text',
          integer_values_list: [],
          boolean_values_list: [],
          string_values_list: [],
          double_values_list: [],
        },
        {
          feed_attribute_id: 3,
          string_value: 'description here',
          integer_values_list: [],
          boolean_values_list: [],
          string_values_list: [],
          double_values_list: [],
        },
        {
          feed_attribute_id: 4,
          string_value: 'description here line 2',
          integer_values_list: [],
          boolean_values_list: [],
          string_values_list: [],
          double_values_list: [],
        },
        {
          feed_attribute_id: 5,
          integer_values_list: [],
          boolean_values_list: [],
          string_values_list: ['https://myurl.com'],
          double_values_list: [],
        },
      ],
      feed: 'customers/9262111890/feeds/82896692',
      geo_targeting_restriction: 0,
      id: 51844020102,
      policy_infos: [
        {
          placeholder_type_enum: 2,
          feed_mapping_resource_name: 'customers/9262111890/feedMappings/82896692~91300060',
          review_status: 0,
          approval_status: 0,
          policy_topic_entries_list: [],
          validation_status: 4,
          validation_errors_list: [],
          quality_approval_status: 0,
          quality_disapproval_reasons_list: [],
        },
      ],
      resource_name: 'customers/9262111890/feedItems/82896692~51844020102',
      status: 2,
      url_custom_parameters: [],
    },
    ad_group: {
      ad_rotation_mode: 0,
      display_custom_bid_dimension: 0,
      effective_target_cpa_source: 0,
      effective_target_roas_source: 0,
      id: 0,
      labels: [],
      resource_name: '',
      status: 0,
      type: 0,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 0,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 0,
      bidding_strategy_type: 0,
      experiment_type: 0,
      frequency_caps: [],
      id: 0,
      labels: [],
      payment_mode: 0,
      resource_name: '',
      serving_status: 0,
      status: 0,
      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',
    },
  },
]

ConversionAction

The ConversionAction object

Fields

app_id string

App ID for an app conversion action.

attribution_model_settings object

Settings related to this conversion action's attribution model.

attribution_model enum

The attribution model type of this conversion action.

data_driven_model_status enum

Output only. The status of the data-driven attribution model for the conversion action.

category enum

The category of conversions reported for this conversion action.

click_through_lookback_window_days int64

The maximum number of days that may elapse between an interaction (e.g., a click) and a conversion event.

counting_type enum

How to count conversion events for the conversion action.

firebase_settings object

Output only. Firebase settings for Firebase conversion types.

id int64

Output only. The ID of the conversion action.

include_in_conversions_metric boolean

Whether this conversion action should be included in the "conversions" metric.

mobile_app_vendor enum

Output only. Mobile app vendor for an app conversion action.

name string

The name of the conversion action. This field is required and should not be empty when creating new conversion actions.

owner_customer string

Output only. The resource name of the conversion action owner customer, or null if this is a system-defined conversion action.

phone_call_duration_seconds int64

The phone call duration in seconds after which a conversion should be reported for this conversion action. The value must be between 0 and 10000, inclusive.

resource_name string

Immutable. The resource name of the conversion action. Conversion action resource names have the form: customers/{customer_id}/conversionActions/{conversion_action_id}

status enum

The status of this conversion action for conversion event accrual.

tag_snippets array of objects

Output only. The snippets used for tracking conversions.

third_party_app_analytics_settings object

Output only. Third Party App Analytics settings for third party conversion types.

type enum

Immutable. The type of this conversion action.

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
AD_CALL (2)
Conversions that occur when a user clicks on an ad's call extension.
CLICK_TO_CALL (3)
Conversions that occur when a user on a mobile device clicks a phone number.
GOOGLE_PLAY_DOWNLOAD (4)
Conversions that occur when a user downloads a mobile app from the Google Play Store.
GOOGLE_PLAY_IN_APP_PURCHASE (5)
Conversions that occur when a user makes a purchase in an app through Android billing.
UPLOAD_CALLS (6)
Call conversions that are tracked by the advertiser and uploaded.
UPLOAD_CLICKS (7)
Conversions that are tracked by the advertiser and uploaded with attributed clicks.
WEBPAGE (8)
Conversions that occur on a webpage.
WEBSITE_CALL (9)
Conversions that occur when a user calls a dynamically-generated phone number from an advertiser's website.
STORE_SALES_DIRECT_UPLOAD (10)
Store Sales conversion based on first-party or third-party merchant data uploads. Only whitelisted customers can use store sales direct upload types.
STORE_SALES (11)
Store Sales conversion based on first-party or third-party merchant data uploads and/or from in-store purchases using cards from payment networks. Only whitelisted customers can use store sales types.
FIREBASE_ANDROID_FIRST_OPEN (12)
Android app first open conversions tracked via Firebase.
FIREBASE_ANDROID_IN_APP_PURCHASE (13)
Android app in app purchase conversions tracked via Firebase.
FIREBASE_ANDROID_CUSTOM (14)
Android app custom conversions tracked via Firebase.
FIREBASE_IOS_FIRST_OPEN (15)
iOS app first open conversions tracked via Firebase.
FIREBASE_IOS_IN_APP_PURCHASE (16)
iOS app in app purchase conversions tracked via Firebase.
FIREBASE_IOS_CUSTOM (17)
iOS app custom conversions tracked via Firebase.
THIRD_PARTY_APP_ANALYTICS_ANDROID_FIRST_OPEN (18)
Android app first open conversions tracked via Third Party App Analytics.
THIRD_PARTY_APP_ANALYTICS_ANDROID_IN_APP_PURCHASE (19)
Android app in app purchase conversions tracked via Third Party App Analytics.
THIRD_PARTY_APP_ANALYTICS_ANDROID_CUSTOM (20)
Android app custom conversions tracked via Third Party App Analytics.
THIRD_PARTY_APP_ANALYTICS_IOS_FIRST_OPEN (21)
iOS app first open conversions tracked via Third Party App Analytics.
THIRD_PARTY_APP_ANALYTICS_IOS_IN_APP_PURCHASE (22)
iOS app in app purchase conversions tracked via Third Party App Analytics.
THIRD_PARTY_APP_ANALYTICS_IOS_CUSTOM (23)
iOS app custom conversions tracked via Third Party App Analytics.

value_settings object

Settings related to the value for conversion events associated with this conversion action.

view_through_lookback_window_days int64

The maximum number of days which may elapse between an impression and a conversion without an interaction.

// Example ConversionAction
const conversion_action = {
  attribution_model_settings: { attribution_model: 105, data_driven_model_status: 5 },
  category: 5,
  click_through_lookback_window_days: 7,
  counting_type: 3,
  id: 314732636,
  include_in_conversions_metric: true,
  mobile_app_vendor: 1,
  name: 'My conversion action',
  owner_customer: 'customers/9262111890',
  phone_call_duration_seconds: 60,
  resource_name: 'customers/9262111890/conversionActions/314732636',
  status: 3,
  tag_snippets: [
    {
      type: 3,
      page_format: 2,
      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",
      event_snippet:
        "<!-- Event snippet for test-conversion-action-6661770 (created during library test) conversion page\nIn your html page, add the snippet and call gtag_report_conversion when someone clicks on the chosen link or button. -->\n<script>\nfunction gtag_report_conversion(url) {\n  var callback = function () {\n    if (typeof(url) != 'undefined') {\n      window.location = url;\n    }\n  };\n  gtag('event', 'conversion', {\n      'send_to': 'AW-797556569/5CprCNzgiZYBENn-pvwC',\n      'value': 5.0,\n      'currency': 'USD',\n      'event_callback': callback\n  });\n  return false;\n}\n</script>\n",
    },
    {
      type: 3,
      page_format: 3,
      global_site_tag:
        '<!-- Global site tag (gtag) - Google Ads: 797556569 -->\n<amp-analytics type="gtag" data-credentials="include">\n<script type="application/json">\n{\n  "vars": {\n    "gtag_id": "AW-797556569",\n    "config": {\n      "AW-797556569": {\n        "groups": "default"\n      }\n    }\n  },\n  "triggers": {\n  }\n}\n</script>\n</amp-analytics>\n',
      event_snippet:
        '"C_yfcHXCUzChg": {\n  "on": "click",\n  "selector": "CSS_SELECTOR",\n  "vars": {\n    "event_name": "conversion",\n    "value": 5.0,\n    "currency": "USD",\n    "send_to": ["AW-797556569/5CprCNzgiZYBENn-pvwC"]\n  }\n}\n',
    },
    {
      type: 2,
      page_format: 2,
      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",
      event_snippet:
        "<!-- Event snippet for test-conversion-action-6661770 (created during library test) conversion page -->\n<script>\n  gtag('event', 'conversion', {\n      'send_to': 'AW-797556569/5CprCNzgiZYBENn-pvwC',\n      'value': 5.0,\n      'currency': 'USD'\n  });\n</script>\n",
    },
    {
      type: 2,
      page_format: 3,
      global_site_tag:
        '<!-- Global site tag (gtag) - Google Ads: 797556569 -->\n<amp-analytics type="gtag" data-credentials="include">\n<script type="application/json">\n{\n  "vars": {\n    "gtag_id": "AW-797556569",\n    "config": {\n      "AW-797556569": {\n        "groups": "default"\n      }\n    }\n  },\n  "triggers": {\n  }\n}\n</script>\n</amp-analytics>\n',
      event_snippet:
        '"C_yfcHXCUzChg": {\n  "on": "visible",\n  "vars": {\n    "event_name": "conversion",\n    "value": 5.0,\n    "currency": "USD",\n    "send_to": ["AW-797556569/5CprCNzgiZYBENn-pvwC"]\n  }\n}\n',
    },
  ],
  type: 8,
  value_settings: { always_use_default_value: false, default_currency_code: 'USD', default_value: 5 },
  view_through_lookback_window_days: 1,
}

Get a ConversionAction

The customer.conversionActions.get(resource_name) method returns the ConversionAction identified by a resource_name.

Arguments

resource_name required

The resource_name of that ConversionAction

Returns

Returns that ConversionAction as an object.

// Getting the entity
let result = await customer.conversionActions.get('customers/9262111890/conversionActions/314732636')

// Example result
;({
  attribution_model_settings: { attribution_model: 105, data_driven_model_status: 5 },
  category: 5,
  click_through_lookback_window_days: 7,
  counting_type: 3,
  id: 314732636,
  include_in_conversions_metric: true,
  mobile_app_vendor: 1,
  name: 'My conversion action',
  owner_customer: 'customers/9262111890',
  phone_call_duration_seconds: 60,
  resource_name: 'customers/9262111890/conversionActions/314732636',
  status: 3,
  tag_snippets: [
    {
      type: 3,
      page_format: 2,
      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",
      event_snippet:
        "<!-- Event snippet for test-conversion-action-6661770 (created during library test) conversion page\nIn your html page, add the snippet and call gtag_report_conversion when someone clicks on the chosen link or button. -->\n<script>\nfunction gtag_report_conversion(url) {\n  var callback = function () {\n    if (typeof(url) != 'undefined') {\n      window.location = url;\n    }\n  };\n  gtag('event', 'conversion', {\n      'send_to': 'AW-797556569/5CprCNzgiZYBENn-pvwC',\n      'value': 5.0,\n      'currency': 'USD',\n      'event_callback': callback\n  });\n  return false;\n}\n</script>\n",
    },
    {
      type: 3,
      page_format: 3,
      global_site_tag:
        '<!-- Global site tag (gtag) - Google Ads: 797556569 -->\n<amp-analytics type="gtag" data-credentials="include">\n<script type="application/json">\n{\n  "vars": {\n    "gtag_id": "AW-797556569",\n    "config": {\n      "AW-797556569": {\n        "groups": "default"\n      }\n    }\n  },\n  "triggers": {\n  }\n}\n</script>\n</amp-analytics>\n',
      event_snippet:
        '"C_yfcHXCUzChg": {\n  "on": "click",\n  "selector": "CSS_SELECTOR",\n  "vars": {\n    "event_name": "conversion",\n    "value": 5.0,\n    "currency": "USD",\n    "send_to": ["AW-797556569/5CprCNzgiZYBENn-pvwC"]\n  }\n}\n',
    },
    {
      type: 2,
      page_format: 2,
      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",
      event_snippet:
        "<!-- Event snippet for test-conversion-action-6661770 (created during library test) conversion page -->\n<script>\n  gtag('event', 'conversion', {\n      'send_to': 'AW-797556569/5CprCNzgiZYBENn-pvwC',\n      'value': 5.0,\n      'currency': 'USD'\n  });\n</script>\n",
    },
    {
      type: 2,
      page_format: 3,
      global_site_tag:
        '<!-- Global site tag (gtag) - Google Ads: 797556569 -->\n<amp-analytics type="gtag" data-credentials="include">\n<script type="application/json">\n{\n  "vars": {\n    "gtag_id": "AW-797556569",\n    "config": {\n      "AW-797556569": {\n        "groups": "default"\n      }\n    }\n  },\n  "triggers": {\n  }\n}\n</script>\n</amp-analytics>\n',
      event_snippet:
        '"C_yfcHXCUzChg": {\n  "on": "visible",\n  "vars": {\n    "event_name": "conversion",\n    "value": 5.0,\n    "currency": "USD",\n    "send_to": ["AW-797556569/5CprCNzgiZYBENn-pvwC"]\n  }\n}\n',
    },
  ],
  type: 8,
  value_settings: { always_use_default_value: false, default_currency_code: 'USD', default_value: 5 },
  view_through_lookback_window_days: 1,
})

List every instance of ConversionAction

The customer.conversionActions.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 ConversionAction.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.conversionActions.list({
  constraints: [
    {
      key: 'conversion_action.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'conversion_action.some_field.sub_field',
})

// Example result
;[
  {
    conversion_action: {
      attribution_model_settings: { attribution_model: 105, data_driven_model_status: 5 },
      category: 5,
      click_through_lookback_window_days: 7,
      counting_type: 3,
      id: 314732636,
      include_in_conversions_metric: true,
      mobile_app_vendor: 1,
      name: 'My conversion action',
      owner_customer: 'customers/9262111890',
      phone_call_duration_seconds: 60,
      resource_name: 'customers/9262111890/conversionActions/314732636',
      status: 3,
      tag_snippets: [
        {
          type: 3,
          page_format: 2,
          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",
          event_snippet:
            "<!-- Event snippet for test-conversion-action-6661770 (created during library test) conversion page\nIn your html page, add the snippet and call gtag_report_conversion when someone clicks on the chosen link or button. -->\n<script>\nfunction gtag_report_conversion(url) {\n  var callback = function () {\n    if (typeof(url) != 'undefined') {\n      window.location = url;\n    }\n  };\n  gtag('event', 'conversion', {\n      'send_to': 'AW-797556569/5CprCNzgiZYBENn-pvwC',\n      'value': 5.0,\n      'currency': 'USD',\n      'event_callback': callback\n  });\n  return false;\n}\n</script>\n",
        },
        {
          type: 3,
          page_format: 3,
          global_site_tag:
            '<!-- Global site tag (gtag) - Google Ads: 797556569 -->\n<amp-analytics type="gtag" data-credentials="include">\n<script type="application/json">\n{\n  "vars": {\n    "gtag_id": "AW-797556569",\n    "config": {\n      "AW-797556569": {\n        "groups": "default"\n      }\n    }\n  },\n  "triggers": {\n  }\n}\n</script>\n</amp-analytics>\n',
          event_snippet:
            '"C_yfcHXCUzChg": {\n  "on": "click",\n  "selector": "CSS_SELECTOR",\n  "vars": {\n    "event_name": "conversion",\n    "value": 5.0,\n    "currency": "USD",\n    "send_to": ["AW-797556569/5CprCNzgiZYBENn-pvwC"]\n  }\n}\n',
        },
        {
          type: 2,
          page_format: 2,
          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",
          event_snippet:
            "<!-- Event snippet for test-conversion-action-6661770 (created during library test) conversion page -->\n<script>\n  gtag('event', 'conversion', {\n      'send_to': 'AW-797556569/5CprCNzgiZYBENn-pvwC',\n      'value': 5.0,\n      'currency': 'USD'\n  });\n</script>\n",
        },
        {
          type: 2,
          page_format: 3,
          global_site_tag:
            '<!-- Global site tag (gtag) - Google Ads: 797556569 -->\n<amp-analytics type="gtag" data-credentials="include">\n<script type="application/json">\n{\n  "vars": {\n    "gtag_id": "AW-797556569",\n    "config": {\n      "AW-797556569": {\n        "groups": "default"\n      }\n    }\n  },\n  "triggers": {\n  }\n}\n</script>\n</amp-analytics>\n',
          event_snippet:
            '"C_yfcHXCUzChg": {\n  "on": "visible",\n  "vars": {\n    "event_name": "conversion",\n    "value": 5.0,\n    "currency": "USD",\n    "send_to": ["AW-797556569/5CprCNzgiZYBENn-pvwC"]\n  }\n}\n',
        },
      ],
      type: 8,
      value_settings: { always_use_default_value: false, default_currency_code: 'USD', default_value: 5 },
      view_through_lookback_window_days: 1,
    },
    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 a ConversionAction

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.conversionActions.create([conversion_action, other_conversion_action], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/conversionActions/314732636'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a ConversionAction

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

Arguments

entity required

The ConversionAction 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 conversion_action = {
  resource_name: 'customers/9262111890/conversionActions/314732636', // 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.conversionActions.update(conversion_action)

// Passing in an array of entities to update, validating only
const result = await customer.conversionActions.update([conversion_action, other_conversion_action], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/conversionActions/314732636'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a ConversionAction

The customer.conversionActions.delete(resource_name) sets the status field of a ConversionAction 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 ConversionAction

Returns

Nothing

// Deleting the entity

await customer.conversionActions.delete('customers/9262111890/conversionActions/314732636')

ConversionUpload

Upload ConversionCalls

The customer.conversionUploads.uploadCallConversions(call_conversions) method uploads call conversions to an account. It requires an array of call conversions.

Arguments

entity required

An array of call conversions.
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.
all_results optional, boolean

Boolean adding true will return an array of all uploaded conversions, defaults to false

Returns

results

an array of information for successfully processed CallConversionUpload.
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.

// uploading CallConversions

const call_conversions: CallConversion[] = [
  {
    // Your CallConversion here
  },
  {
    // Your CallConversion here
  },
]

// Getting identifying information for all uploads
const result = await customer.conversionUploads.uploadCallConversions(call_conversions, {}, true)

// Getting identifying information for all uploads with options
const result = await customer.conversionUploads.uploadCallConversions(
  call_conversions,
  {
    validate_only: true,
  },
  true
)

// Getting identifying information for the first uploaded item
const result = await customer.conversionUploads.uploadCallConversions(call_conversions)

// Example result

{
	results: [
		{
			caller_id: '+442087599036',
			call_start_date_time: '2019-01-01 12:32:45-08:00',
			conversion_action: `customer/${CID}/conversionAction/123123123`,
			conversion_date_time: '2019-01-01 12:32:45-08:00',
		}
	],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Upload ConversionClicks

The customer.conversionUploads.uploadClickConversions(click_conversions) method uploads click conversions to an account. It requires an array of click conversions.

Arguments

entity required

An array of click conversions.
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.
all_results optional, boolean

Boolean adding true will return an array of all uploaded conversions, defaults to false

Returns

results

an array of information for successfully processed ClickConversionUpload.
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.

// uploading ClickConversions

const click_conversions: ClickConversion[] = [
  {
    // Your ClickConversion here
  },
  {
    // Your ClickConversion here
  },
]

// Getting identifying information for all uploads
const result = await customer.conversionUploads.uploadClickConversions(click_conversions, {}, true)

// Getting identifying information for all uploads with options
const result = await customer.conversionUploads.uploadClickConversions(
  click_conversions,
  {
    validate_only: true,
  },
  true
)

// Getting identifying information for the first uploaded item
const result = await customer.conversionUploads.uploadClickConversions(click_conversions)

// Example result

{
	results: [
		{
            gclid: '42812402112',
            conversion_action: 'beans',
            conversion_date_time: '2019-01-01 12:32:45-08:00',
            conversion_value: 320,
            currency_code: 'GBP',
            order_id: '32894129342',
            external_attribution_data: {
                external_attribution_credit: 925592,
                external_attribution_model: 'heinz',
            }

		}
	],
	partial_failure_error : null,
	request: { /* your request object */ }
}

CustomInterest

The CustomInterest object

Fields

description string

Description of this custom interest audience.

id int64

Output only. Id of the custom interest.

members array of objects

List of custom interest members that this custom interest is composed of. Members can be added during CustomInterest creation. If members are presented in UPDATE operation, existing members will be overridden.

name string

Name of the custom interest. It should be unique across the same custom affinity audience. This field is required for create operations.

resource_name string

Immutable. The resource name of the custom interest. Custom interest resource names have the form: customers/{customer_id}/customInterests/{custom_interest_id}

status enum

Status of this custom interest. Indicates whether the custom interest is enabled or removed.

type enum

Type of the custom interest, CUSTOM_AFFINITY or CUSTOM_INTENT. By default the type is set to CUSTOM_AFFINITY.

// Example CustomInterest
const custom_interest = {
  description: '',
  id: 13338354,
  members: [
    { member_type: 2, parameter: 'ppc' },
    { member_type: 2, parameter: 'google adwords ppc campaign' },
    { member_type: 2, parameter: 'google adwords ppc advertising' },
    { member_type: 2, parameter: 'ppc and google adwords' },
    { member_type: 2, parameter: 'is google adwords ppc' },
    { member_type: 2, parameter: 'google adwords ppc cost' },
    { member_type: 2, parameter: 'ppc google advertising' },
    { member_type: 2, parameter: 'google ads ppc' },
    { member_type: 2, parameter: 'google ad word campaign' },
    { member_type: 2, parameter: 'google ppc marketing' },
    { member_type: 2, parameter: 'google advertising adwords' },
    { member_type: 2, parameter: 'google ppc campaign' },
    { member_type: 2, parameter: 'what is google ppc advertising' },
    { member_type: 2, parameter: 'adwords ppc campaign' },
    { member_type: 2, parameter: 'google ppc agency' },
    { member_type: 2, parameter: 'google adwords agency' },
    { member_type: 2, parameter: 'google ppc' },
    { member_type: 2, parameter: 'google ppc services' },
    { member_type: 2, parameter: 'google ppc cost' },
    { member_type: 2, parameter: 'what is google ppc' },
    { member_type: 2, parameter: 'google ppc courses' },
    { member_type: 2, parameter: 'google ads' },
    { member_type: 2, parameter: 'adwords' },
  ],
  name: 'My custom interest',
  resource_name: 'customers/3827277046/customInterests/13338354',
  status: 2,
  type: 3,
}

Get a CustomInterest

The customer.customInterests.get(resource_name) method returns the CustomInterest identified by a resource_name.

Arguments

resource_name required

The resource_name of that CustomInterest

Returns

Returns that CustomInterest as an object.

// Getting the entity
let result = await customer.customInterests.get('customers/3827277046/customInterests/13338354')

// Example result
;({
  description: '',
  id: 13338354,
  members: [
    { member_type: 2, parameter: 'ppc' },
    { member_type: 2, parameter: 'google adwords ppc campaign' },
    { member_type: 2, parameter: 'google adwords ppc advertising' },
    { member_type: 2, parameter: 'ppc and google adwords' },
    { member_type: 2, parameter: 'is google adwords ppc' },
    { member_type: 2, parameter: 'google adwords ppc cost' },
    { member_type: 2, parameter: 'ppc google advertising' },
    { member_type: 2, parameter: 'google ads ppc' },
    { member_type: 2, parameter: 'google ad word campaign' },
    { member_type: 2, parameter: 'google ppc marketing' },
    { member_type: 2, parameter: 'google advertising adwords' },
    { member_type: 2, parameter: 'google ppc campaign' },
    { member_type: 2, parameter: 'what is google ppc advertising' },
    { member_type: 2, parameter: 'adwords ppc campaign' },
    { member_type: 2, parameter: 'google ppc agency' },
    { member_type: 2, parameter: 'google adwords agency' },
    { member_type: 2, parameter: 'google ppc' },
    { member_type: 2, parameter: 'google ppc services' },
    { member_type: 2, parameter: 'google ppc cost' },
    { member_type: 2, parameter: 'what is google ppc' },
    { member_type: 2, parameter: 'google ppc courses' },
    { member_type: 2, parameter: 'google ads' },
    { member_type: 2, parameter: 'adwords' },
  ],
  name: 'My custom interest',
  resource_name: 'customers/3827277046/customInterests/13338354',
  status: 2,
  type: 3,
})

List every instance of CustomInterest

The customer.customInterests.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 CustomInterest.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.customInterests.list({
  constraints: [
    {
      key: 'custom_interest.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'custom_interest.some_field.sub_field',
})

// Example result
;[
  {
    custom_interest: {
      description: '',
      id: 13338354,
      members: [
        { member_type: 2, parameter: 'ppc' },
        { member_type: 2, parameter: 'google adwords ppc campaign' },
        { member_type: 2, parameter: 'google adwords ppc advertising' },
        { member_type: 2, parameter: 'ppc and google adwords' },
        { member_type: 2, parameter: 'is google adwords ppc' },
        { member_type: 2, parameter: 'google adwords ppc cost' },
        { member_type: 2, parameter: 'ppc google advertising' },
        { member_type: 2, parameter: 'google ads ppc' },
        { member_type: 2, parameter: 'google ad word campaign' },
        { member_type: 2, parameter: 'google ppc marketing' },
        { member_type: 2, parameter: 'google advertising adwords' },
        { member_type: 2, parameter: 'google ppc campaign' },
        { member_type: 2, parameter: 'what is google ppc advertising' },
        { member_type: 2, parameter: 'adwords ppc campaign' },
        { member_type: 2, parameter: 'google ppc agency' },
        { member_type: 2, parameter: 'google adwords agency' },
        { member_type: 2, parameter: 'google ppc' },
        { member_type: 2, parameter: 'google ppc services' },
        { member_type: 2, parameter: 'google ppc cost' },
        { member_type: 2, parameter: 'what is google ppc' },
        { member_type: 2, parameter: 'google ppc courses' },
        { member_type: 2, parameter: 'google ads' },
        { member_type: 2, parameter: 'adwords' },
      ],
      name: 'My custom interest',
      resource_name: 'customers/3827277046/customInterests/13338354',
      status: 2,
      type: 3,
    },
    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 a CustomInterest

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.customInterests.create([custom_interest, other_custom_interest], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/customInterests/13338354'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CustomInterest

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

Arguments

entity required

The CustomInterest 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 custom_interest = {
  resource_name: 'customers/3827277046/customInterests/13338354', // 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.customInterests.update(custom_interest)

// Passing in an array of entities to update, validating only
const result = await customer.customInterests.update([custom_interest, other_custom_interest], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/customInterests/13338354'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CustomInterest

The customer.customInterests.delete(resource_name) sets the status field of a CustomInterest 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 CustomInterest

Returns

Nothing

// Deleting the entity

await customer.customInterests.delete('customers/3827277046/customInterests/13338354')

Customer

The customer resource is the root of all other resources in this library. On top of the usual self-get and self-mutate methods, it also features methods useful for reporting and mutations across several resource types.

The Customer object

Fields

tracking_url_template string

The URL template for constructing a tracking URL out of parameters.

auto_tagging_enabled boolean

Whether auto-tagging is enabled for the customer.

currency_code string

The currency in which the account operates. A subset of the currency codes from the ISO 4217 standard is supported.

remarketing_setting object

conversion_tracking_setting object

time_zone string

The local timezone ID of the customer.

call_reporting_setting object

test_account boolean

Whether the customer is a test account.

manager boolean

Whether the customer is a manager.

descriptive_name string

Optional, non-unique descriptive name of the customer.

id int64

The ID of the customer.

has_partners_badge boolean

Whether the Customer has a Partners program badge. If the Customer is not associated with the Partners program, this will be false. For more information, see https://support.google.com/partners/answer/3125774.

final_url_suffix string

The URL template for appending params to the final URL

resource_name string

The resource name of the customer. Customer resource names have the form: customers/{customer_id}

// Example Customer
const customer = {
  resource_name: 'customers/9262111890',
  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,
  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",
  },
  test_account: true,
  time_zone: 'Europe/London',
}

Get a Customer

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

Arguments

id required

The ID (aka CID) of that customer, without dashes, such as 1231231234.

Returns

Returns that Customer as an object.

// Getting the entity
let result = await customer.get('9262111890')

// Example result
;({
  resource_name: 'customers/9262111890',
  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,
  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",
  },
  test_account: true,
  time_zone: 'Europe/London',
})

Query

The customer.query(gaql_string) method takes an SQL-like string and returns the queried rows. For more information about how and when to use this method, see the reporting section.

Arguments

gaql_string string, required

The SQL-like string.

Returns

An array of objects, each object containing the keys requested in the query.

const ads_with_urls = await customer.query(`
    SELECT 
      ad_group.id,
      ad_group_ad.ad.id,
      ad_group_ad.ad.expanded_text_ad.headline_part1,
      ad_group_ad.ad.text_ad.headline,
      metrics.impressions
    FROM 
        ad_group_ad 
    WHERE 
        campaign.status = ENABLED 
        AND ad_group_ad.ad.type IN ('TEXT_AD', 'EXPANDED_TEXT_AD')
        AND metrics.impressions > 0 
        AND segments.date >= '2018-02-25'
        AND segments.date <= '2019-03-01'
    ORDER BY metrics.impressions DESC
    LIMIT 3
`)

// result rows
;[
  {
    ad_group: { resource_name: 'customers/3827277046/adGroups/45808681353', id: 45808681353 },
    ad_group_ad: {
      resource_name: 'customers/3827277046/adGroupAds/45808681353~266534257097',
      ad: { expanded_text_ad: { headline_part_1: 'best ad ever' }, id: 266534257097 },
    },
    metrics: { impressions: 1473 },
  },
  {
    ad_group: { resource_name: 'customers/3827277046/adGroups/45808681353', id: 45808681353 },
    ad_group_ad: {
      resource_name: 'customers/3827277046/adGroupAds/45808681353~304364243717',
      ad: { expanded_text_ad: { headline_part_1: 'next best ad' }, id: 304364243717 },
    },
    metrics: { impressions: 959 },
  },
  {
    ad_group: { resource_name: 'customers/3827277046/adGroups/69639056868', id: 69639056868 },
    ad_group_ad: {
      resource_name: 'customers/3827277046/adGroupAds/69639056868~307847364192',
      ad: { text_ad: { headline: 'pretty okay ad i guess' }, id: 307847364192 },
    },
    metrics: { impressions: 533 },
  },
]

Report

The customer.report() method is very similar to customer.query, except that it takes a query-building object as an argument. For more information about why this is a good idea, see the reporting section

Arguments

query object, required

An object of the form:
- entity string, required
  
  The resource to query. All core resources can be queried, as well as the views defined in the official docs. Note that this field expects resources in snake_case.
- attributes array, optional
  
  The attributes to query. Check the core resource on this page to see which attributes are available.
- metrics array, optional
  
  The metrics to query.
- segments array, optional
  
  The segments to split your metrics by. Note that segments will increase your number of result rows, and that attributes will simply be repeated.
- constraints array, optional
  
  Constraints should be provided as an array. Each constraint is of the form:
  - key string, required
    
    The field that you are applying a constraint on.
  - op string, required
    
    The operator, such as = or NOT IN.
  - val required
    
    The value to check. This can either be a string or an enum.
  Since this is quite verbose, we have a few of shorthands explained in the example code to the right.
- date_constant string, optional
  
  One of the date constants defined in the query grammar, such as LAST_30_DAYS
- from_date string, optional
  
  The start date for any metrics in your query. Only valid if date_constant is not defined.
- to_date string, optional
  
  The end date for any metrics in your query. Defaults to today. Only valid if date_constant is not defined.
- limit number, optional
  
  The number of rows to return. Useful when used with order_by.
- order_by string, optional
  
  The field to order your results by.
- sort_order string, optional
  
  The order direction. Either DESC or ASC
- page_size number, optional
  
  This library handles paging automatically. If the number of returned rows is larger than the page size, it will paginate through result sets and return all of the results when done. Defaults to 10,000.

Returns

An array of objects, each object containing the keys requested in the query.

// This example will generate the same results as the query() call above
let ads_with_urls = await customer.report({
  entity: 'ad_group_ad',
  attributes: [
    'ad_group_ad.ad.id',
    'ad_group.id',
    'ad_group_ad.ad.expanded_text_ad.headline_part1',
    'ad_group_ad.ad.text_ad.headline',
  ],
  metrics: ['metrics.impressions'],
  constraints: [
    { key: 'metrics.impressions', op: '>', val: 0 },
    {
      'ad_group_ad.ad.type': [enums.AdType.TEXT_AD, enums.AdType.EXPANDED_TEXT_AD],
    },
  ],
  from_date: '2018-02-25',
  to_date: '2019-03-01',
  order_by: 'metrics.impressions',
  sort_order: 'DESC',
  limit: 3,
})

// result rows
;[
  {
    ad_group: { resource_name: 'customers/3827277046/adGroups/45808681353', id: 45808681353 },
    ad_group_ad: {
      resource_name: 'customers/3827277046/adGroupAds/45808681353~266534257097',
      ad: { expanded_text_ad: { headline_part_1: 'best ad ever' }, id: 266534257097 },
    },
    metrics: { impressions: 1473 },
  },
  {
    ad_group: { resource_name: 'customers/3827277046/adGroups/45808681353', id: 45808681353 },
    ad_group_ad: {
      resource_name: 'customers/3827277046/adGroupAds/45808681353~304364243717',
      ad: { expanded_text_ad: { headline_part_1: 'next best ad' }, id: 304364243717 },
    },
    metrics: { impressions: 959 },
  },
  {
    ad_group: { resource_name: 'customers/3827277046/adGroups/69639056868', id: 69639056868 },
    ad_group_ad: {
      resource_name: 'customers/3827277046/adGroupAds/69639056868~307847364192',
      ad: { text_ad: { headline: 'pretty okay ad i guess' }, id: 307847364192 },
    },
    metrics: { impressions: 533 },
  },
]

// Constraint shorthands
constraints = [
  // clicks > 0, with no shorthand
  { key: 'metrics.clicks', op: '>', val: 0 },
  // campaign.name = "my campaign", with object shorthand for "="
  { 'campaign.name': '"my campaign"' },
  // campaign.status = "PAUSED", with object shorthand for "=" on enum
  { 'campaign.status': enums.CampaignStatus.PAUSED },
  // campaign.status IN ("PAUSED", "ENABLED"), with array shorthand for "IN"
  { 'campaign.status': [enums.CampaignStatus.PAUSED, enums.CampaignStatus.ENABLED] },
]

// If all constraints are using "=" or "IN", the whole contraints key can be an object instead of an array.
constraints = {
  'campaign.name': '"my campaign"',
  'campaign.status': [enums.CampaignStatus.PAUSED, enums.CampaignStatus.ENABLED],
}

Mutate several of different resource types in one call

The customer.mutateResources(resources_array) method takes an array of operations, where each operation is mutation to a resource, performs all of these mutations in sequence. By default, a call to customer.mutateResources() is atomic -- either all operations succeed or everything is rolled back.

Arguments

operations required, array

An array of operations. Each operation looks just like a resource with a few extra keys. They are of the form:
- _resource: string, required
  
  The resource type of this operation, such as Campaign or AdGroupAd. All mutable core resources are valid. This string is in TitleCase format.
- _operation: string, optional
  
  The mutation type of this operation. Can be create, update, or delete. Defaults to create.
- resource_name string
  
  The resource_name of the resource you are operating on. Required for update and deleteoperations, optional for create operations. When creating a resource, if you need to reference this resource in a future operation, use a negative integer as an ID, such as -1.
- (other_fields)
  
  Any other fields valid for this resource, such as name.
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
  
  When false, a single failure in the array of operations will cause the whole sequence to be rolled back. When true, the system will attempt to perform the next operations. 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.

const response = await customer.mutateResources([
	// Create new budget
	{
		_resource: 'CampaignBudget',
		_operation: 'create',
		resource_name: 'customers/3827277046/campaignBudgets/-1',
		name: 'My new budget',
		amount_micros: 3000000,
		explicitly_shared: true,
	},
	// Update campaign to use the new budget and have a new name
	{
		_resource: 'Campaign',
		_operation: 'update',
		name: 'New name for my campaign with a new budget'
		resource_name: 'customers/3827277046/campaigns/456456456',
		campaign_budget: 'customers/3827277046/campaignBudgets/-1',
	},
	// Delete old budget
	{
		_resource: 'CampaignBudget',
		_operation: 'delete',
		resource_name: 'customers/3827277046/campaignBudgets/123123',
	},
])

{
	results : [
		'customers/3827277046/campaignBudgets/265265547' // created
		'customers/3827277046/campaigns/456456456' // updated
		'customers/3827277046/campaignBugets/123123' // deleted
	],
	partial_failure_error : null,
	request: { /* your request object */ }
}

CustomerClient

The CustomerClient object

Fields

client_customer string

Output only. The resource name of the client-customer which is linked to the given customer. Read only.

currency_code string

Output only. Currency code (e.g. 'USD', 'EUR') for the client. Read only.

descriptive_name string

Output only. Descriptive name for the client. Read only.

hidden boolean

Output only. Specifies whether this is a hidden account. Read only.

id int64

Output only. The ID of the client customer. Read only.

level int64

Output only. Distance between given customer and client. For self link, the level value will be 0. Read only.

manager boolean

Output only. Identifies if the client is a manager. Read only.

resource_name string

Output only. The resource name of the customer client. CustomerClient resource names have the form: customers/{customer_id}/customerClients/{client_customer_id}

test_account boolean

Output only. Identifies if the client is a test account. Read only.

time_zone string

Output only. Common Locale Data Repository (CLDR) string representation of the time zone of the client, e.g. America/Los_Angeles. Read only.

// Example CustomerClient
const customer_client = {
  client_customer: 'customers/9262111890',
  currency_code: 'EUR',
  descriptive_name: 'My customer client',
  hidden: false,
  id: 9262111890,
  level: 0,
  manager: false,
  resource_name: 'customers/9262111890/customerClients/9262111890',
  test_account: true,
  time_zone: 'Europe/London',
}

Get a CustomerClient

The customer.customerClients.get(resource_name) method returns the CustomerClient identified by a resource_name.

Arguments

resource_name required

The resource_name of that CustomerClient

Returns

Returns that CustomerClient as an object.

// Getting the entity
let result = await customer.customerClients.get('customers/9262111890/customerClients/9262111890')

// Example result
;({
  client_customer: 'customers/9262111890',
  currency_code: 'EUR',
  descriptive_name: 'My customer client',
  hidden: false,
  id: 9262111890,
  level: 0,
  manager: false,
  resource_name: 'customers/9262111890/customerClients/9262111890',
  test_account: true,
  time_zone: 'Europe/London',
})

List every instance of CustomerClient

The customer.customerClients.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 CustomerClient.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.customerClients.list({
  constraints: [
    {
      key: 'customer_client.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'customer_client.some_field.sub_field',
})

// Example result
;[
  {
    customer_client: {
      client_customer: 'customers/9262111890',
      currency_code: 'EUR',
      descriptive_name: 'My customer client',
      hidden: false,
      id: 9262111890,
      level: 0,
      manager: false,
      resource_name: 'customers/9262111890/customerClients/9262111890',
      test_account: true,
      time_zone: 'Europe/London',
    },
    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',
    },
  },
]

CustomerClientLink

The CustomerClientLink object

Fields

client_customer string

Immutable. The client customer linked to this customer.

hidden boolean

The visibility of the link. Users can choose whether or not to see hidden links in the AdWords UI. Default value is false

manager_link_id int64

Output only. This is uniquely identifies a customer client link. Read only.

resource_name string

Immutable. Name of the resource. CustomerClientLink resource names have the form: customers/{customer_id}/customerClientLinks/{client_customer_id}~{manager_link_id}

status enum

This is the status of the link between client and manager.

// Example CustomerClientLink
const customer_client_link = /* Todo: add example get() return here */

Get a CustomerClientLink

The customer.customerClientLinks.get(resource_name) method returns the CustomerClientLink identified by a resource_name.

Arguments

resource_name required

The resource_name of that CustomerClientLink

Returns

Returns that CustomerClientLink as an object.

// Getting the entity
let result = await customer.customerClientLinks.get('customers/1234567890/customerClientLinks/123123123')

// Example result
(/* Todo: add example get() return here */)

List every instance of CustomerClientLink

The customer.customerClientLinks.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 CustomerClientLink.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.customerClientLinks.list({
  constraints: [
    {
      key: 'customer_client_link.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'customer_client_link.some_field.sub_field',
})

// Example result
;[
  /* Todo: add example list() return here */
]

Create a CustomerClientLink

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.customerClientLinks.create([customer_client_link, other_customer_client_link], {
  validate_only: true,
})

// Example result
{
	results : ['customers/1234567890/customerClientLinks/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CustomerClientLink

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

Arguments

entity required

The CustomerClientLink 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 customer_client_link = {
  resource_name: 'customers/1234567890/customerClientLinks/123123123', // 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.customerClientLinks.update(customer_client_link)

// Passing in an array of entities to update, validating only
const result = await customer.customerClientLinks.update([customer_client_link, other_customer_client_link], {
  validate_only: true,
})

// Example result
{
	results : ['customers/1234567890/customerClientLinks/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CustomerClientLink

The customer.customerClientLinks.delete(resource_name) sets the status field of a CustomerClientLink 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 CustomerClientLink

Returns

Nothing

// Deleting the entity

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

CustomerExtensionSetting

The CustomerExtensionSetting object

Fields

device enum

The device for which the extensions will serve. Optional.

extension_feed_items array of strings

The resource names of the extension feed items to serve under the customer. ExtensionFeedItem resource names have the form: customers/{customer_id}/extensionFeedItems/{feed_item_id}

extension_type enum

Immutable. The extension type of the customer extension setting.

resource_name string

Immutable. The resource name of the customer extension setting. CustomerExtensionSetting resource names have the form: customers/{customer_id}/customerExtensionSettings/{extension_type}

// Example CustomerExtensionSetting
const customer_extension_setting = {
  device: 0,
  extension_feed_items: ['customers/9262111890/extensionFeedItems/51842375274'],
  extension_type: 11,
  resource_name: 'customers/9262111890/customerExtensionSettings/STRUCTURED_SNIPPET',
}

Get a CustomerExtensionSetting

The customer.customerExtensionSettings.get(resource_name) method returns the CustomerExtensionSetting identified by a resource_name.

Arguments

resource_name required

The resource_name of that CustomerExtensionSetting

Returns

Returns that CustomerExtensionSetting as an object.

// Getting the entity
let result = await customer.customerExtensionSettings.get(
  'customers/9262111890/customerExtensionSettings/STRUCTURED_SNIPPET'
)

// Example result
;({
  device: 0,
  extension_feed_items: ['customers/9262111890/extensionFeedItems/51842375274'],
  extension_type: 11,
  resource_name: 'customers/9262111890/customerExtensionSettings/STRUCTURED_SNIPPET',
})

List every instance of CustomerExtensionSetting

The customer.customerExtensionSettings.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 CustomerExtensionSetting.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.customerExtensionSettings.list({
  constraints: [
    {
      key: 'customer_extension_setting.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'customer_extension_setting.some_field.sub_field',
})

// Example result
;[
  {
    customer_extension_setting: {
      device: 0,
      extension_feed_items: ['customers/9262111890/extensionFeedItems/51842375274'],
      extension_type: 11,
      resource_name: 'customers/9262111890/customerExtensionSettings/STRUCTURED_SNIPPET',
    },
    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 a CustomerExtensionSetting

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.customerExtensionSettings.create(
  [customer_extension_setting, other_customer_extension_setting],
  {
    validate_only: true,
  }
)

// Example result
{
	results : ['customers/9262111890/customerExtensionSettings/STRUCTURED_SNIPPET'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CustomerExtensionSetting

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

Arguments

entity required

The CustomerExtensionSetting 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 customer_extension_setting = {
  resource_name: 'customers/9262111890/customerExtensionSettings/STRUCTURED_SNIPPET', // 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.customerExtensionSettings.update(customer_extension_setting)

// Passing in an array of entities to update, validating only
const result = await customer.customerExtensionSettings.update(
  [customer_extension_setting, other_customer_extension_setting],
  {
    validate_only: true,
  }
)

// Example result
{
	results : ['customers/9262111890/customerExtensionSettings/STRUCTURED_SNIPPET'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CustomerExtensionSetting

The customer.customerExtensionSettings.delete(resource_name) sets the status field of a CustomerExtensionSetting 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 CustomerExtensionSetting

Returns

Nothing

// Deleting the entity

await customer.customerExtensionSettings.delete('customers/9262111890/customerExtensionSettings/STRUCTURED_SNIPPET')

CustomerFeed

The CustomerFeed object

Fields

feed string

Immutable. The feed being linked to the customer.

matching_function object

Matching function associated with the CustomerFeed. The matching function is used to filter the set of feed items selected. Required.

placeholder_types array of strings

Indicates which placeholder types the feed may populate under the connected customer. Required.

resource_name string

Immutable. The resource name of the customer feed. Customer feed resource names have the form: customers/{customer_id}/customerFeeds/{feed_id}

status enum

Output only. Status of the customer feed. This field is read-only.

// Example CustomerFeed
const customer_feed = {
  feed: 'customers/9262111890/feeds/82896692',
  matching_function: {
    function_string: 'EQUALS(FEED_ITEM_ID,51840594005)',
    left_operands: [{ request_context_operand: { context_type: 2 } }],
    operator: 4,
    right_operands: [{ constant_operand: { long_value: 51840594005 } }],
  },
  placeholder_types: [],
  resource_name: 'customers/9262111890/customerFeeds/82896692',
  status: 2,
}

Get a CustomerFeed

The customer.customerFeeds.get(resource_name) method returns the CustomerFeed identified by a resource_name.

Arguments

resource_name required

The resource_name of that CustomerFeed

Returns

Returns that CustomerFeed as an object.

// Getting the entity
let result = await customer.customerFeeds.get('customers/9262111890/customerFeeds/82896692')

// Example result
;({
  feed: 'customers/9262111890/feeds/82896692',
  matching_function: {
    function_string: 'EQUALS(FEED_ITEM_ID,51840594005)',
    left_operands: [{ request_context_operand: { context_type: 2 } }],
    operator: 4,
    right_operands: [{ constant_operand: { long_value: 51840594005 } }],
  },
  placeholder_types: [],
  resource_name: 'customers/9262111890/customerFeeds/82896692',
  status: 2,
})

List every instance of CustomerFeed

The customer.customerFeeds.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 CustomerFeed.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.customerFeeds.list({
  constraints: [
    {
      key: 'customer_feed.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'customer_feed.some_field.sub_field',
})

// Example result
;[
  {
    customer_feed: {
      feed: 'customers/9262111890/feeds/82896692',
      matching_function: {
        function_string: 'EQUALS(FEED_ITEM_ID,51840594005)',
        left_operands: [{ request_context_operand: { context_type: 2 } }],
        operator: 4,
        right_operands: [{ constant_operand: { long_value: 51840594005 } }],
      },
      placeholder_types: [],
      resource_name: 'customers/9262111890/customerFeeds/82896692',
      status: 2,
    },
    feed: {
      attributes: [
        { id: 1, name: 'SitelinkName', type: 4, is_part_of_key: false },
        { id: 2, name: 'SitelinkUrl', type: 6, is_part_of_key: false },
        { id: 3, name: 'SitelinkDescription1', type: 4, is_part_of_key: false },
        { id: 4, name: 'SitelinkDescription2', type: 4, is_part_of_key: false },
        { id: 5, name: 'SitelinkFinalUrls', type: 12, is_part_of_key: false },
        { id: 6, name: 'SitelinkFinalMobileUrls', type: 12, is_part_of_key: false },
        { id: 7, name: 'SitelinkTrackingUrl', type: 6, is_part_of_key: false },
        { id: 8, name: 'SitelinkFinalUrlSuffix', type: 4, is_part_of_key: false },
      ],
      id: 82896692,
      name: 'My feed',
      origin: 3,
      resource_name: 'customers/9262111890/feeds/82896692',
      status: 2,
    },
    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 a CustomerFeed

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.customerFeeds.create([customer_feed, other_customer_feed], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/customerFeeds/82896692'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CustomerFeed

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

Arguments

entity required

The CustomerFeed 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 customer_feed = {
  resource_name: 'customers/9262111890/customerFeeds/82896692', // 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.customerFeeds.update(customer_feed)

// Passing in an array of entities to update, validating only
const result = await customer.customerFeeds.update([customer_feed, other_customer_feed], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/customerFeeds/82896692'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CustomerFeed

The customer.customerFeeds.delete(resource_name) sets the status field of a CustomerFeed 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 CustomerFeed

Returns

Nothing

// Deleting the entity

await customer.customerFeeds.delete('customers/9262111890/customerFeeds/82896692')

CustomerLabel

The CustomerLabel object

Fields

customer string

Output only. The resource name of the customer to which the label is attached. Read only.

label string

Output only. The resource name of the label assigned to the customer. Note: the Customer ID portion of the label resource name is not validated when creating a new CustomerLabel.

resource_name string

Immutable. Name of the resource. Customer label resource names have the form: customers/{customer_id}/customerLabels/{label_id}

// Example CustomerLabel
const customer_label = /* Todo: add example get() return here */

Get a CustomerLabel

The customer.customerLabels.get(resource_name) method returns the CustomerLabel identified by a resource_name.

Arguments

resource_name required

The resource_name of that CustomerLabel

Returns

Returns that CustomerLabel as an object.

// Getting the entity
let result = await customer.customerLabels.get('customers/1234567890/customerLabels/123123123')

// Example result
(/* Todo: add example get() return here */)

List every instance of CustomerLabel

The customer.customerLabels.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 CustomerLabel.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.customerLabels.list({
  constraints: [
    {
      key: 'customer_label.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'customer_label.some_field.sub_field',
})

// Example result
;[
  /* Todo: add example list() return here */
]

Create a CustomerLabel

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.customerLabels.create([customer_label, other_customer_label], {
  validate_only: true,
})

// Example result
{
	results : ['customers/1234567890/customerLabels/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CustomerLabel

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

Arguments

entity required

The CustomerLabel 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 customer_label = {
  resource_name: 'customers/1234567890/customerLabels/123123123', // 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.customerLabels.update(customer_label)

// Passing in an array of entities to update, validating only
const result = await customer.customerLabels.update([customer_label, other_customer_label], {
  validate_only: true,
})

// Example result
{
	results : ['customers/1234567890/customerLabels/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CustomerLabel

The customer.customerLabels.delete(resource_name) sets the status field of a CustomerLabel 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 CustomerLabel

Returns

Nothing

// Deleting the entity

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

CustomerManagerLink

The CustomerManagerLink object

Fields

manager_customer string

Output only. The manager customer linked to the customer.

manager_link_id int64

Output only. ID of the customer-manager link. This field is read only.

resource_name string

Immutable. Name of the resource. CustomerManagerLink resource names have the form: customers/{customer_id}/customerManagerLinks/{manager_customer_id}~{manager_link_id}

status enum

Status of the link between the customer and the manager.

// Example CustomerManagerLink
const customer_manager_link = {
  manager_customer: 'customers/6141549892',
  manager_link_id: 121665495,
  resource_name: 'customers/9262111890/customerManagerLinks/6141549892~121665495',
  status: 2,
}

Get a CustomerManagerLink

The customer.customerManagerLinks.get(resource_name) method returns the CustomerManagerLink identified by a resource_name.

Arguments

resource_name required

The resource_name of that CustomerManagerLink

Returns

Returns that CustomerManagerLink as an object.

// Getting the entity
let result = await customer.customerManagerLinks.get('customers/9262111890/customerManagerLinks/6141549892~121665495')

// Example result
;({
  manager_customer: 'customers/6141549892',
  manager_link_id: 121665495,
  resource_name: 'customers/9262111890/customerManagerLinks/6141549892~121665495',
  status: 2,
})

List every instance of CustomerManagerLink

The customer.customerManagerLinks.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 CustomerManagerLink.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.customerManagerLinks.list({
  constraints: [
    {
      key: 'customer_manager_link.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'customer_manager_link.some_field.sub_field',
})

// Example result
;[
  {
    customer_manager_link: {
      manager_customer: 'customers/6141549892',
      manager_link_id: 121665495,
      resource_name: 'customers/9262111890/customerManagerLinks/6141549892~121665495',
      status: 2,
    },
    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 a CustomerManagerLink

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.customerManagerLinks.create([customer_manager_link, other_customer_manager_link], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/customerManagerLinks/6141549892~121665495'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CustomerManagerLink

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

Arguments

entity required

The CustomerManagerLink 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 customer_manager_link = {
  resource_name: 'customers/9262111890/customerManagerLinks/6141549892~121665495', // 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.customerManagerLinks.update(customer_manager_link)

// Passing in an array of entities to update, validating only
const result = await customer.customerManagerLinks.update([customer_manager_link, other_customer_manager_link], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/customerManagerLinks/6141549892~121665495'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CustomerManagerLink

The customer.customerManagerLinks.delete(resource_name) sets the status field of a CustomerManagerLink 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 CustomerManagerLink

Returns

Nothing

// Deleting the entity

await customer.customerManagerLinks.delete('customers/9262111890/customerManagerLinks/6141549892~121665495')

CustomerNegativeCriterion

The CustomerNegativeCriterion object

Fields

ONE of the following:

content_label object
Immutable. ContentLabel.
Child Fields
type enum
Content label type, required for CREATE operations.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
SEXUALLY_SUGGESTIVE (2)
Sexually suggestive content.
BELOW_THE_FOLD (3)
Below the fold placement.
PARKED_DOMAIN (4)
Parked domain.
JUVENILE (6)
Juvenile, gross & bizarre content.
PROFANITY (7)
Profanity & rough language.
TRAGEDY (8)
Death & tragedy.
VIDEO (9)
Video.
VIDEO_RATING_DV_G (10)
Content rating: G.
VIDEO_RATING_DV_PG (11)
Content rating: PG.
VIDEO_RATING_DV_T (12)
Content rating: T.
VIDEO_RATING_DV_MA (13)
Content rating: MA.
VIDEO_NOT_YET_RATED (14)
Content rating: not yet rated.
EMBEDDED_VIDEO (15)
Embedded video.
LIVE_STREAMING_VIDEO (16)
Live streaming video.
SOCIAL_ISSUES (17)
Sensitive social issues.
mobile_app_category object
Immutable. MobileAppCategory.
Child Fields
mobile_app_category_constant string
The mobile app category constant resource name.
mobile_application object
Immutable. MobileApplication.
Child Fields
app_id string
A string that uniquely identifies a mobile application to Google Ads API. The format of this string is "{platform}-{platform_native_id}", where platform is "1" for iOS apps and "2" for Android apps, and where platform_native_id is the mobile application identifier native to the corresponding platform. For iOS, this native identifier is the 9 digit string that appears at the end of an App Store URL (e.g., "476943146" for "Flood-It! 2" whose App Store link is "http://itunes.apple.com/us/app/flood-it!-2/id476943146"). For Android, this native identifier is the application's package name (e.g., "com.labpixies.colordrips" for "Color Drips" given Google Play link "https://play.google.com/store/apps/details?id=com.labpixies.colordrips"). A well formed app id for Google Ads API would thus be "1-476943146" for iOS and "2-com.labpixies.colordrips" for Android. This field is required and must be set in CREATE operations.
name string
Name of this mobile application.
placement object
Immutable. Placement.
Child Fields
url string
URL of the placement. For example, "http://www.domain.com".
youtube_channel object
Immutable. YouTube Channel.
Child Fields
channel_id string
The YouTube uploader channel id or the channel code of a YouTube channel.
youtube_video object
Immutable. YouTube Video.
Child Fields
video_id string
YouTube video id as it appears on the YouTube watch page.

id int64

Output only. The ID of the criterion.

resource_name string

Immutable. The resource name of the customer negative criterion. Customer negative criterion resource names have the form: customers/{customer_id}/customerNegativeCriteria/{criterion_id}

type enum

Output only. The type of the criterion.

// Example CustomerNegativeCriterion
const customer_negative_criterion = {
  id: 61276056204,
  mobile_application: {
    app_id: '2-com.duolingo',
    name: 'Mobile App: Duolingo: Learn Languages Free (Google Play), by Duolingo',
  },
  resource_name: 'customers/3827277046/customerNegativeCriteria/61276056204',
  type: 5,
}

Get a CustomerNegativeCriterion

The customer.customerNegativeCriteria.get(resource_name) method returns the CustomerNegativeCriterion identified by a resource_name.

Arguments

resource_name required

The resource_name of that CustomerNegativeCriterion

Returns

Returns that CustomerNegativeCriterion as an object.

// Getting the entity
let result = await customer.customerNegativeCriteria.get('customers/3827277046/customerNegativeCriteria/61276056204')

// Example result
;({
  id: 61276056204,
  mobile_application: {
    app_id: '2-com.duolingo',
    name: 'Mobile App: Duolingo: Learn Languages Free (Google Play), by Duolingo',
  },
  resource_name: 'customers/3827277046/customerNegativeCriteria/61276056204',
  type: 5,
})

List every instance of CustomerNegativeCriterion

The customer.customerNegativeCriteria.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 CustomerNegativeCriterion.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.customerNegativeCriteria.list({
  constraints: [
    {
      key: 'customer_negative_criterion.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'customer_negative_criterion.some_field.sub_field',
})

// Example result
;[
  {
    customer_negative_criterion: {
      id: 61276056204,
      mobile_application: {
        app_id: '2-com.duolingo',
        name: 'Mobile App: Duolingo: Learn Languages Free (Google Play), by Duolingo',
      },
      resource_name: 'customers/3827277046/customerNegativeCriteria/61276056204',
      type: 5,
    },
    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 a CustomerNegativeCriterion

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.customerNegativeCriteria.create(
  [customer_negative_criterion, other_customer_negative_criterion],
  {
    validate_only: true,
  }
)

// Example result
{
	results : ['customers/3827277046/customerNegativeCriteria/61276056204'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a CustomerNegativeCriterion

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

Arguments

entity required

The CustomerNegativeCriterion 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 customer_negative_criterion = {
  resource_name: 'customers/3827277046/customerNegativeCriteria/61276056204', // 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.customerNegativeCriteria.update(customer_negative_criterion)

// Passing in an array of entities to update, validating only
const result = await customer.customerNegativeCriteria.update(
  [customer_negative_criterion, other_customer_negative_criterion],
  {
    validate_only: true,
  }
)

// Example result
{
	results : ['customers/3827277046/customerNegativeCriteria/61276056204'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a CustomerNegativeCriterion

The customer.customerNegativeCriteria.delete(resource_name) sets the status field of a CustomerNegativeCriterion 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 CustomerNegativeCriterion

Returns

Nothing

// Deleting the entity

await customer.customerNegativeCriteria.delete('customers/3827277046/customerNegativeCriteria/61276056204')

DomainCategory

The DomainCategory object

Fields

campaign string

Output only. The campaign this category is recommended for.

category string

Output only. Recommended category for the website domain. e.g. if you have a website about electronics, the categories could be "cameras", "televisions", etc.

category_rank int64

Output only. The position of this category in the set of categories. Lower numbers indicate a better match for the domain. null indicates not recommended.

coverage_fraction double

Output only. Fraction of pages on your site that this category matches.

domain string

Output only. The domain for the website. The domain can be specified in the DynamicSearchAdsSetting required for dynamic search ads.

has_children boolean

Output only. Indicates whether this category has sub-categories.

language_code string

Output only. The language code specifying the language of the website. e.g. "en" for English. The language can be specified in the DynamicSearchAdsSetting required for dynamic search ads. This is the language of the pages from your website that you want Google Ads to find, create ads for, and match searches with.

recommended_cpc_bid_micros int64

Output only. The recommended cost per click for the category.

resource_name string

Output only. The resource name of the domain category. Domain category resource names have the form: customers/{customer_id}/domainCategories/{campaign_id}~{category_base64}~{language_code}

// Example DomainCategory
const domain_category = {
  campaign: 'customers/3827277046/campaigns/1398201241',
  category: 'landing pages from your standard ad groups',
  category_rank: 0,
  coverage_fraction: 2.7777777777777777,
  domain: 'opteo.com',
  has_children: false,
  language_code: 'en',
  recommended_cpc_bid_micros: 6626250,
  resource_name:
    'customers/3827277046/domainCategories/1398201241~bGFuZGluZyBwYWdlcyBmcm9tIHlvdXIgc3RhbmRhcmQgYWQgZ3JvdXBz~en',
}

Get a DomainCategory

The customer.domainCategories.get(resource_name) method returns the DomainCategory identified by a resource_name.

Arguments

resource_name required

The resource_name of that DomainCategory

Returns

Returns that DomainCategory as an object.

// Getting the entity
let result = await customer.domainCategories.get(
  'customers/3827277046/domainCategories/1398201241~bGFuZGluZyBwYWdlcyBmcm9tIHlvdXIgc3RhbmRhcmQgYWQgZ3JvdXBz~en'
)

// Example result
;({
  campaign: 'customers/3827277046/campaigns/1398201241',
  category: 'landing pages from your standard ad groups',
  category_rank: 0,
  coverage_fraction: 2.7777777777777777,
  domain: 'opteo.com',
  has_children: false,
  language_code: 'en',
  recommended_cpc_bid_micros: 6626250,
  resource_name:
    'customers/3827277046/domainCategories/1398201241~bGFuZGluZyBwYWdlcyBmcm9tIHlvdXIgc3RhbmRhcmQgYWQgZ3JvdXBz~en',
})

List every instance of DomainCategory

The customer.domainCategories.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 DomainCategory.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.domainCategories.list({
  constraints: [
    {
      key: 'domain_category.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'domain_category.some_field.sub_field',
})

// Example result
;[
  {
    domain_category: {
      campaign: 'customers/3827277046/campaigns/1398201241',
      category: 'landing pages from your standard ad groups',
      category_rank: 0,
      coverage_fraction: 2.7777777777777777,
      domain: 'opteo.com',
      has_children: false,
      language_code: 'en',
      recommended_cpc_bid_micros: 6626250,
      resource_name:
        'customers/3827277046/domainCategories/1398201241~bGFuZGluZyBwYWdlcyBmcm9tIHlvdXIgc3RhbmRhcmQgYWQgZ3JvdXBz~en',
    },
    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}',
    },
  },
]

ExtensionFeedItem

The ExtensionFeedItem object

Fields

ONE of the following:

affiliate_location_feed_item object
Output only. Affiliate location extension. Feed locations are populated by Google Ads based on a chain ID. This field is read-only.
Child Fields
address_line1 string
Line 1 of the business address.
address_line2 string
Line 2 of the business address.
business_name string
The name of the business.
chain_id int64
Id of the retail chain that is advertised as a seller of your product.
chain_name string
Name of chain.
city string
City of the business address.
country_code string
Country code of the business address.
phone_number string
Phone number of the business.
postal_code string
Postal code of the business address.
province string
Province of the business address.
app_feed_item object
App extension.
Child Fields
app_id string
The store-specific ID for the target application. This string must not be empty.
app_store enum
The application store that the target application belongs to. This field is required.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
APPLE_ITUNES (2)
Apple iTunes.
GOOGLE_PLAY (3)
Google Play.
final_mobile_urls array of strings
A list of possible final mobile URLs after all cross domain redirects.
final_url_suffix string
URL template for appending params to landing page URLs served with parallel tracking.
final_urls array of strings
A list of possible final URLs after all cross domain redirects. This list must not be empty.
link_text string
The visible text displayed when the link is rendered in an ad. This string must not be empty, and the length of this string should be between 1 and 25, inclusive.
tracking_url_template string
URL template for constructing a tracking URL. Default value is "{lpurl}".
url_custom_parameters array of objects
A list of mappings to be used for substituting URL custom parameter tags in the tracking_url_template, final_urls, and/or final_mobile_urls.
key string
The key matching the parameter tag name.
value string
The value to be substituted.
call_feed_item object
Call extension.
Child Fields
call_conversion_action string
The conversion action to attribute a call conversion to. If not set a default conversion action is used. This field only has effect if call_tracking_enabled is set to true. Otherwise this field is ignored.
call_conversion_reporting_state enum
Enum value that indicates whether this call extension uses its own call conversion setting (or just have call conversion disabled), or following the account level setting.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
DISABLED (2)
Call conversion action is disabled.
USE_ACCOUNT_LEVEL_CALL_CONVERSION_ACTION (3)
Call conversion action will use call conversion type set at the account level.
USE_RESOURCE_LEVEL_CALL_CONVERSION_ACTION (4)
Call conversion action will use call conversion type set at the resource (call only ads/call extensions) level.
call_conversion_tracking_disabled boolean
If true, disable call conversion tracking. call_conversion_action should not be set if this is true. Optional.
call_tracking_enabled boolean
Indicates whether call tracking is enabled. By default, call tracking is not enabled.
country_code string
Uppercase two-letter country code of the advertiser's phone number. This string must not be empty.
phone_number string
The advertiser's phone number to append to the ad. This string must not be empty.
callout_feed_item object
Callout extension.
Child Fields
callout_text string
The callout text. The length of this string should be between 1 and 25, inclusive.
hotel_callout_feed_item object
Hotel Callout extension.
Child Fields
language_code string
The language of the hotel callout text. IETF BCP 47 compliant language code.
text string
The callout text. The length of this string should be between 1 and 25, inclusive.
location_feed_item object
Output only. Location extension. Locations are synced from a GMB account into a feed. This field is read-only.
Child Fields
address_line1 string
Line 1 of the business address.
address_line2 string
Line 2 of the business address.
business_name string
The name of the business.
city string
City of the business address.
country_code string
Country code of the business address.
phone_number string
Phone number of the business.
postal_code string
Postal code of the business address.
province string
Province of the business address.
price_feed_item object
Price extension.
Child Fields
final_url_suffix string
URL template for appending params to landing page URLs served with parallel tracking.
language_code string
The code of the language used for this price extension.
price_offerings array of objects
The price offerings in this price extension.
description string
Description text of this offer.
final_mobile_urls array of strings
A list of possible final mobile URLs after all cross domain redirects.
final_urls array of strings
A list of possible final URLs after all cross domain redirects.
header string
Header text of this offer.
price object
Price value of this offer.
amount_micros int64
Amount in micros. One million is equivalent to one unit.
currency_code string
Three-character ISO 4217 currency code.
unit enum
Price unit for this offer.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
PER_HOUR (2)
Per hour.
PER_DAY (3)
Per day.
PER_WEEK (4)
Per week.
PER_MONTH (5)
Per month.
PER_YEAR (6)
Per year.
PER_NIGHT (7)
Per night.
price_qualifier enum
Price qualifier for all offers of this price extension.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
FROM (2)
'From' qualifier for the price.
UP_TO (3)
'Up to' qualifier for the price.
AVERAGE (4)
'Average' qualifier for the price.
tracking_url_template string
Tracking URL template for all offers of this price extension.
type enum
Price extension type of this extension.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
BRANDS (2)
The type for showing a list of brands.
EVENTS (3)
The type for showing a list of events.
LOCATIONS (4)
The type for showing locations relevant to your business.
NEIGHBORHOODS (5)
The type for showing sub-regions or districts within a city or region.
PRODUCT_CATEGORIES (6)
The type for showing a collection of product categories.
PRODUCT_TIERS (7)
The type for showing a collection of related product tiers.
SERVICES (8)
The type for showing a collection of services offered by your business.
SERVICE_CATEGORIES (9)
The type for showing a collection of service categories.
SERVICE_TIERS (10)
The type for showing a collection of related service tiers.
promotion_feed_item object
Promotion extension.
Child Fields
discount_modifier enum
Enum that modifies the qualification of the discount.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
UP_TO (2)
'Up to'.
final_mobile_urls array of strings
A list of possible final mobile URLs after all cross domain redirects.
final_url_suffix string
URL template for appending params to landing page URLs served with parallel tracking.
final_urls array of strings
A list of possible final URLs after all cross domain redirects. This field is required.
language_code string
The language of the promotion. Represented as BCP 47 language tag.
money_amount_off object
Money amount off for discount in the promotion. Either this or percent_off is required.
amount_micros int64
Amount in micros. One million is equivalent to one unit.
currency_code string
Three-character ISO 4217 currency code.
occasion enum
The occasion the promotion was intended for. If an occasion is set, the redemption window will need to fall within the date range associated with the occasion.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
NEW_YEARS (2)
New Year's.
CHINESE_NEW_YEAR (3)
Chinese New Year.
VALENTINES_DAY (4)
Valentine's Day.
EASTER (5)
Easter.
MOTHERS_DAY (6)
Mother's Day.
FATHERS_DAY (7)
Father's Day.
LABOR_DAY (8)
Labor Day.
BACK_TO_SCHOOL (9)
Back To School.
HALLOWEEN (10)
Halloween.
BLACK_FRIDAY (11)
Black Friday.
CYBER_MONDAY (12)
Cyber Monday.
CHRISTMAS (13)
Christmas.
BOXING_DAY (14)
Boxing Day.
INDEPENDENCE_DAY (15)
Independence Day in any country.
NATIONAL_DAY (16)
National Day in any country.
END_OF_SEASON (17)
End of any season.
WINTER_SALE (18)
Winter Sale.
SUMMER_SALE (19)
Summer sale.
FALL_SALE (20)
Fall Sale.
SPRING_SALE (21)
Spring Sale.
RAMADAN (22)
Ramadan.
EID_AL_FITR (23)
Eid al-Fitr.
EID_AL_ADHA (24)
Eid al-Adha.
SINGLES_DAY (25)
Singles Day.
WOMENS_DAY (26)
Women's Day.
HOLI (27)
Holi.
PARENTS_DAY (28)
Parent's Day.
ST_NICHOLAS_DAY (29)
St. Nicholas Day.
CARNIVAL (30)
Carnival.
EPIPHANY (31)
Epiphany, also known as Three Kings' Day.
ROSH_HASHANAH (32)
Rosh Hashanah.
PASSOVER (33)
Passover.
HANUKKAH (34)
Hanukkah.
DIWALI (35)
Diwali.
NAVRATRI (36)
Navratri.
SONGKRAN (37)
Available in Thai: Songkran.
YEAR_END_GIFT (38)
Available in Japanese: Year-end Gift.
orders_over_amount object
The amount the total order needs to be for the user to be eligible for the promotion.
amount_micros int64
Amount in micros. One million is equivalent to one unit.
currency_code string
Three-character ISO 4217 currency code.
percent_off int64
Percentage off discount in the promotion in micros. One million is equivalent to one percent. Either this or money_off_amount is required.
promotion_code string
A code the user should use in order to be eligible for the promotion.
promotion_end_date string
End date of when the promotion is eligible to be redeemed.
promotion_start_date string
Start date of when the promotion is eligible to be redeemed.
promotion_target string
A freeform description of what the promotion is targeting. This field is required.
tracking_url_template string
URL template for constructing a tracking URL.
url_custom_parameters array of objects
A list of mappings to be used for substituting URL custom parameter tags in the tracking_url_template, final_urls, and/or final_mobile_urls.
key string
The key matching the parameter tag name.
value string
The value to be substituted.
sitelink_feed_item object
Sitelink extension.
Child Fields
final_mobile_urls array of strings
A list of possible final mobile URLs after all cross domain redirects.
final_url_suffix string
Final URL suffix to be appended to landing page URLs served with parallel tracking.
final_urls array of strings
A list of possible final URLs after all cross domain redirects.
line1 string
First line of the description for the sitelink. If this value is set, line2 must also be set. The length of this string should be between 0 and 35, inclusive.
line2 string
Second line of the description for the sitelink. If this value is set, line1 must also be set. The length of this string should be between 0 and 35, inclusive.
link_text string
URL display text for the sitelink. The length of this string should be between 1 and 25, inclusive.
tracking_url_template string
URL template for constructing a tracking URL.
url_custom_parameters array of objects
A list of mappings to be used for substituting URL custom parameter tags in the tracking_url_template, final_urls, and/or final_mobile_urls.
key string
The key matching the parameter tag name.
value string
The value to be substituted.
structured_snippet_feed_item object
Structured snippet extension.
Child Fields
header string
The header of the snippet. This string must not be empty.
values array of strings
The values in the snippet. The maximum size of this collection is 10.
text_message_feed_item object
Text message extension.
Child Fields
business_name string
The business name to prepend to the message text. This field is required.
country_code string
Uppercase two-letter country code of the advertiser's phone number. This field is required.
extension_text string
The message text populated in the messaging app.
phone_number string
The advertiser's phone number the message will be sent to. Required.
text string
The text to show in the ad. This field is required.

ONE of the following:

targeted_ad_group string
The targeted ad group.
targeted_campaign string
The targeted campaign.

ad_schedules array of objects

List of non-overlapping schedules specifying all time intervals for which the feed item may serve. There can be a maximum of 6 schedules per day.

device enum

The targeted device.

end_date_time string

End time in which this feed item is no longer effective and will stop serving. The time is in the customer's time zone. The format is "YYYY-MM-DD HH:MM:SS". Examples: "2018-03-05 09:15:00" or "2018-02-01 14:34:30"

extension_type enum

Output only. The extension type of the extension feed item. This field is read-only.

id int64

Output only. The ID of this feed item. Read-only.

resource_name string

Immutable. The resource name of the extension feed item. Extension feed item resource names have the form: customers/{customer_id}/extensionFeedItems/{feed_item_id}

start_date_time string

Start time in which this feed item is effective and can begin serving. The time is in the customer's time zone. The format is "YYYY-MM-DD HH:MM:SS". Examples: "2018-03-05 09:15:00" or "2018-02-01 14:34:30"

status enum

Output only. Status of the feed item. This field is read-only.

targeted_geo_target_constant string

The targeted geo target constant.

targeted_keyword object

The targeted keyword.

// Example ExtensionFeedItem
const extension_feed_item = {
  ad_schedules: [],
  call_feed_item: {
    call_conversion_action: 'customers/3827277046/conversionActions/179',
    call_conversion_reporting_state: 4,
    call_conversion_tracking_disabled: false,
    call_tracking_enabled: true,
    country_code: 'GB',
    phone_number: '02035751125',
  },
  device: 0,
  extension_type: 4,
  id: 13882206517,
  resource_name: 'customers/3827277046/extensionFeedItems/13882206517',
  status: 2,
}

Get a ExtensionFeedItem

The customer.extensionFeedItems.get(resource_name) method returns the ExtensionFeedItem identified by a resource_name.

Arguments

resource_name required

The resource_name of that ExtensionFeedItem

Returns

Returns that ExtensionFeedItem as an object.

// Getting the entity
let result = await customer.extensionFeedItems.get('customers/3827277046/extensionFeedItems/13882206517')

// Example result
;({
  ad_schedules: [],
  call_feed_item: {
    call_conversion_action: 'customers/3827277046/conversionActions/179',
    call_conversion_reporting_state: 4,
    call_conversion_tracking_disabled: false,
    call_tracking_enabled: true,
    country_code: 'GB',
    phone_number: '02035751125',
  },
  device: 0,
  extension_type: 4,
  id: 13882206517,
  resource_name: 'customers/3827277046/extensionFeedItems/13882206517',
  status: 2,
})

List every instance of ExtensionFeedItem

The customer.extensionFeedItems.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 ExtensionFeedItem.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.extensionFeedItems.list({
  constraints: [
    {
      key: 'extension_feed_item.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'extension_feed_item.some_field.sub_field',
})

// Example result
;[
  {
    extension_feed_item: {
      ad_schedules: [],
      call_feed_item: {
        call_conversion_action: 'customers/3827277046/conversionActions/179',
        call_conversion_reporting_state: 4,
        call_conversion_tracking_disabled: false,
        call_tracking_enabled: true,
        country_code: 'GB',
        phone_number: '02035751125',
      },
      device: 0,
      extension_type: 4,
      id: 13882206517,
      resource_name: 'customers/3827277046/extensionFeedItems/13882206517',
      status: 2,
    },
    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 a ExtensionFeedItem

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.extensionFeedItems.create([extension_feed_item, other_extension_feed_item], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/extensionFeedItems/13882206517'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a ExtensionFeedItem

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

Arguments

entity required

The ExtensionFeedItem 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 extension_feed_item = {
  resource_name: 'customers/3827277046/extensionFeedItems/13882206517', // 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.extensionFeedItems.update(extension_feed_item)

// Passing in an array of entities to update, validating only
const result = await customer.extensionFeedItems.update([extension_feed_item, other_extension_feed_item], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/extensionFeedItems/13882206517'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a ExtensionFeedItem

The customer.extensionFeedItems.delete(resource_name) sets the status field of a ExtensionFeedItem 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 ExtensionFeedItem

Returns

Nothing

// Deleting the entity

await customer.extensionFeedItems.delete('customers/3827277046/extensionFeedItems/13882206517')

Feed

The Feed object

Fields

ONE of the following:

affiliate_location_feed_data object
Data used to configure an affiliate location feed populated with the specified chains.
Child Fields
chain_ids array of strings
The list of chains that the affiliate location feed will sync the locations from.
relationship_type enum
The relationship the chains have with the advertiser.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
GENERAL_RETAILER (2)
General retailer relationship.
places_location_feed_data object
Data used to configure a location feed populated from Google My Business Locations.
Child Fields
business_account_id string
Plus page ID of the managed business whose locations should be used. If this field is not set, then all businesses accessible by the user (specified by email_address) are used. This field is mutate-only and is not selectable.
business_name_filter string
Used to filter Google My Business listings by business name. If business_name_filter is set, only listings with a matching business name are candidates to be sync'd into FeedItems.
category_filters array of strings
Used to filter Google My Business listings by categories. If entries exist in category_filters, only listings that belong to any of the categories are candidates to be sync'd into FeedItems. If no entries exist in category_filters, then all listings are candidates for syncing.
email_address string
Email address of a Google My Business account or email address of a manager of the Google My Business account. Required.
label_filters array of strings
Used to filter Google My Business listings by labels. If entries exist in label_filters, only listings that has any of the labels set are candidates to be synchronized into FeedItems. If no entries exist in label_filters, then all listings are candidates for syncing.
oauth_info object
Immutable. Required authentication token (from OAuth API) for the email. This field can only be specified in a create request. All its subfields are not selectable.
http_authorization_header string
The HTTP authorization header used to obtain authorization.
http_method string
The HTTP method used to obtain authorization.
http_request_url string
The HTTP request URL used to obtain authorization.

attribute_operations array of objects

The list of operations changing the feed attributes. Attributes can only be added, not removed.

attributes array of objects

The Feed's attributes. Required on CREATE, unless system_feed_generation_data is provided, in which case Google Ads will update the feed with the correct attributes. Disallowed on UPDATE. Use attribute_operations to add new attributes.

id int64

Output only. The ID of the feed. This field is read-only.

name string

Immutable. Name of the feed. Required.

origin enum

Immutable. Specifies who manages the FeedAttributes for the Feed.

resource_name string

Immutable. The resource name of the feed. Feed resource names have the form: customers/{customer_id}/feeds/{feed_id}

status enum

Output only. Status of the feed. This field is read-only.

// Example Feed
const feed = {
  attributes: [
    { id: 1, name: 'SitelinkName', type: 4, is_part_of_key: false },
    { id: 2, name: 'SitelinkUrl', type: 6, is_part_of_key: false },
    { id: 3, name: 'SitelinkDescription1', type: 4, is_part_of_key: false },
    { id: 4, name: 'SitelinkDescription2', type: 4, is_part_of_key: false },
    { id: 5, name: 'SitelinkFinalUrls', type: 12, is_part_of_key: false },
    { id: 6, name: 'SitelinkFinalMobileUrls', type: 12, is_part_of_key: false },
    { id: 7, name: 'SitelinkTrackingUrl', type: 6, is_part_of_key: false },
    { id: 8, name: 'SitelinkFinalUrlSuffix', type: 4, is_part_of_key: false },
  ],
  id: 82896692,
  name: 'My feed',
  origin: 3,
  resource_name: 'customers/9262111890/feeds/82896692',
  status: 2,
}

Get a Feed

The customer.feeds.get(resource_name) method returns the Feed identified by a resource_name.

Arguments

resource_name required

The resource_name of that Feed

Returns

Returns that Feed as an object.

// Getting the entity
let result = await customer.feeds.get('customers/9262111890/feeds/82896692')

// Example result
;({
  attributes: [
    { id: 1, name: 'SitelinkName', type: 4, is_part_of_key: false },
    { id: 2, name: 'SitelinkUrl', type: 6, is_part_of_key: false },
    { id: 3, name: 'SitelinkDescription1', type: 4, is_part_of_key: false },
    { id: 4, name: 'SitelinkDescription2', type: 4, is_part_of_key: false },
    { id: 5, name: 'SitelinkFinalUrls', type: 12, is_part_of_key: false },
    { id: 6, name: 'SitelinkFinalMobileUrls', type: 12, is_part_of_key: false },
    { id: 7, name: 'SitelinkTrackingUrl', type: 6, is_part_of_key: false },
    { id: 8, name: 'SitelinkFinalUrlSuffix', type: 4, is_part_of_key: false },
  ],
  id: 82896692,
  name: 'My feed',
  origin: 3,
  resource_name: 'customers/9262111890/feeds/82896692',
  status: 2,
})

List every instance of Feed

The customer.feeds.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 Feed.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.feeds.list({
  constraints: [
    {
      key: 'feed.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'feed.some_field.sub_field',
})

// Example result
;[
  {
    feed: {
      attributes: [
        { id: 1, name: 'SitelinkName', type: 4, is_part_of_key: false },
        { id: 2, name: 'SitelinkUrl', type: 6, is_part_of_key: false },
        { id: 3, name: 'SitelinkDescription1', type: 4, is_part_of_key: false },
        { id: 4, name: 'SitelinkDescription2', type: 4, is_part_of_key: false },
        { id: 5, name: 'SitelinkFinalUrls', type: 12, is_part_of_key: false },
        { id: 6, name: 'SitelinkFinalMobileUrls', type: 12, is_part_of_key: false },
        { id: 7, name: 'SitelinkTrackingUrl', type: 6, is_part_of_key: false },
        { id: 8, name: 'SitelinkFinalUrlSuffix', type: 4, is_part_of_key: false },
      ],
      id: 82896692,
      name: 'My feed',
      origin: 3,
      resource_name: 'customers/9262111890/feeds/82896692',
      status: 2,
    },
    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 a Feed

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.feeds.create([feed, other_feed], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/feeds/82896692'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a Feed

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

Arguments

entity required

The Feed 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 feed = {
  resource_name: 'customers/9262111890/feeds/82896692', // 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.feeds.update(feed)

// Passing in an array of entities to update, validating only
const result = await customer.feeds.update([feed, other_feed], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/feeds/82896692'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a Feed

The customer.feeds.delete(resource_name) sets the status field of a Feed 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 Feed

Returns

Nothing

// Deleting the entity

await customer.feeds.delete('customers/9262111890/feeds/82896692')

FeedItem

The FeedItem object

Fields

attribute_values array of objects

The feed item's attribute values.

end_date_time string

End time in which this feed item is no longer effective and will stop serving. The time is in the customer's time zone. The format is "YYYY-MM-DD HH:MM:SS". Examples: "2018-03-05 09:15:00" or "2018-02-01 14:34:30"

feed string

Immutable. The feed to which this feed item belongs.

geo_targeting_restriction enum

Geo targeting restriction specifies the type of location that can be used for targeting.

id int64

Output only. The ID of this feed item.

policy_infos array of objects

Output only. List of info about a feed item's validation and approval state for active feed mappings. There will be an entry in the list for each type of feed mapping associated with the feed, e.g. a feed with a sitelink and a call feed mapping would cause every feed item associated with that feed to have an entry in this list for both sitelink and call. This field is read-only.

approval_status enum

Output only. The overall approval status of the placeholder type, calculated based on the status of its individual policy topic entries.

feed_mapping_resource_name string

Output only. The FeedMapping that contains the placeholder type.

placeholder_type_enum enum

Output only. The placeholder type.

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
SITELINK (2)
Lets you show links in your ad to pages from your website, including the main landing page.
CALL (3)
Lets you attach a phone number to an ad, allowing customers to call directly from the ad.
APP (4)
Lets you provide users with a link that points to a mobile app in addition to a website.
LOCATION (5)
Lets you show locations of businesses from your Google My Business account in your ad. This helps people find your locations by showing your ads with your address, a map to your location, or the distance to your business. This extension type is useful to draw customers to your brick-and-mortar location.
AFFILIATE_LOCATION (6)
If you sell your product through retail chains, affiliate location extensions let you show nearby stores that carry your products.
CALLOUT (7)
Lets you include additional text with your search ads that provide detailed information about your business, including products and services you offer. Callouts appear in ads at the top and bottom of Google search results.
STRUCTURED_SNIPPET (8)
Lets you add more info to your ad, specific to some predefined categories such as types, brands, styles, etc. A minimum of 3 text (SNIPPETS) values are required.
MESSAGE (9)
Allows users to see your ad, click an icon, and contact you directly by text message. With one tap on your ad, people can contact you to book an appointment, get a quote, ask for information, or request a service.
PRICE (10)
Lets you display prices for a list of items along with your ads. A price feed is composed of three to eight price table rows.
PROMOTION (11)
Allows you to highlight sales and other promotions that let users see how they can save by buying now.
AD_CUSTOMIZER (12)
Lets you dynamically inject custom data into the title and description of your ads.
DYNAMIC_EDUCATION (13)
Indicates that this feed is for education dynamic remarketing.
DYNAMIC_FLIGHT (14)
Indicates that this feed is for flight dynamic remarketing.
DYNAMIC_CUSTOM (15)
Indicates that this feed is for a custom dynamic remarketing type. Use this only if the other business types don't apply to your products or services.
DYNAMIC_HOTEL (16)
Indicates that this feed is for hotels and rentals dynamic remarketing.
DYNAMIC_REAL_ESTATE (17)
Indicates that this feed is for real estate dynamic remarketing.
DYNAMIC_TRAVEL (18)
Indicates that this feed is for travel dynamic remarketing.
DYNAMIC_LOCAL (19)
Indicates that this feed is for local deals dynamic remarketing.
DYNAMIC_JOB (20)
Indicates that this feed is for job dynamic remarketing.

policy_topic_entries array of objects

Output only. The list of policy findings for the placeholder type.

constraints array of objects

Indicates how serving of this resource may be affected (e.g. not serving in a country).

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.

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.

destination_text_list object

The text in the destination of the resource that is causing a policy finding.

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.

website_list object

List of websites linked with this resource.

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.

quality_approval_status enum

Output only. Placeholder type quality evaluation approval status.

quality_disapproval_reasons array of strings

Output only. List of placeholder type quality evaluation disapproval reasons.

review_status enum

Output only. Where the placeholder type is in the review process.

validation_errors array of objects

Output only. List of placeholder type validation errors.

description string

Output only. The description of the validation error.

extra_info string

Output only. Any extra information related to this error which is not captured by validation_error and feed_attribute_id (e.g. placeholder field IDs when feed_attribute_id is not mapped). Note that extra_info is not localized.

feed_attribute_ids array of strings

Output only. Set of feed attributes in the feed item flagged during validation. If empty, no specific feed attributes can be associated with the error (e.g. error across the entire feed item).

validation_error enum

Output only. Error code indicating what validation error was triggered. The description of the error can be found in the 'description' field.

UNSPECIFIED ()
No value has been specified.
UNKNOWN ()
Used for return value only. Represents value unknown in this version.
STRING_TOO_SHORT ()
String is too short.
STRING_TOO_LONG ()
String is too long.
VALUE_NOT_SPECIFIED ()
Value is not provided.
INVALID_DOMESTIC_PHONE_NUMBER_FORMAT ()
Phone number format is invalid for region.
INVALID_PHONE_NUMBER ()
String does not represent a phone number.
PHONE_NUMBER_NOT_SUPPORTED_FOR_COUNTRY ()
Phone number format is not compatible with country code.
PREMIUM_RATE_NUMBER_NOT_ALLOWED ()
Premium rate number is not allowed.
DISALLOWED_NUMBER_TYPE ()
Phone number type is not allowed.
VALUE_OUT_OF_RANGE ()
Specified value is outside of the valid range.
CALLTRACKING_NOT_SUPPORTED_FOR_COUNTRY ()
Call tracking is not supported in the selected country.
CUSTOMER_NOT_WHITELISTED_FOR_CALLTRACKING ()
Customer is not whitelisted for call tracking.
INVALID_COUNTRY_CODE ()
Country code is invalid.
INVALID_APP_ID ()
The specified mobile app id is invalid.
MISSING_ATTRIBUTES_FOR_FIELDS ()
Some required field attributes are missing.
INVALID_TYPE_ID ()
Invalid email button type for email extension.
INVALID_EMAIL_ADDRESS ()
Email address is invalid.
INVALID_HTTPS_URL ()
The HTTPS URL in email extension is invalid.
MISSING_DELIVERY_ADDRESS ()
Delivery address is missing from email extension.
START_DATE_AFTER_END_DATE ()
FeedItem scheduling start date comes after end date.
MISSING_FEED_ITEM_START_TIME ()
FeedItem scheduling start time is missing.
MISSING_FEED_ITEM_END_TIME ()
FeedItem scheduling end time is missing.
MISSING_FEED_ITEM_ID ()
Cannot compute system attributes on a FeedItem that has no FeedItemId.
VANITY_PHONE_NUMBER_NOT_ALLOWED ()
Call extension vanity phone numbers are not supported.
INVALID_REVIEW_EXTENSION_SNIPPET ()
Invalid review text.
INVALID_NUMBER_FORMAT ()
Invalid format for numeric value in ad parameter.
INVALID_DATE_FORMAT ()
Invalid format for date value in ad parameter.
INVALID_PRICE_FORMAT ()
Invalid format for price value in ad parameter.
UNKNOWN_PLACEHOLDER_FIELD ()
Unrecognized type given for value in ad parameter.
MISSING_ENHANCED_SITELINK_DESCRIPTION_LINE ()
Enhanced sitelinks must have both description lines specified.
REVIEW_EXTENSION_SOURCE_INELIGIBLE ()
Review source is ineligible.
HYPHENS_IN_REVIEW_EXTENSION_SNIPPET ()
Review text cannot contain hyphens or dashes.
DOUBLE_QUOTES_IN_REVIEW_EXTENSION_SNIPPET ()
Review text cannot contain double quote characters.
QUOTES_IN_REVIEW_EXTENSION_SNIPPET ()
Review text cannot contain quote characters.
INVALID_FORM_ENCODED_PARAMS ()
Parameters are encoded in the wrong format.
INVALID_URL_PARAMETER_NAME ()
URL parameter name must contain only letters, numbers, underscores, and dashes.
NO_GEOCODING_RESULT ()
Cannot find address location.
SOURCE_NAME_IN_REVIEW_EXTENSION_TEXT ()
Review extension text has source name.
CARRIER_SPECIFIC_SHORT_NUMBER_NOT_ALLOWED ()
Some phone numbers can be shorter than usual. Some of these short numbers are carrier-specific, and we disallow those in ad extensions because they will not be available to all users.
INVALID_PLACEHOLDER_FIELD_ID ()
Triggered when a request references a placeholder field id that does not exist.
INVALID_URL_TAG ()
URL contains invalid ValueTrack tags or format.
LIST_TOO_LONG ()
Provided list exceeds acceptable size.
INVALID_ATTRIBUTES_COMBINATION ()
Certain combinations of attributes aren't allowed to be specified in the same feed item.
DUPLICATE_VALUES ()
An attribute has the same value repeatedly.
INVALID_CALL_CONVERSION_ACTION_ID ()
Advertisers can link a conversion action with a phone number to indicate that sufficiently long calls forwarded to that phone number should be counted as conversions of the specified type. This is an error message indicating that the conversion action specified is invalid (e.g., the conversion action does not exist within the appropriate Google Ads account, or it is a type of conversion not appropriate to phone call conversions).
CANNOT_SET_WITHOUT_FINAL_URLS ()
Tracking template requires final url to be set.
APP_ID_DOESNT_EXIST_IN_APP_STORE ()
An app id was provided that doesn't exist in the given app store.
INVALID_FINAL_URL ()
Invalid U2 final url.
INVALID_TRACKING_URL ()
Invalid U2 tracking url.
INVALID_FINAL_URL_FOR_APP_DOWNLOAD_URL ()
Final URL should start from App download URL.
LIST_TOO_SHORT ()
List provided is too short.
INVALID_USER_ACTION ()
User Action field has invalid value.
INVALID_TYPE_NAME ()
Type field has invalid value.
INVALID_EVENT_CHANGE_STATUS ()
Change status for event is invalid.
INVALID_SNIPPETS_HEADER ()
The header of a structured snippets extension is not one of the valid headers.
INVALID_ANDROID_APP_LINK ()
Android app link is not formatted correctly
NUMBER_TYPE_WITH_CALLTRACKING_NOT_SUPPORTED_FOR_COUNTRY ()
Phone number incompatible with call tracking for country.
RESERVED_KEYWORD_OTHER ()
The input is identical to a reserved keyword
DUPLICATE_OPTION_LABELS ()
Each option label in the message extension must be unique.
DUPLICATE_OPTION_PREFILLS ()
Each option prefill in the message extension must be unique.
UNEQUAL_LIST_LENGTHS ()
In message extensions, the number of optional labels and optional prefills must be the same.
INCONSISTENT_CURRENCY_CODES ()
All currency codes in an ad extension must be the same.
PRICE_EXTENSION_HAS_DUPLICATED_HEADERS ()
Headers in price extension are not unique.
ITEM_HAS_DUPLICATED_HEADER_AND_DESCRIPTION ()
Header and description in an item are the same.
PRICE_EXTENSION_HAS_TOO_FEW_ITEMS ()
Price extension has too few items.
UNSUPPORTED_VALUE ()
The given value is not supported.
INVALID_FINAL_MOBILE_URL ()
Invalid final mobile url.
INVALID_KEYWORDLESS_AD_RULE_LABEL ()
The given string value of Label contains invalid characters
VALUE_TRACK_PARAMETER_NOT_SUPPORTED ()
The given URL contains value track parameters.
UNSUPPORTED_VALUE_IN_SELECTED_LANGUAGE ()
The given value is not supported in the selected language of an extension.
INVALID_IOS_APP_LINK ()
The iOS app link is not formatted correctly.
MISSING_IOS_APP_LINK_OR_IOS_APP_STORE_ID ()
iOS app link or iOS app store id is missing.
PROMOTION_INVALID_TIME ()
Promotion time is invalid.
PROMOTION_CANNOT_SET_PERCENT_OFF_AND_MONEY_AMOUNT_OFF ()
Both the percent off and money amount off fields are set.
PROMOTION_CANNOT_SET_PROMOTION_CODE_AND_ORDERS_OVER_AMOUNT ()
Both the promotion code and orders over amount fields are set.
TOO_MANY_DECIMAL_PLACES_SPECIFIED ()
Too many decimal places are specified.
AD_CUSTOMIZERS_NOT_ALLOWED ()
Ad Customizers are present and not allowed.
INVALID_LANGUAGE_CODE ()
Language code is not valid.
UNSUPPORTED_LANGUAGE ()
Language is not supported.
IF_FUNCTION_NOT_ALLOWED ()
IF Function is present and not allowed.
INVALID_FINAL_URL_SUFFIX ()
Final url suffix is not valid.
INVALID_TAG_IN_FINAL_URL_SUFFIX ()
Final url suffix contains an invalid tag.
INVALID_FINAL_URL_SUFFIX_FORMAT ()
Final url suffix is formatted incorrectly.
CUSTOMER_CONSENT_FOR_CALL_RECORDING_REQUIRED ()
Consent for call recording, which is required for the use of call extensions, was not provided by the advertiser. Please see https://support.google.com/google-ads/answer/7412639.
ONLY_ONE_DELIVERY_OPTION_IS_ALLOWED ()
Multiple message delivery options are set.
NO_DELIVERY_OPTION_IS_SET ()
No message delivery option is set.
INVALID_CONVERSION_REPORTING_STATE ()
String value of conversion reporting state field is not valid.
IMAGE_SIZE_WRONG ()
Image size is not right.
EMAIL_DELIVERY_NOT_AVAILABLE_IN_COUNTRY ()
Email delivery is not supported in the country specified in the country code field.
AUTO_REPLY_NOT_AVAILABLE_IN_COUNTRY ()
Auto reply is not supported in the country specified in the country code field.
INVALID_LATITUDE_VALUE ()
Invalid value specified for latitude.
INVALID_LONGITUDE_VALUE ()
Invalid value specified for longitude.
TOO_MANY_LABELS ()
Too many label fields provided.
INVALID_IMAGE_URL ()
Invalid image url.
MISSING_LATITUDE_VALUE ()
Latitude value is missing.
MISSING_LONGITUDE_VALUE ()
Longitude value is missing.
ADDRESS_NOT_FOUND ()
Unable to find address.
ADDRESS_NOT_TARGETABLE ()
Cannot target provided address.

validation_status enum

Output only. The validation status of the palceholder type.

resource_name string

Immutable. The resource name of the feed item. Feed item resource names have the form: customers/{customer_id}/feedItems/{feed_id}~{feed_item_id}

start_date_time string

Start time in which this feed item is effective and can begin serving. The time is in the customer's time zone. The format is "YYYY-MM-DD HH:MM:SS". Examples: "2018-03-05 09:15:00" or "2018-02-01 14:34:30"

status enum

Output only. Status of the feed item. This field is read-only.

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.

// Example FeedItem
const feed_item = {
  attribute_values: [
    {
      feed_attribute_id: 1,
      string_value: 'AdWords Knowledge Base',
      integer_values_list: [],
      boolean_values_list: [],
      string_values_list: [],
      double_values_list: [],
    },
    {
      feed_attribute_id: 3,
      string_value: 'Adwords Guides, Case Studies',
      integer_values_list: [],
      boolean_values_list: [],
      string_values_list: [],
      double_values_list: [],
    },
    {
      feed_attribute_id: 4,
      string_value: 'Chrome Extensions and more!',
      integer_values_list: [],
      boolean_values_list: [],
      string_values_list: [],
      double_values_list: [],
    },
    {
      feed_attribute_id: 5,
      integer_values_list: [],
      boolean_values_list: [],
      string_values_list: ['https://opteo.com/docs'],
      double_values_list: [],
    },
  ],
  feed: 'customers/3827277046/feeds/43009393',
  geo_targeting_restriction: 0,
  id: 9779152283,
  policy_infos: [
    {
      placeholder_type_enum: 2,
      feed_mapping_resource_name: 'customers/3827277046/feedMappings/43009393~46066123',
      review_status: 3,
      approval_status: 2,
      policy_topic_entries_list: [{ topic: 'DESTINATION_MISMATCH', type: 2, evidences_list: [], constraints_list: [] }],
      validation_status: 4,
      validation_errors_list: [],
      quality_approval_status: 0,
      quality_disapproval_reasons_list: [],
    },
  ],
  resource_name: 'customers/3827277046/feedItems/43009393~9779152283',
  status: 3,
  url_custom_parameters: [],
}

Get a FeedItem

The customer.feedItems.get(resource_name) method returns the FeedItem identified by a resource_name.

Arguments

resource_name required

The resource_name of that FeedItem

Returns

Returns that FeedItem as an object.

// Getting the entity
let result = await customer.feedItems.get('customers/3827277046/feedItems/43009393~9779152283')

// Example result
;({
  attribute_values: [
    {
      feed_attribute_id: 1,
      string_value: 'AdWords Knowledge Base',
      integer_values_list: [],
      boolean_values_list: [],
      string_values_list: [],
      double_values_list: [],
    },
    {
      feed_attribute_id: 3,
      string_value: 'Adwords Guides, Case Studies',
      integer_values_list: [],
      boolean_values_list: [],
      string_values_list: [],
      double_values_list: [],
    },
    {
      feed_attribute_id: 4,
      string_value: 'Chrome Extensions and more!',
      integer_values_list: [],
      boolean_values_list: [],
      string_values_list: [],
      double_values_list: [],
    },
    {
      feed_attribute_id: 5,
      integer_values_list: [],
      boolean_values_list: [],
      string_values_list: ['https://opteo.com/docs'],
      double_values_list: [],
    },
  ],
  feed: 'customers/3827277046/feeds/43009393',
  geo_targeting_restriction: 0,
  id: 9779152283,
  policy_infos: [
    {
      placeholder_type_enum: 2,
      feed_mapping_resource_name: 'customers/3827277046/feedMappings/43009393~46066123',
      review_status: 3,
      approval_status: 2,
      policy_topic_entries_list: [{ topic: 'DESTINATION_MISMATCH', type: 2, evidences_list: [], constraints_list: [] }],
      validation_status: 4,
      validation_errors_list: [],
      quality_approval_status: 0,
      quality_disapproval_reasons_list: [],
    },
  ],
  resource_name: 'customers/3827277046/feedItems/43009393~9779152283',
  status: 3,
  url_custom_parameters: [],
})

List every instance of FeedItem

The customer.feedItems.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 FeedItem.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.feedItems.list({
  constraints: [
    {
      key: 'feed_item.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'feed_item.some_field.sub_field',
})

// Example result
;[
  {
    feed_item: {
      attribute_values: [
        {
          feed_attribute_id: 1,
          string_value: 'AdWords Knowledge Base',
          integer_values_list: [],
          boolean_values_list: [],
          string_values_list: [],
          double_values_list: [],
        },
        {
          feed_attribute_id: 3,
          string_value: 'Adwords Guides, Case Studies',
          integer_values_list: [],
          boolean_values_list: [],
          string_values_list: [],
          double_values_list: [],
        },
        {
          feed_attribute_id: 4,
          string_value: 'Chrome Extensions and more!',
          integer_values_list: [],
          boolean_values_list: [],
          string_values_list: [],
          double_values_list: [],
        },
        {
          feed_attribute_id: 5,
          integer_values_list: [],
          boolean_values_list: [],
          string_values_list: ['https://opteo.com/docs'],
          double_values_list: [],
        },
      ],
      feed: 'customers/3827277046/feeds/43009393',
      geo_targeting_restriction: 0,
      id: 9779152283,
      policy_infos: [
        {
          placeholder_type_enum: 2,
          feed_mapping_resource_name: 'customers/3827277046/feedMappings/43009393~46066123',
          review_status: 3,
          approval_status: 2,
          policy_topic_entries_list: [
            { topic: 'DESTINATION_MISMATCH', type: 2, evidences_list: [], constraints_list: [] },
          ],
          validation_status: 4,
          validation_errors_list: [],
          quality_approval_status: 0,
          quality_disapproval_reasons_list: [],
        },
      ],
      resource_name: 'customers/3827277046/feedItems/43009393~9779152283',
      status: 3,
      url_custom_parameters: [],
    },
    ad_group_ad: {
      ad: {
        added_by_google_ads: false,
        device_preference: 0,
        expanded_text_ad: {
          description: 'Top Rated AdWords PPC Tool. Designed For Agencies. Try It Free!',
          headline_part1: 'Top Rated Google Ad Tool',
          headline_part2: 'Lift PPC Results In 30 Seconds',
          path1: 'google-ad',
          path2: 'tool',
        },
        final_app_urls: [],
        final_mobile_urls: [],
        final_urls: ['http://lp3.opteo.com/lp/google-ad-tool'],
        id: 170067910717,
        resource_name: 'customers/3827277046/ads/170067910717',
        system_managed_resource_source: 0,
        type: 3,
        url_collections: [],
        url_custom_parameters: [],
      },
      ad_group: 'customers/3827277046/adGroups/36337682617',
      ad_strength: 0,
      policy_summary: {
        approval_status: 3,
        policy_topic_entries: [
          {
            topic: 'TRADEMARKS_IN_AD_TEXT',
            type: 4,
            evidences_list: [{ text_list: { texts: ['Google'] } }],
            constraints_list: [
              {
                country_constraint_list: {
                  total_targeted_countries: 23,
                  countries: [
                    { country_criterion: 'geoTargetConstants/2528' },
                    { country_criterion: 'geoTargetConstants/2040' },
                    { country_criterion: 'geoTargetConstants/2710' },
                    { country_criterion: 'geoTargetConstants/2702' },
                    { country_criterion: 'geoTargetConstants/2246' },
                    { country_criterion: 'geoTargetConstants/2380' },
                    { country_criterion: 'geoTargetConstants/2056' },
                    { country_criterion: 'geoTargetConstants/2344' },
                    { country_criterion: 'geoTargetConstants/2250' },
                    { country_criterion: 'geoTargetConstants/2442' },
                    { country_criterion: 'geoTargetConstants/2752' },
                    { country_criterion: 'geoTargetConstants/2724' },
                    { country_criterion: 'geoTargetConstants/2756' },
                    { country_criterion: 'geoTargetConstants/2276' },
                    { country_criterion: 'geoTargetConstants/2348' },
                    { country_criterion: 'geoTargetConstants/2578' },
                    { country_criterion: 'geoTargetConstants/2203' },
                  ],
                },
              },
            ],
          },
        ],
        review_status: 3,
      },
      resource_name: 'customers/3827277046/adGroupAds/36337682617~170067910717',
      status: 2,
    },
    feed: {
      attributes: [
        { id: 1, name: 'SitelinkName', type: 4, is_part_of_key: false },
        { id: 2, name: 'SitelinkUrl', type: 6, is_part_of_key: false },
        { id: 3, name: 'SitelinkDescription1', type: 4, is_part_of_key: false },
        { id: 4, name: 'SitelinkDescription2', type: 4, is_part_of_key: false },
        { id: 5, name: 'SitelinkFinalUrls', type: 12, is_part_of_key: false },
        { id: 6, name: 'SitelinkFinalMobileUrls', type: 12, is_part_of_key: false },
        { id: 7, name: 'SitelinkTrackingUrl', type: 6, is_part_of_key: false },
        { id: 8, name: 'SitelinkFinalUrlSuffix', type: 4, is_part_of_key: false },
      ],
      id: 43009393,
      name: 'My feed',
      origin: 3,
      resource_name: 'customers/3827277046/feeds/43009393',
      status: 2,
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/36337682617',
      campaign: 'customers/3827277046/campaigns/729468367',
      cpc_bid_micros: 5000000,
      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: 36337682617,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/36337682617',
      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: false },
          { 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/729468367',
      bidding_strategy_type: 3,
      campaign_budget: 'customers/3827277046/campaignBudgets/1005586771',
      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: 729468367,
      labels: [],
      manual_cpc: { enhanced_cpc_enabled: true },
      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/729468367',
      serving_status: 2,
      start_date: '2017-01-04',
      status: 4,
      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 a FeedItem

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.feedItems.create([feed_item, other_feed_item], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/feedItems/43009393~9779152283'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a FeedItem

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

Arguments

entity required

The FeedItem 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 feed_item = {
  resource_name: 'customers/3827277046/feedItems/43009393~9779152283', // 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.feedItems.update(feed_item)

// Passing in an array of entities to update, validating only
const result = await customer.feedItems.update([feed_item, other_feed_item], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/feedItems/43009393~9779152283'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a FeedItem

The customer.feedItems.delete(resource_name) sets the status field of a FeedItem 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 FeedItem

Returns

Nothing

// Deleting the entity

await customer.feedItems.delete('customers/3827277046/feedItems/43009393~9779152283')

FeedItemTarget

The FeedItemTarget object

Fields

ONE of the following:

ad_group string
Immutable. The targeted ad group.
ad_schedule object
Immutable. The targeted schedule.
Child Fields
day_of_week enum
Day of the week the schedule applies to. This field is required for CREATE operations and is prohibited on UPDATE operations.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
MONDAY (2)
Monday.
TUESDAY (3)
Tuesday.
WEDNESDAY (4)
Wednesday.
THURSDAY (5)
Thursday.
FRIDAY (6)
Friday.
SATURDAY (7)
Saturday.
SUNDAY (8)
Sunday.
end_hour int32
Ending hour in 24 hour time; 24 signifies end of the day. This field must be between 0 and 24, inclusive. This field is required for CREATE operations and is prohibited on UPDATE operations.
end_minute enum
Minutes after the end hour at which this schedule ends. The schedule is exclusive of the end minute. This field is required for CREATE operations and is prohibited on UPDATE operations.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
ZERO (2)
Zero minutes past the hour.
FIFTEEN (3)
Fifteen minutes past the hour.
THIRTY (4)
Thirty minutes past the hour.
FORTY_FIVE (5)
Forty-five minutes past the hour.
start_hour int32
Starting hour in 24 hour time. This field must be between 0 and 23, inclusive. This field is required for CREATE operations and is prohibited on UPDATE operations.
start_minute enum
Minutes after the start hour at which this schedule starts. This field is required for CREATE operations and is prohibited on UPDATE operations.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
ZERO (2)
Zero minutes past the hour.
FIFTEEN (3)
Fifteen minutes past the hour.
THIRTY (4)
Thirty minutes past the hour.
FORTY_FIVE (5)
Forty-five minutes past the hour.
campaign string
Immutable. The targeted campaign.
device enum
Immutable. The targeted device.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
MOBILE (2)
Mobile.
geo_target_constant string
Immutable. The targeted geo target constant resource name.
keyword object
Immutable. The targeted keyword.
Child Fields
match_type enum
The match type of the keyword.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EXACT (2)
Exact match.
PHRASE (3)
Phrase match.
BROAD (4)
Broad match.
text string
The text of the keyword (at most 80 characters and 10 words).

feed_item string

Immutable. The feed item to which this feed item target belongs.

feed_item_target_id int64

Output only. The ID of the targeted resource. This field is read-only.

feed_item_target_type enum

Output only. The target type of this feed item target. This field is read-only.

resource_name string

Immutable. The resource name of the feed item target. Feed item target resource names have the form: customers/{customer_id}/feedItemTargets/{feed_id}~{feed_item_id}~{feed_item_target_type}~{feed_item_target_id}

status enum

Output only. Status of the feed item target. This field is read-only.

// Example FeedItemTarget
const feed_item_target = /* Todo: add example get() return here */

Get a FeedItemTarget

The customer.feedItemTargets.get(resource_name) method returns the FeedItemTarget identified by a resource_name.

Arguments

resource_name required

The resource_name of that FeedItemTarget

Returns

Returns that FeedItemTarget as an object.

// Getting the entity
let result = await customer.feedItemTargets.get('customers/1234567890/feedItemTargets/123123123')

// Example result
(/* Todo: add example get() return here */)

List every instance of FeedItemTarget

The customer.feedItemTargets.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 FeedItemTarget.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.feedItemTargets.list({
  constraints: [
    {
      key: 'feed_item_target.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'feed_item_target.some_field.sub_field',
})

// Example result
;[
  /* Todo: add example list() return here */
]

Create a FeedItemTarget

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.feedItemTargets.create([feed_item_target, other_feed_item_target], {
  validate_only: true,
})

// Example result
{
	results : ['customers/1234567890/feedItemTargets/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a FeedItemTarget

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

Arguments

entity required

The FeedItemTarget 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 feed_item_target = {
  resource_name: 'customers/1234567890/feedItemTargets/123123123', // 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.feedItemTargets.update(feed_item_target)

// Passing in an array of entities to update, validating only
const result = await customer.feedItemTargets.update([feed_item_target, other_feed_item_target], {
  validate_only: true,
})

// Example result
{
	results : ['customers/1234567890/feedItemTargets/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a FeedItemTarget

The customer.feedItemTargets.delete(resource_name) sets the status field of a FeedItemTarget 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 FeedItemTarget

Returns

Nothing

// Deleting the entity

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

FeedMapping

The FeedMapping object

Fields

ONE of the following:

criterion_type enum
Immutable. The criterion type of this mapping (i.e., if the mapping maps feed attributes to criterion fields).
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
LOCATION_EXTENSION_TARGETING (4)
Allows campaign targeting at locations within a location feed.
DSA_PAGE_FEED (3)
Allows url targeting for your dynamic search ads within a page feed.
placeholder_type enum
Immutable. The placeholder type of this mapping (i.e., if the mapping maps feed attributes to placeholder fields).
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
SITELINK (2)
Lets you show links in your ad to pages from your website, including the main landing page.
CALL (3)
Lets you attach a phone number to an ad, allowing customers to call directly from the ad.
APP (4)
Lets you provide users with a link that points to a mobile app in addition to a website.
LOCATION (5)
Lets you show locations of businesses from your Google My Business account in your ad. This helps people find your locations by showing your ads with your address, a map to your location, or the distance to your business. This extension type is useful to draw customers to your brick-and-mortar location.
AFFILIATE_LOCATION (6)
If you sell your product through retail chains, affiliate location extensions let you show nearby stores that carry your products.
CALLOUT (7)
Lets you include additional text with your search ads that provide detailed information about your business, including products and services you offer. Callouts appear in ads at the top and bottom of Google search results.
STRUCTURED_SNIPPET (8)
Lets you add more info to your ad, specific to some predefined categories such as types, brands, styles, etc. A minimum of 3 text (SNIPPETS) values are required.
MESSAGE (9)
Allows users to see your ad, click an icon, and contact you directly by text message. With one tap on your ad, people can contact you to book an appointment, get a quote, ask for information, or request a service.
PRICE (10)
Lets you display prices for a list of items along with your ads. A price feed is composed of three to eight price table rows.
PROMOTION (11)
Allows you to highlight sales and other promotions that let users see how they can save by buying now.
AD_CUSTOMIZER (12)
Lets you dynamically inject custom data into the title and description of your ads.
DYNAMIC_EDUCATION (13)
Indicates that this feed is for education dynamic remarketing.
DYNAMIC_FLIGHT (14)
Indicates that this feed is for flight dynamic remarketing.
DYNAMIC_CUSTOM (15)
Indicates that this feed is for a custom dynamic remarketing type. Use this only if the other business types don't apply to your products or services.
DYNAMIC_HOTEL (16)
Indicates that this feed is for hotels and rentals dynamic remarketing.
DYNAMIC_REAL_ESTATE (17)
Indicates that this feed is for real estate dynamic remarketing.
DYNAMIC_TRAVEL (18)
Indicates that this feed is for travel dynamic remarketing.
DYNAMIC_LOCAL (19)
Indicates that this feed is for local deals dynamic remarketing.
DYNAMIC_JOB (20)
Indicates that this feed is for job dynamic remarketing.

attribute_field_mappings array of objects

Immutable. Feed attributes to field mappings. These mappings are a one-to-many relationship meaning that 1 feed attribute can be used to populate multiple placeholder fields, but 1 placeholder field can only draw data from 1 feed attribute. Ad Customizer is an exception, 1 placeholder field can be mapped to multiple feed attributes. Required.

ad_customizer_field enum

Immutable. Ad Customizer Placeholder Fields

affiliate_location_field enum

Output only. Affiliate Location Placeholder Fields. This field is read-only.

app_field enum

Immutable. App Placeholder Fields.

call_field enum

Immutable. Call Placeholder Fields.

callout_field enum

Immutable. Callout Placeholder Fields.

custom_field enum

Immutable. Custom Placeholder Fields

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
ID (2)
Data Type: STRING. Required. Combination ID and ID2 must be unique per offer.
ID2 (3)
Data Type: STRING. Combination ID and ID2 must be unique per offer.
ITEM_TITLE (4)
Data Type: STRING. Required. Main headline with product name to be shown in dynamic ad.
ITEM_SUBTITLE (5)
Data Type: STRING. Optional text to be shown in the image ad.
ITEM_DESCRIPTION (6)
Data Type: STRING. Optional description of the product to be shown in the ad.
ITEM_ADDRESS (7)
Data Type: STRING. Full address of your offer or service, including postal code. This will be used to identify the closest product to the user when there are multiple offers in the feed that are relevant to the user.
PRICE (8)
Data Type: STRING. Price to be shown in the ad. Example: "100.00 USD"
FORMATTED_PRICE (9)
Data Type: STRING. Formatted price to be shown in the ad. Example: "Starting at $100.00 USD", "$80 - $100"
SALE_PRICE (10)
Data Type: STRING. Sale price to be shown in the ad. Example: "80.00 USD"
FORMATTED_SALE_PRICE (11)
Data Type: STRING. Formatted sale price to be shown in the ad. Example: "On sale for $80.00", "$60 - $80"
IMAGE_URL (12)
Data Type: URL. Image to be displayed in the ad. Highly recommended for image ads.
ITEM_CATEGORY (13)
Data Type: STRING. Used as a recommendation engine signal to serve items in the same category.
FINAL_URLS (14)
Data Type: URL_LIST. Final URLs for the ad when using Upgraded URLs. User will be redirected to these URLs when they click on an ad, or when they click on a specific product for ads that have multiple products.
FINAL_MOBILE_URLS (15)
Data Type: URL_LIST. Final mobile URLs for the ad when using Upgraded URLs.
TRACKING_URL (16)
Data Type: URL. Tracking template for the ad when using Upgraded URLs.
CONTEXTUAL_KEYWORDS (17)
Data Type: STRING_LIST. Keywords used for product retrieval.
ANDROID_APP_LINK (18)
Data Type: STRING. Android app link. Must be formatted as: android-app://{package_id}/{scheme}/{host_path}. The components are defined as follows: package_id: app ID as specified in Google Play. scheme: the scheme to pass to the application. Can be HTTP, or a custom scheme. host_path: identifies the specific content within your application.
SIMILAR_IDS (19)
Data Type: STRING_LIST. List of recommended IDs to show together with this item.
IOS_APP_LINK (20)
Data Type: STRING. iOS app link.
IOS_APP_STORE_ID (21)
Data Type: INT64. iOS app store ID.

dsa_page_feed_field enum

Immutable. Dynamic Search Ad Page Feed Fields.

education_field enum

Immutable. Education Placeholder Fields

feed_attribute_id int64

Immutable. Feed attribute from which to map.

field_id int64

Output only. The placeholder field ID. If a placeholder field enum is not published in the current API version, then this field will be populated and the field oneof will be empty. This field is read-only.

flight_field enum

Immutable. Flight Placeholder Fields

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
DESTINATION_ID (2)
Data Type: STRING. Required. Destination id. Example: PAR, LON. For feed items that only have destination id, destination id must be a unique key. For feed items that have both destination id and origin id, then the combination must be a unique key.
ORIGIN_ID (3)
Data Type: STRING. Origin id. Example: PAR, LON. Optional. Combination of destination id and origin id must be unique per offer.
FLIGHT_DESCRIPTION (4)
Data Type: STRING. Required. Main headline with product name to be shown in dynamic ad.
ORIGIN_NAME (5)
Data Type: STRING. Shorter names are recommended.
DESTINATION_NAME (6)
Data Type: STRING. Shorter names are recommended.
FLIGHT_PRICE (7)
Data Type: STRING. Price to be shown in the ad. Example: "100.00 USD"
FORMATTED_PRICE (8)
Data Type: STRING. Formatted price to be shown in the ad. Example: "Starting at $100.00 USD", "$80 - $100"
FLIGHT_SALE_PRICE (9)
Data Type: STRING. Sale price to be shown in the ad. Example: "80.00 USD"
FORMATTED_SALE_PRICE (10)
Data Type: STRING. Formatted sale price to be shown in the ad. Example: "On sale for $80.00", "$60 - $80"
IMAGE_URL (11)
Data Type: URL. Image to be displayed in the ad.
FINAL_URLS (12)
Data Type: URL_LIST. Required. Final URLs for the ad when using Upgraded URLs. User will be redirected to these URLs when they click on an ad, or when they click on a specific flight for ads that show multiple flights.
FINAL_MOBILE_URLS (13)
Data Type: URL_LIST. Final mobile URLs for the ad when using Upgraded URLs.
TRACKING_URL (14)
Data Type: URL. Tracking template for the ad when using Upgraded URLs.
ANDROID_APP_LINK (15)
Data Type: STRING. Android app link. Must be formatted as: android-app://{package_id}/{scheme}/{host_path}. The components are defined as follows: package_id: app ID as specified in Google Play. scheme: the scheme to pass to the application. Can be HTTP, or a custom scheme. host_path: identifies the specific content within your application.
SIMILAR_DESTINATION_IDS (16)
Data Type: STRING_LIST. List of recommended destination IDs to show together with this item.
IOS_APP_LINK (17)
Data Type: STRING. iOS app link.
IOS_APP_STORE_ID (18)
Data Type: INT64. iOS app store ID.

hotel_field enum

Immutable. Hotel Placeholder Fields

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
PROPERTY_ID (2)
Data Type: STRING. Required. Unique ID.
PROPERTY_NAME (3)
Data Type: STRING. Required. Main headline with property name to be shown in dynamic ad.
DESTINATION_NAME (4)
Data Type: STRING. Name of destination to be shown in dynamic ad.
DESCRIPTION (5)
Data Type: STRING. Description of destination to be shown in dynamic ad.
ADDRESS (6)
Data Type: STRING. Complete property address, including postal code.
PRICE (7)
Data Type: STRING. Price to be shown in the ad. Example: "100.00 USD"
FORMATTED_PRICE (8)
Data Type: STRING. Formatted price to be shown in the ad. Example: "Starting at $100.00 USD", "$80 - $100"
SALE_PRICE (9)
Data Type: STRING. Sale price to be shown in the ad. Example: "80.00 USD"
FORMATTED_SALE_PRICE (10)
Data Type: STRING. Formatted sale price to be shown in the ad. Example: "On sale for $80.00", "$60 - $80"
IMAGE_URL (11)
Data Type: URL. Image to be displayed in the ad.
CATEGORY (12)
Data Type: STRING. Category of property used to group like items together for recommendation engine.
STAR_RATING (13)
Data Type: INT64. Star rating (1 to 5) used to group like items together for recommendation engine.
CONTEXTUAL_KEYWORDS (14)
Data Type: STRING_LIST. Keywords used for product retrieval.
FINAL_URLS (15)
Data Type: URL_LIST. Required. Final URLs for the ad when using Upgraded URLs. User will be redirected to these URLs when they click on an ad, or when they click on a specific flight for ads that show multiple flights.
FINAL_MOBILE_URLS (16)
Data Type: URL_LIST. Final mobile URLs for the ad when using Upgraded URLs.
TRACKING_URL (17)
Data Type: URL. Tracking template for the ad when using Upgraded URLs.
ANDROID_APP_LINK (18)
Data Type: STRING. Android app link. Must be formatted as: android-app://{package_id}/{scheme}/{host_path}. The components are defined as follows: package_id: app ID as specified in Google Play. scheme: the scheme to pass to the application. Can be HTTP, or a custom scheme. host_path: identifies the specific content within your application.
SIMILAR_PROPERTY_IDS (19)
Data Type: STRING_LIST. List of recommended property IDs to show together with this item.
IOS_APP_LINK (20)
Data Type: STRING. iOS app link.
IOS_APP_STORE_ID (21)
Data Type: INT64. iOS app store ID.

job_field enum

Immutable. Job Placeholder Fields

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
JOB_ID (2)
Data Type: STRING. Required. If only JOB_ID is specified, then it must be unique. If both JOB_ID and LOCATION_ID are specified, then the pair must be unique. ID) pair must be unique.
LOCATION_ID (3)
Data Type: STRING. Combination of JOB_ID and LOCATION_ID must be unique per offer.
TITLE (4)
Data Type: STRING. Required. Main headline with job title to be shown in dynamic ad.
SUBTITLE (5)
Data Type: STRING. Job subtitle to be shown in dynamic ad.
DESCRIPTION (6)
Data Type: STRING. Description of job to be shown in dynamic ad.
IMAGE_URL (7)
Data Type: URL. Image to be displayed in the ad. Highly recommended for image ads.
CATEGORY (8)
Data Type: STRING. Category of property used to group like items together for recommendation engine.
CONTEXTUAL_KEYWORDS (9)
Data Type: STRING_LIST. Keywords used for product retrieval.
ADDRESS (10)
Data Type: STRING. Complete property address, including postal code.
SALARY (11)
Data Type: STRING. Salary or salary range of job to be shown in dynamic ad.
FINAL_URLS (12)
Data Type: URL_LIST. Required. Final URLs to be used in ad when using Upgraded URLs; the more specific the better (e.g. the individual URL of a specific job and its location).
FINAL_MOBILE_URLS (14)
Data Type: URL_LIST. Final mobile URLs for the ad when using Upgraded URLs.
TRACKING_URL (15)
Data Type: URL. Tracking template for the ad when using Upgraded URLs.
ANDROID_APP_LINK (16)
Data Type: STRING. Android app link. Must be formatted as: android-app://{package_id}/{scheme}/{host_path}. The components are defined as follows: package_id: app ID as specified in Google Play. scheme: the scheme to pass to the application. Can be HTTP, or a custom scheme. host_path: identifies the specific content within your application.
SIMILAR_JOB_IDS (17)
Data Type: STRING_LIST. List of recommended job IDs to show together with this item.
IOS_APP_LINK (18)
Data Type: STRING. iOS app link.
IOS_APP_STORE_ID (19)
Data Type: INT64. iOS app store ID.

local_field enum

Immutable. Local Placeholder Fields

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
DEAL_ID (2)
Data Type: STRING. Required. Unique ID.
DEAL_NAME (3)
Data Type: STRING. Required. Main headline with local deal title to be shown in dynamic ad.
SUBTITLE (4)
Data Type: STRING. Local deal subtitle to be shown in dynamic ad.
DESCRIPTION (5)
Data Type: STRING. Description of local deal to be shown in dynamic ad.
PRICE (6)
Data Type: STRING. Price to be shown in the ad. Highly recommended for dynamic ads. Example: "100.00 USD"
FORMATTED_PRICE (7)
Data Type: STRING. Formatted price to be shown in the ad. Example: "Starting at $100.00 USD", "$80 - $100"
SALE_PRICE (8)
Data Type: STRING. Sale price to be shown in the ad. Example: "80.00 USD"
FORMATTED_SALE_PRICE (9)
Data Type: STRING. Formatted sale price to be shown in the ad. Example: "On sale for $80.00", "$60 - $80"
IMAGE_URL (10)
Data Type: URL. Image to be displayed in the ad.
ADDRESS (11)
Data Type: STRING. Complete property address, including postal code.
CATEGORY (12)
Data Type: STRING. Category of local deal used to group like items together for recommendation engine.
CONTEXTUAL_KEYWORDS (13)
Data Type: STRING_LIST. Keywords used for product retrieval.
FINAL_URLS (14)
Data Type: URL_LIST. Required. Final URLs to be used in ad when using Upgraded URLs; the more specific the better (e.g. the individual URL of a specific local deal and its location).
FINAL_MOBILE_URLS (15)
Data Type: URL_LIST. Final mobile URLs for the ad when using Upgraded URLs.
TRACKING_URL (16)
Data Type: URL. Tracking template for the ad when using Upgraded URLs.
ANDROID_APP_LINK (17)
Data Type: STRING. Android app link. Must be formatted as: android-app://{package_id}/{scheme}/{host_path}. The components are defined as follows: package_id: app ID as specified in Google Play. scheme: the scheme to pass to the application. Can be HTTP, or a custom scheme. host_path: identifies the specific content within your application.
SIMILAR_DEAL_IDS (18)
Data Type: STRING_LIST. List of recommended local deal IDs to show together with this item.
IOS_APP_LINK (19)
Data Type: STRING. iOS app link.
IOS_APP_STORE_ID (20)
Data Type: INT64. iOS app store ID.

location_extension_targeting_field enum

Immutable. Location Target Fields.

location_field enum

Output only. Location Placeholder Fields. This field is read-only.

message_field enum

Immutable. Message Placeholder Fields.

price_field enum

Immutable. Price Placeholder Fields.

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
TYPE (2)
Data Type: STRING. The type of your price feed. Must match one of the predefined price feed type exactly.
PRICE_QUALIFIER (3)
Data Type: STRING. The qualifier of each price. Must match one of the predefined price qualifiers exactly.
TRACKING_TEMPLATE (4)
Data Type: URL. Tracking template for the price feed when using Upgraded URLs.
LANGUAGE (5)
Data Type: STRING. Language of the price feed. Must match one of the available available locale codes exactly.
FINAL_URL_SUFFIX (6)
Data Type: STRING. Final URL suffix for the price feed when using parallel tracking.
ITEM_1_HEADER (100)
Data Type: STRING. The header of item 1 of the table.
ITEM_1_DESCRIPTION (101)
Data Type: STRING. The description of item 1 of the table.
ITEM_1_PRICE (102)
Data Type: MONEY. The price (money with currency) of item 1 of the table, e.g., 30 USD. The currency must match one of the available currencies.
ITEM_1_UNIT (103)
Data Type: STRING. The price unit of item 1 of the table. Must match one of the predefined price units.
ITEM_1_FINAL_URLS (104)
Data Type: URL_LIST. The final URLs of item 1 of the table when using Upgraded URLs.
ITEM_1_FINAL_MOBILE_URLS (105)
Data Type: URL_LIST. The final mobile URLs of item 1 of the table when using Upgraded URLs.
ITEM_2_HEADER (200)
Data Type: STRING. The header of item 2 of the table.
ITEM_2_DESCRIPTION (201)
Data Type: STRING. The description of item 2 of the table.
ITEM_2_PRICE (202)
Data Type: MONEY. The price (money with currency) of item 2 of the table, e.g., 30 USD. The currency must match one of the available currencies.
ITEM_2_UNIT (203)
Data Type: STRING. The price unit of item 2 of the table. Must match one of the predefined price units.
ITEM_2_FINAL_URLS (204)
Data Type: URL_LIST. The final URLs of item 2 of the table when using Upgraded URLs.
ITEM_2_FINAL_MOBILE_URLS (205)
Data Type: URL_LIST. The final mobile URLs of item 2 of the table when using Upgraded URLs.
ITEM_3_HEADER (300)
Data Type: STRING. The header of item 3 of the table.
ITEM_3_DESCRIPTION (301)
Data Type: STRING. The description of item 3 of the table.
ITEM_3_PRICE (302)
Data Type: MONEY. The price (money with currency) of item 3 of the table, e.g., 30 USD. The currency must match one of the available currencies.
ITEM_3_UNIT (303)
Data Type: STRING. The price unit of item 3 of the table. Must match one of the predefined price units.
ITEM_3_FINAL_URLS (304)
Data Type: URL_LIST. The final URLs of item 3 of the table when using Upgraded URLs.
ITEM_3_FINAL_MOBILE_URLS (305)
Data Type: URL_LIST. The final mobile URLs of item 3 of the table when using Upgraded URLs.
ITEM_4_HEADER (400)
Data Type: STRING. The header of item 4 of the table.
ITEM_4_DESCRIPTION (401)
Data Type: STRING. The description of item 4 of the table.
ITEM_4_PRICE (402)
Data Type: MONEY. The price (money with currency) of item 4 of the table, e.g., 30 USD. The currency must match one of the available currencies.
ITEM_4_UNIT (403)
Data Type: STRING. The price unit of item 4 of the table. Must match one of the predefined price units.
ITEM_4_FINAL_URLS (404)
Data Type: URL_LIST. The final URLs of item 4 of the table when using Upgraded URLs.
ITEM_4_FINAL_MOBILE_URLS (405)
Data Type: URL_LIST. The final mobile URLs of item 4 of the table when using Upgraded URLs.
ITEM_5_HEADER (500)
Data Type: STRING. The header of item 5 of the table.
ITEM_5_DESCRIPTION (501)
Data Type: STRING. The description of item 5 of the table.
ITEM_5_PRICE (502)
Data Type: MONEY. The price (money with currency) of item 5 of the table, e.g., 30 USD. The currency must match one of the available currencies.
ITEM_5_UNIT (503)
Data Type: STRING. The price unit of item 5 of the table. Must match one of the predefined price units.
ITEM_5_FINAL_URLS (504)
Data Type: URL_LIST. The final URLs of item 5 of the table when using Upgraded URLs.
ITEM_5_FINAL_MOBILE_URLS (505)
Data Type: URL_LIST. The final mobile URLs of item 5 of the table when using Upgraded URLs.
ITEM_6_HEADER (600)
Data Type: STRING. The header of item 6 of the table.
ITEM_6_DESCRIPTION (601)
Data Type: STRING. The description of item 6 of the table.
ITEM_6_PRICE (602)
Data Type: MONEY. The price (money with currency) of item 6 of the table, e.g., 30 USD. The currency must match one of the available currencies.
ITEM_6_UNIT (603)
Data Type: STRING. The price unit of item 6 of the table. Must match one of the predefined price units.
ITEM_6_FINAL_URLS (604)
Data Type: URL_LIST. The final URLs of item 6 of the table when using Upgraded URLs.
ITEM_6_FINAL_MOBILE_URLS (605)
Data Type: URL_LIST. The final mobile URLs of item 6 of the table when using Upgraded URLs.
ITEM_7_HEADER (700)
Data Type: STRING. The header of item 7 of the table.
ITEM_7_DESCRIPTION (701)
Data Type: STRING. The description of item 7 of the table.
ITEM_7_PRICE (702)
Data Type: MONEY. The price (money with currency) of item 7 of the table, e.g., 30 USD. The currency must match one of the available currencies.
ITEM_7_UNIT (703)
Data Type: STRING. The price unit of item 7 of the table. Must match one of the predefined price units.
ITEM_7_FINAL_URLS (704)
Data Type: URL_LIST. The final URLs of item 7 of the table when using Upgraded URLs.
ITEM_7_FINAL_MOBILE_URLS (705)
Data Type: URL_LIST. The final mobile URLs of item 7 of the table when using Upgraded URLs.
ITEM_8_HEADER (800)
Data Type: STRING. The header of item 8 of the table.
ITEM_8_DESCRIPTION (801)
Data Type: STRING. The description of item 8 of the table.
ITEM_8_PRICE (802)
Data Type: MONEY. The price (money with currency) of item 8 of the table, e.g., 30 USD. The currency must match one of the available currencies.
ITEM_8_UNIT (803)
Data Type: STRING. The price unit of item 8 of the table. Must match one of the predefined price units.
ITEM_8_FINAL_URLS (804)
Data Type: URL_LIST. The final URLs of item 8 of the table when using Upgraded URLs.
ITEM_8_FINAL_MOBILE_URLS (805)
Data Type: URL_LIST. The final mobile URLs of item 8 of the table when using Upgraded URLs.

promotion_field enum

Immutable. Promotion Placeholder Fields.

real_estate_field enum

Immutable. Real Estate Placeholder Fields

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
LISTING_ID (2)
Data Type: STRING. Unique ID.
LISTING_NAME (3)
Data Type: STRING. Main headline with listing name to be shown in dynamic ad.
CITY_NAME (4)
Data Type: STRING. City name to be shown in dynamic ad.
DESCRIPTION (5)
Data Type: STRING. Description of listing to be shown in dynamic ad.
ADDRESS (6)
Data Type: STRING. Complete listing address, including postal code.
PRICE (7)
Data Type: STRING. Price to be shown in the ad. Example: "100.00 USD"
FORMATTED_PRICE (8)
Data Type: STRING. Formatted price to be shown in the ad. Example: "Starting at $100.00 USD", "$80 - $100"
IMAGE_URL (9)
Data Type: URL. Image to be displayed in the ad.
PROPERTY_TYPE (10)
Data Type: STRING. Type of property (house, condo, apartment, etc.) used to group like items together for recommendation engine.
LISTING_TYPE (11)
Data Type: STRING. Type of listing (resale, rental, foreclosure, etc.) used to group like items together for recommendation engine.
CONTEXTUAL_KEYWORDS (12)
Data Type: STRING_LIST. Keywords used for product retrieval.
FINAL_URLS (13)
Data Type: URL_LIST. Final URLs to be used in ad when using Upgraded URLs; the more specific the better (e.g. the individual URL of a specific listing and its location).
FINAL_MOBILE_URLS (14)
Data Type: URL_LIST. Final mobile URLs for the ad when using Upgraded URLs.
TRACKING_URL (15)
Data Type: URL. Tracking template for the ad when using Upgraded URLs.
ANDROID_APP_LINK (16)
Data Type: STRING. Android app link. Must be formatted as: android-app://{package_id}/{scheme}/{host_path}. The components are defined as follows: package_id: app ID as specified in Google Play. scheme: the scheme to pass to the application. Can be HTTP, or a custom scheme. host_path: identifies the specific content within your application.
SIMILAR_LISTING_IDS (17)
Data Type: STRING_LIST. List of recommended listing IDs to show together with this item.
IOS_APP_LINK (18)
Data Type: STRING. iOS app link.
IOS_APP_STORE_ID (19)
Data Type: INT64. iOS app store ID.

sitelink_field enum

Immutable. Sitelink Placeholder Fields.

structured_snippet_field enum

Immutable. Structured Snippet Placeholder Fields.

travel_field enum

Immutable. Travel Placeholder Fields

UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
DESTINATION_ID (2)
Data Type: STRING. Required. Destination id. Example: PAR, LON. For feed items that only have destination id, destination id must be a unique key. For feed items that have both destination id and origin id, then the combination must be a unique key.
ORIGIN_ID (3)
Data Type: STRING. Origin id. Example: PAR, LON. Combination of DESTINATION_ID and ORIGIN_ID must be unique per offer.
TITLE (4)
Data Type: STRING. Required. Main headline with name to be shown in dynamic ad.
DESTINATION_NAME (5)
Data Type: STRING. The destination name. Shorter names are recommended.
ORIGIN_NAME (6)
Data Type: STRING. Origin name. Shorter names are recommended.
PRICE (7)
Data Type: STRING. Price to be shown in the ad. Highly recommended for dynamic ads. Example: "100.00 USD"
FORMATTED_PRICE (8)
Data Type: STRING. Formatted price to be shown in the ad. Example: "Starting at $100.00 USD", "$80 - $100"
SALE_PRICE (9)
Data Type: STRING. Sale price to be shown in the ad. Example: "80.00 USD"
FORMATTED_SALE_PRICE (10)
Data Type: STRING. Formatted sale price to be shown in the ad. Example: "On sale for $80.00", "$60 - $80"
IMAGE_URL (11)
Data Type: URL. Image to be displayed in the ad.
CATEGORY (12)
Data Type: STRING. Category of travel offer used to group like items together for recommendation engine.
CONTEXTUAL_KEYWORDS (13)
Data Type: STRING_LIST. Keywords used for product retrieval.
DESTINATION_ADDRESS (14)
Data Type: STRING. Address of travel offer, including postal code.
FINAL_URL (15)
Data Type: URL_LIST. Required. Final URLs to be used in ad, when using Upgraded URLs; the more specific the better (e.g. the individual URL of a specific travel offer and its location).
FINAL_MOBILE_URLS (16)
Data Type: URL_LIST. Final mobile URLs for the ad when using Upgraded URLs.
TRACKING_URL (17)
Data Type: URL. Tracking template for the ad when using Upgraded URLs.
ANDROID_APP_LINK (18)
Data Type: STRING. Android app link. Must be formatted as: android-app://{package_id}/{scheme}/{host_path}. The components are defined as follows: package_id: app ID as specified in Google Play. scheme: the scheme to pass to the application. Can be HTTP, or a custom scheme. host_path: identifies the specific content within your application.
SIMILAR_DESTINATION_IDS (19)
Data Type: STRING_LIST. List of recommended destination IDs to show together with this item.
IOS_APP_LINK (20)
Data Type: STRING. iOS app link.
IOS_APP_STORE_ID (21)
Data Type: INT64. iOS app store ID.

feed string

Immutable. The feed of this feed mapping.

resource_name string

Immutable. The resource name of the feed mapping. Feed mapping resource names have the form: customers/{customer_id}/feedMappings/{feed_id}~{feed_mapping_id}

status enum

Output only. Status of the feed mapping. This field is read-only.

// Example FeedMapping
const feed_mapping = {
  attribute_field_mappings: [
    {
      feed_attribute_id: 1,
      field_id: 1,
      sitelink_field: 2,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 2,
      field_id: 2,
      sitelink_field: 1,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 3,
      field_id: 3,
      sitelink_field: 3,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 4,
      field_id: 4,
      sitelink_field: 4,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 5,
      field_id: 5,
      sitelink_field: 5,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 6,
      field_id: 6,
      sitelink_field: 6,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 7,
      field_id: 7,
      sitelink_field: 7,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 8,
      field_id: 8,
      sitelink_field: 8,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
  ],
  criterion_type: 0,
  feed: 'customers/9262111890/feeds/82896692',
  placeholder_type: 2,
  resource_name: 'customers/9262111890/feedMappings/82896692~91300060',
  status: 2,
}

Get a FeedMapping

The customer.feedMappings.get(resource_name) method returns the FeedMapping identified by a resource_name.

Arguments

resource_name required

The resource_name of that FeedMapping

Returns

Returns that FeedMapping as an object.

// Getting the entity
let result = await customer.feedMappings.get('customers/9262111890/feedMappings/82896692~91300060')

// Example result
;({
  attribute_field_mappings: [
    {
      feed_attribute_id: 1,
      field_id: 1,
      sitelink_field: 2,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 2,
      field_id: 2,
      sitelink_field: 1,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 3,
      field_id: 3,
      sitelink_field: 3,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 4,
      field_id: 4,
      sitelink_field: 4,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 5,
      field_id: 5,
      sitelink_field: 5,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 6,
      field_id: 6,
      sitelink_field: 6,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 7,
      field_id: 7,
      sitelink_field: 7,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
    {
      feed_attribute_id: 8,
      field_id: 8,
      sitelink_field: 8,
      call_field: 0,
      app_field: 0,
      location_field: 0,
      affiliate_location_field: 0,
      callout_field: 0,
      structured_snippet_field: 0,
      message_field: 0,
      price_field: 0,
      promotion_field: 0,
      ad_customizer_field: 0,
      dsa_page_feed_field: 0,
      location_extension_targeting_field: 0,
      education_field: 0,
      flight_field: 0,
      custom_field: 0,
      hotel_field: 0,
      real_estate_field: 0,
      travel_field: 0,
      local_field: 0,
      job_field: 0,
    },
  ],
  criterion_type: 0,
  feed: 'customers/9262111890/feeds/82896692',
  placeholder_type: 2,
  resource_name: 'customers/9262111890/feedMappings/82896692~91300060',
  status: 2,
})

List every instance of FeedMapping

The customer.feedMappings.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 FeedMapping.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.feedMappings.list({
  constraints: [
    {
      key: 'feed_mapping.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'feed_mapping.some_field.sub_field',
})

// Example result
;[
  {
    feed_mapping: {
      attribute_field_mappings: [
        {
          feed_attribute_id: 1,
          field_id: 1,
          sitelink_field: 2,
          call_field: 0,
          app_field: 0,
          location_field: 0,
          affiliate_location_field: 0,
          callout_field: 0,
          structured_snippet_field: 0,
          message_field: 0,
          price_field: 0,
          promotion_field: 0,
          ad_customizer_field: 0,
          dsa_page_feed_field: 0,
          location_extension_targeting_field: 0,
          education_field: 0,
          flight_field: 0,
          custom_field: 0,
          hotel_field: 0,
          real_estate_field: 0,
          travel_field: 0,
          local_field: 0,
          job_field: 0,
        },
        {
          feed_attribute_id: 2,
          field_id: 2,
          sitelink_field: 1,
          call_field: 0,
          app_field: 0,
          location_field: 0,
          affiliate_location_field: 0,
          callout_field: 0,
          structured_snippet_field: 0,
          message_field: 0,
          price_field: 0,
          promotion_field: 0,
          ad_customizer_field: 0,
          dsa_page_feed_field: 0,
          location_extension_targeting_field: 0,
          education_field: 0,
          flight_field: 0,
          custom_field: 0,
          hotel_field: 0,
          real_estate_field: 0,
          travel_field: 0,
          local_field: 0,
          job_field: 0,
        },
        {
          feed_attribute_id: 3,
          field_id: 3,
          sitelink_field: 3,
          call_field: 0,
          app_field: 0,
          location_field: 0,
          affiliate_location_field: 0,
          callout_field: 0,
          structured_snippet_field: 0,
          message_field: 0,
          price_field: 0,
          promotion_field: 0,
          ad_customizer_field: 0,
          dsa_page_feed_field: 0,
          location_extension_targeting_field: 0,
          education_field: 0,
          flight_field: 0,
          custom_field: 0,
          hotel_field: 0,
          real_estate_field: 0,
          travel_field: 0,
          local_field: 0,
          job_field: 0,
        },
        {
          feed_attribute_id: 4,
          field_id: 4,
          sitelink_field: 4,
          call_field: 0,
          app_field: 0,
          location_field: 0,
          affiliate_location_field: 0,
          callout_field: 0,
          structured_snippet_field: 0,
          message_field: 0,
          price_field: 0,
          promotion_field: 0,
          ad_customizer_field: 0,
          dsa_page_feed_field: 0,
          location_extension_targeting_field: 0,
          education_field: 0,
          flight_field: 0,
          custom_field: 0,
          hotel_field: 0,
          real_estate_field: 0,
          travel_field: 0,
          local_field: 0,
          job_field: 0,
        },
        {
          feed_attribute_id: 5,
          field_id: 5,
          sitelink_field: 5,
          call_field: 0,
          app_field: 0,
          location_field: 0,
          affiliate_location_field: 0,
          callout_field: 0,
          structured_snippet_field: 0,
          message_field: 0,
          price_field: 0,
          promotion_field: 0,
          ad_customizer_field: 0,
          dsa_page_feed_field: 0,
          location_extension_targeting_field: 0,
          education_field: 0,
          flight_field: 0,
          custom_field: 0,
          hotel_field: 0,
          real_estate_field: 0,
          travel_field: 0,
          local_field: 0,
          job_field: 0,
        },
        {
          feed_attribute_id: 6,
          field_id: 6,
          sitelink_field: 6,
          call_field: 0,
          app_field: 0,
          location_field: 0,
          affiliate_location_field: 0,
          callout_field: 0,
          structured_snippet_field: 0,
          message_field: 0,
          price_field: 0,
          promotion_field: 0,
          ad_customizer_field: 0,
          dsa_page_feed_field: 0,
          location_extension_targeting_field: 0,
          education_field: 0,
          flight_field: 0,
          custom_field: 0,
          hotel_field: 0,
          real_estate_field: 0,
          travel_field: 0,
          local_field: 0,
          job_field: 0,
        },
        {
          feed_attribute_id: 7,
          field_id: 7,
          sitelink_field: 7,
          call_field: 0,
          app_field: 0,
          location_field: 0,
          affiliate_location_field: 0,
          callout_field: 0,
          structured_snippet_field: 0,
          message_field: 0,
          price_field: 0,
          promotion_field: 0,
          ad_customizer_field: 0,
          dsa_page_feed_field: 0,
          location_extension_targeting_field: 0,
          education_field: 0,
          flight_field: 0,
          custom_field: 0,
          hotel_field: 0,
          real_estate_field: 0,
          travel_field: 0,
          local_field: 0,
          job_field: 0,
        },
        {
          feed_attribute_id: 8,
          field_id: 8,
          sitelink_field: 8,
          call_field: 0,
          app_field: 0,
          location_field: 0,
          affiliate_location_field: 0,
          callout_field: 0,
          structured_snippet_field: 0,
          message_field: 0,
          price_field: 0,
          promotion_field: 0,
          ad_customizer_field: 0,
          dsa_page_feed_field: 0,
          location_extension_targeting_field: 0,
          education_field: 0,
          flight_field: 0,
          custom_field: 0,
          hotel_field: 0,
          real_estate_field: 0,
          travel_field: 0,
          local_field: 0,
          job_field: 0,
        },
      ],
      criterion_type: 0,
      feed: 'customers/9262111890/feeds/82896692',
      placeholder_type: 2,
      resource_name: 'customers/9262111890/feedMappings/82896692~91300060',
      status: 2,
    },
    feed: {
      attributes: [
        { id: 1, name: 'SitelinkName', type: 4, is_part_of_key: false },
        { id: 2, name: 'SitelinkUrl', type: 6, is_part_of_key: false },
        { id: 3, name: 'SitelinkDescription1', type: 4, is_part_of_key: false },
        { id: 4, name: 'SitelinkDescription2', type: 4, is_part_of_key: false },
        { id: 5, name: 'SitelinkFinalUrls', type: 12, is_part_of_key: false },
        { id: 6, name: 'SitelinkFinalMobileUrls', type: 12, is_part_of_key: false },
        { id: 7, name: 'SitelinkTrackingUrl', type: 6, is_part_of_key: false },
        { id: 8, name: 'SitelinkFinalUrlSuffix', type: 4, is_part_of_key: false },
      ],
      id: 82896692,
      name: 'My feed',
      origin: 3,
      resource_name: 'customers/9262111890/feeds/82896692',
      status: 2,
    },
    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 a FeedMapping

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.feedMappings.create([feed_mapping, other_feed_mapping], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/feedMappings/82896692~91300060'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a FeedMapping

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

Arguments

entity required

The FeedMapping 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 feed_mapping = {
  resource_name: 'customers/9262111890/feedMappings/82896692~91300060', // 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.feedMappings.update(feed_mapping)

// Passing in an array of entities to update, validating only
const result = await customer.feedMappings.update([feed_mapping, other_feed_mapping], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/feedMappings/82896692~91300060'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a FeedMapping

The customer.feedMappings.delete(resource_name) sets the status field of a FeedMapping 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 FeedMapping

Returns

Nothing

// Deleting the entity

await customer.feedMappings.delete('customers/9262111890/feedMappings/82896692~91300060')

GeoTargetConstant

The GeoTargetConstant object

Fields

canonical_name string

Output only. The fully qualified English name, consisting of the target's name and that of its parent and country.

country_code string

Output only. The ISO-3166-1 alpha-2 country code that is associated with the target.

id int64

Output only. The ID of the geo target constant.

name string

Output only. Geo target constant English name.

resource_name string

Output only. The resource name of the geo target constant. Geo target constant resource names have the form: geoTargetConstants/{geo_target_constant_id}

status enum

Output only. Geo target constant status.

target_type string

Output only. Geo target constant target type.

// Example GeoTargetConstant
const geo_target_constant = {
  canonical_name: 'South Georgia and the South Sandwich Islands',
  country_code: 'GS',
  id: 2239,
  name: 'South Georgia and the South Sandwich Islands',
  resource_name: 'geoTargetConstants/2239',
  status: 2,
  target_type: 'Country',
}

Get a GeoTargetConstant

The customer.geoTargetConstants.get(resource_name) method returns the GeoTargetConstant identified by a resource_name.

Arguments

resource_name required

The resource_name of that GeoTargetConstant

Returns

Returns that GeoTargetConstant as an object.

// Getting the entity
let result = await customer.geoTargetConstants.get('geoTargetConstants/2239')

// Example result
;({
  canonical_name: 'South Georgia and the South Sandwich Islands',
  country_code: 'GS',
  id: 2239,
  name: 'South Georgia and the South Sandwich Islands',
  resource_name: 'geoTargetConstants/2239',
  status: 2,
  target_type: 'Country',
})

List every instance of GeoTargetConstant

The customer.geoTargetConstants.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 GeoTargetConstant.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.geoTargetConstants.list({
  constraints: [
    {
      key: 'geo_target_constant.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'geo_target_constant.some_field.sub_field',
})

// Example result
;[
  {
    geo_target_constant: {
      canonical_name: 'South Georgia and the South Sandwich Islands',
      country_code: 'GS',
      id: 2239,
      name: 'South Georgia and the South Sandwich Islands',
      resource_name: 'geoTargetConstants/2239',
      status: 2,
      target_type: 'Country',
    },
  },
]

Get GeoTargetConstant Suggestions

The customer.geoTargetConstants.suggest() method returns geo target constant suggestion.

Arguments

locale optional

If possible, returned geo targets are translated using this locale. If not, en is used by default. This is also used as a hint for returned geo targets.
country_code optional

Returned geo targets are restricted to this country code.
location_names optional, array/object

The location names to search by. At most 25 names can be set.
geo_targets optional, array/object

The geo target constant resource names to filter by.

Returns

Returns an array of objects. Each object has locale, reach, search_term, geo_target_constant and geo_target_constant_parents[] properties.

// Get geo target constant suggestions
let result = await customer.geoTargetConstants.suggest({
  locale: 'en',
  country_code: 'GB',
  location_names: { names: ['London'] },
})

// Example result
;[
  {
    locale: 'en',
    reach: 32000000,
    search_term: 'London',
    geo_target_constant: {
      resource_name: 'geoTargetConstants/1006886',
      id: 1006886,
      name: 'London',
      country_code: 'GB',
      target_type: 'City',
      status: 2,
      canonical_name: 'London,England,United Kingdom',
    },
    geo_target_constant_parents_list: [
      {
        resource_name: 'geoTargetConstants/20339',
        id: 20339,
        name: 'England',
        country_code: 'GB',
        target_type: 'Province',
        status: 2,
      },
      {
        resource_name: 'geoTargetConstants/2826',
        id: 2826,
        name: 'United Kingdom',
        country_code: 'GB',
        target_type: 'Country',
        status: 2,
      },
    ],
  },
]

KeywordPlan

The KeywordPlan object

Fields

forecast_period object

The date period used for forecasting the plan.

id int64

Output only. The ID of the keyword plan.

name string

The name of the keyword plan. This field is required and should not be empty when creating new keyword plans.

resource_name string

Immutable. The resource name of the Keyword Planner plan. KeywordPlan resource names have the form: customers/{customer_id}/keywordPlans/{kp_plan_id}

// Example KeywordPlan
const keyword_plan = {
  forecast_period: { date_interval: 4 },
  id: 115113466,
  name: 'My keyword plan',
  resource_name: 'customers/9262111890/keywordPlans/115113466',
}

Get a KeywordPlan

The customer.keywordPlans.get(resource_name) method returns the KeywordPlan identified by a resource_name.

Arguments

resource_name required

The resource_name of that KeywordPlan

Returns

Returns that KeywordPlan as an object.

// Getting the entity
let result = await customer.keywordPlans.get('customers/9262111890/keywordPlans/115113466')

// Example result
;({
  forecast_period: { date_interval: 4 },
  id: 115113466,
  name: 'My keyword plan',
  resource_name: 'customers/9262111890/keywordPlans/115113466',
})

List every instance of KeywordPlan

The customer.keywordPlans.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 KeywordPlan.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.keywordPlans.list({
  constraints: [
    {
      key: 'keyword_plan.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'keyword_plan.some_field.sub_field',
})

// Example result
;[
  {
    keyword_plan: {
      forecast_period: { date_interval: 4 },
      id: 115113466,
      name: 'My keyword plan',
      resource_name: 'customers/9262111890/keywordPlans/115113466',
    },
    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 a KeywordPlan

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.keywordPlans.create([keyword_plan, other_keyword_plan], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/keywordPlans/115113466'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a KeywordPlan

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

Arguments

entity required

The KeywordPlan 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 keyword_plan = {
  resource_name: 'customers/9262111890/keywordPlans/115113466', // 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.keywordPlans.update(keyword_plan)

// Passing in an array of entities to update, validating only
const result = await customer.keywordPlans.update([keyword_plan, other_keyword_plan], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/keywordPlans/115113466'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a KeywordPlan

The customer.keywordPlans.delete(resource_name) sets the status field of a KeywordPlan 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 KeywordPlan

Returns

Nothing

// Deleting the entity

await customer.keywordPlans.delete('customers/9262111890/keywordPlans/115113466')

KeywordPlanAdGroup

The KeywordPlanAdGroup object

Fields

cpc_bid_micros int64

A default ad group max cpc bid in micros in account currency for all biddable keywords under the keyword plan ad group. If not set, will inherit from parent campaign.

id int64

Output only. The ID of the keyword plan ad group.

keyword_plan_campaign string

The keyword plan campaign to which this ad group belongs.

name string

The name of the keyword plan ad group. This field is required and should not be empty when creating keyword plan ad group.

resource_name string

Immutable. The resource name of the Keyword Planner ad group. KeywordPlanAdGroup resource names have the form: customers/{customer_id}/keywordPlanAdGroups/{kp_ad_group_id}

// Example KeywordPlanAdGroup
const keyword_plan_ad_group = {
  cpc_bid_micros: 2500000,
  id: 104819196,
  keyword_plan_campaign: 'customers/9262111890/keywordPlanCampaigns/115088623',
  name: 'My keyword plan ad group',
  resource_name: 'customers/9262111890/keywordPlanAdGroups/104819196',
}

Get a KeywordPlanAdGroup

The customer.keywordPlanAdGroups.get(resource_name) method returns the KeywordPlanAdGroup identified by a resource_name.

Arguments

resource_name required

The resource_name of that KeywordPlanAdGroup

Returns

Returns that KeywordPlanAdGroup as an object.

// Getting the entity
let result = await customer.keywordPlanAdGroups.get('customers/9262111890/keywordPlanAdGroups/104819196')

// Example result
;({
  cpc_bid_micros: 2500000,
  id: 104819196,
  keyword_plan_campaign: 'customers/9262111890/keywordPlanCampaigns/115088623',
  name: 'My keyword plan ad group',
  resource_name: 'customers/9262111890/keywordPlanAdGroups/104819196',
})

List every instance of KeywordPlanAdGroup

The customer.keywordPlanAdGroups.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 KeywordPlanAdGroup.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.keywordPlanAdGroups.list({
  constraints: [
    {
      key: 'keyword_plan_ad_group.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'keyword_plan_ad_group.some_field.sub_field',
})

// Example result
;[
  {
    keyword_plan_ad_group: {
      cpc_bid_micros: 2500000,
      id: 104819196,
      keyword_plan_campaign: 'customers/9262111890/keywordPlanCampaigns/115088623',
      name: 'My keyword plan ad group',
      resource_name: 'customers/9262111890/keywordPlanAdGroups/104819196',
    },
    keyword_plan: {
      forecast_period: { date_interval: 4 },
      id: 115133472,
      name: 'My keyword plan',
      resource_name: 'customers/9262111890/keywordPlans/115133472',
    },
    keyword_plan_campaign: {
      cpc_bid_micros: 1000000,
      geo_targets: [{ geo_target_constant: 'geoTargetConstants/1021278' }],
      id: 115088623,
      keyword_plan: 'customers/9262111890/keywordPlans/115133472',
      keyword_plan_network: 2,
      language_constants: ['languageConstants/1000'],
      name: 'My keyword plan campaign',
      resource_name: 'customers/9262111890/keywordPlanCampaigns/115088623',
    },
    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 a KeywordPlanAdGroup

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.keywordPlanAdGroups.create([keyword_plan_ad_group, other_keyword_plan_ad_group], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/keywordPlanAdGroups/104819196'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a KeywordPlanAdGroup

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

Arguments

entity required

The KeywordPlanAdGroup 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 keyword_plan_ad_group = {
  resource_name: 'customers/9262111890/keywordPlanAdGroups/104819196', // 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.keywordPlanAdGroups.update(keyword_plan_ad_group)

// Passing in an array of entities to update, validating only
const result = await customer.keywordPlanAdGroups.update([keyword_plan_ad_group, other_keyword_plan_ad_group], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/keywordPlanAdGroups/104819196'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a KeywordPlanAdGroup

The customer.keywordPlanAdGroups.delete(resource_name) sets the status field of a KeywordPlanAdGroup 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 KeywordPlanAdGroup

Returns

Nothing

// Deleting the entity

await customer.keywordPlanAdGroups.delete('customers/9262111890/keywordPlanAdGroups/104819196')

KeywordPlanCampaign

The KeywordPlanCampaign object

Fields

cpc_bid_micros int64

A default max cpc bid in micros, and in the account currency, for all ad groups under the campaign. This field is required and should not be empty when creating Keyword Plan campaigns.

geo_targets array of objects

The geo targets. Max number allowed: 20.

id int64

Output only. The ID of the Keyword Plan campaign.

keyword_plan string

The keyword plan this campaign belongs to.

keyword_plan_network enum

Targeting network. This field is required and should not be empty when creating Keyword Plan campaigns.

language_constants array of strings

The languages targeted for the Keyword Plan campaign. Max allowed: 1.

name string

The name of the Keyword Plan campaign. This field is required and should not be empty when creating Keyword Plan campaigns.

resource_name string

Immutable. The resource name of the Keyword Plan campaign. KeywordPlanCampaign resource names have the form: customers/{customer_id}/keywordPlanCampaigns/{kp_campaign_id}

// Example KeywordPlanCampaign
const keyword_plan_campaign = {
  cpc_bid_micros: 1000000,
  geo_targets: [{ geo_target_constant: 'geoTargetConstants/1021278' }],
  id: 115088623,
  keyword_plan: 'customers/9262111890/keywordPlans/115133472',
  keyword_plan_network: 2,
  language_constants: ['languageConstants/1000'],
  name: 'My keyword plan campaign',
  resource_name: 'customers/9262111890/keywordPlanCampaigns/115088623',
}

Get a KeywordPlanCampaign

The customer.keywordPlanCampaigns.get(resource_name) method returns the KeywordPlanCampaign identified by a resource_name.

Arguments

resource_name required

The resource_name of that KeywordPlanCampaign

Returns

Returns that KeywordPlanCampaign as an object.

// Getting the entity
let result = await customer.keywordPlanCampaigns.get('customers/9262111890/keywordPlanCampaigns/115088623')

// Example result
;({
  cpc_bid_micros: 1000000,
  geo_targets: [{ geo_target_constant: 'geoTargetConstants/1021278' }],
  id: 115088623,
  keyword_plan: 'customers/9262111890/keywordPlans/115133472',
  keyword_plan_network: 2,
  language_constants: ['languageConstants/1000'],
  name: 'My keyword plan campaign',
  resource_name: 'customers/9262111890/keywordPlanCampaigns/115088623',
})

List every instance of KeywordPlanCampaign

The customer.keywordPlanCampaigns.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 KeywordPlanCampaign.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.keywordPlanCampaigns.list({
  constraints: [
    {
      key: 'keyword_plan_campaign.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'keyword_plan_campaign.some_field.sub_field',
})

// Example result
;[
  {
    keyword_plan_campaign: {
      cpc_bid_micros: 1000000,
      geo_targets: [{ geo_target_constant: 'geoTargetConstants/1021278' }],
      id: 115088623,
      keyword_plan: 'customers/9262111890/keywordPlans/115133472',
      keyword_plan_network: 2,
      language_constants: ['languageConstants/1000'],
      name: 'My keyword plan campaign',
      resource_name: 'customers/9262111890/keywordPlanCampaigns/115088623',
    },
    keyword_plan: {
      forecast_period: { date_interval: 4 },
      id: 115133472,
      name: 'My keyword plan',
      resource_name: 'customers/9262111890/keywordPlans/115133472',
    },
    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 a KeywordPlanCampaign

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.keywordPlanCampaigns.create([keyword_plan_campaign, other_keyword_plan_campaign], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/keywordPlanCampaigns/115088623'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a KeywordPlanCampaign

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

Arguments

entity required

The KeywordPlanCampaign 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 keyword_plan_campaign = {
  resource_name: 'customers/9262111890/keywordPlanCampaigns/115088623', // 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.keywordPlanCampaigns.update(keyword_plan_campaign)

// Passing in an array of entities to update, validating only
const result = await customer.keywordPlanCampaigns.update([keyword_plan_campaign, other_keyword_plan_campaign], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/keywordPlanCampaigns/115088623'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a KeywordPlanCampaign

The customer.keywordPlanCampaigns.delete(resource_name) sets the status field of a KeywordPlanCampaign 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 KeywordPlanCampaign

Returns

Nothing

// Deleting the entity

await customer.keywordPlanCampaigns.delete('customers/9262111890/keywordPlanCampaigns/115088623')

KeywordPlanKeyword

The KeywordPlanKeyword object

Fields

cpc_bid_micros int64

A keyword level max cpc bid in micros, in the account currency, that overrides the keyword plan ad group cpc bid.

id int64

Output only. The ID of the Keyword Plan keyword.

keyword_plan_ad_group string

The Keyword Plan ad group to which this keyword belongs.

match_type enum

The keyword match type.

resource_name string

Immutable. The resource name of the Keyword Plan ad group keyword. KeywordPlanKeyword resource names have the form: customers/{customer_id}/keywordPlanKeywords/{kp_ad_group_keyword_id}

text string

The keyword text.

// Example KeywordPlanKeyword
const keyword_plan_keyword = /* Todo: add example get() return here */

Get a KeywordPlanKeyword

The customer.keywordPlanKeywords.get(resource_name) method returns the KeywordPlanKeyword identified by a resource_name.

Arguments

resource_name required

The resource_name of that KeywordPlanKeyword

Returns

Returns that KeywordPlanKeyword as an object.

// Getting the entity
let result = await customer.keywordPlanKeywords.get('customers/1234567890/keywordPlanKeywords/123123123')

// Example result
(/* Todo: add example get() return here */)

List every instance of KeywordPlanKeyword

The customer.keywordPlanKeywords.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 KeywordPlanKeyword.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.keywordPlanKeywords.list({
  constraints: [
    {
      key: 'keyword_plan_keyword.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'keyword_plan_keyword.some_field.sub_field',
})

// Example result
;[
  /* Todo: add example list() return here */
]

Create a KeywordPlanKeyword

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.keywordPlanKeywords.create([keyword_plan_keyword, other_keyword_plan_keyword], {
  validate_only: true,
})

// Example result
{
	results : ['customers/1234567890/keywordPlanKeywords/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a KeywordPlanKeyword

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

Arguments

entity required

The KeywordPlanKeyword 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 keyword_plan_keyword = {
  resource_name: 'customers/1234567890/keywordPlanKeywords/123123123', // 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.keywordPlanKeywords.update(keyword_plan_keyword)

// Passing in an array of entities to update, validating only
const result = await customer.keywordPlanKeywords.update([keyword_plan_keyword, other_keyword_plan_keyword], {
  validate_only: true,
})

// Example result
{
	results : ['customers/1234567890/keywordPlanKeywords/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a KeywordPlanKeyword

The customer.keywordPlanKeywords.delete(resource_name) sets the status field of a KeywordPlanKeyword 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 KeywordPlanKeyword

Returns

Nothing

// Deleting the entity

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

KeywordPlanNegativeKeyword

The KeywordPlanNegativeKeyword object

Fields

id int64

Output only. The ID of the Keyword Plan negative keyword.

keyword_plan_campaign string

The Keyword Plan campaign to which this negative keyword belongs.

match_type enum

The keyword match type.

resource_name string

Immutable. The resource name of the Keyword Plan negative keyword. KeywordPlanNegativeKeyword resource names have the form: customers/{customer_id}/keywordPlanNegativeKeywords/{kp_negative_keyword_id}

text string

The keyword text.

// Example KeywordPlanNegativeKeyword
const keyword_plan_negative_keyword = {
  id: 13119148,
  keyword_plan_campaign: 'customers/9262111890/keywordPlanCampaigns/115088623',
  match_type: 4,
  resource_name: 'customers/9262111890/keywordPlanNegativeKeywords/13119148',
  text: 'moon walk',
}

Get a KeywordPlanNegativeKeyword

The customer.keywordPlanNegativeKeywords.get(resource_name) method returns the KeywordPlanNegativeKeyword identified by a resource_name.

Arguments

resource_name required

The resource_name of that KeywordPlanNegativeKeyword

Returns

Returns that KeywordPlanNegativeKeyword as an object.

// Getting the entity
let result = await customer.keywordPlanNegativeKeywords.get('customers/9262111890/keywordPlanNegativeKeywords/13119148')

// Example result
;({
  id: 13119148,
  keyword_plan_campaign: 'customers/9262111890/keywordPlanCampaigns/115088623',
  match_type: 4,
  resource_name: 'customers/9262111890/keywordPlanNegativeKeywords/13119148',
  text: 'moon walk',
})

List every instance of KeywordPlanNegativeKeyword

The customer.keywordPlanNegativeKeywords.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 KeywordPlanNegativeKeyword.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.keywordPlanNegativeKeywords.list({
  constraints: [
    {
      key: 'keyword_plan_negative_keyword.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'keyword_plan_negative_keyword.some_field.sub_field',
})

// Example result
;[
  {
    keyword_plan_negative_keyword: {
      id: 13119148,
      keyword_plan_campaign: 'customers/9262111890/keywordPlanCampaigns/115088623',
      match_type: 4,
      resource_name: 'customers/9262111890/keywordPlanNegativeKeywords/13119148',
      text: 'moon walk',
    },
    keyword_plan: {
      forecast_period: { date_interval: 4 },
      id: 115133472,
      name: 'My keyword plan',
      resource_name: 'customers/9262111890/keywordPlans/115133472',
    },
    keyword_plan_campaign: {
      cpc_bid_micros: 1000000,
      geo_targets: [{ geo_target_constant: 'geoTargetConstants/1021278' }],
      id: 115088623,
      keyword_plan: 'customers/9262111890/keywordPlans/115133472',
      keyword_plan_network: 2,
      language_constants: ['languageConstants/1000'],
      name: 'My keyword plan campaign',
      resource_name: 'customers/9262111890/keywordPlanCampaigns/115088623',
    },
    customer: {
      auto_tagging_enabled: false,
      call_reporting_setting: {
        call_conversion_action: 'customers/9262111890/conversionActions/179',
        call_conversion_reporting_enabled: true,
      },
      conversion_tracking_setting: { conversion_tracking_id: 797556569 },
      currency_code: 'EUR',
      descriptive_name: 'My customer',
      has_partners_badge: false,
      id: 9262111890,
      manager: false,
      pay_per_conversion_eligibility_failure_reasons: [8, 2],
      remarketing_setting: {
        google_global_site_tag:
          "<!-- Global site tag (gtag.js) - Google Ads: 797556569 -->\n<script async src=\"https://www.googletagmanager.com/gtag/js?id=AW-797556569\"></script>\n<script>\n  window.dataLayer = window.dataLayer || [];\n  function gtag(){dataLayer.push(arguments);}\n  gtag('js', new Date());\n\n  gtag('config', 'AW-797556569');\n</script>\n",
      },
      resource_name: 'customers/9262111890',
      test_account: true,
      time_zone: 'Europe/London',
    },
  },
]

Create a KeywordPlanNegativeKeyword

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.keywordPlanNegativeKeywords.create(
  [keyword_plan_negative_keyword, other_keyword_plan_negative_keyword],
  {
    validate_only: true,
  }
)

// Example result
{
	results : ['customers/9262111890/keywordPlanNegativeKeywords/13119148'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a KeywordPlanNegativeKeyword

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

Arguments

entity required

The KeywordPlanNegativeKeyword 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 keyword_plan_negative_keyword = {
  resource_name: 'customers/9262111890/keywordPlanNegativeKeywords/13119148', // 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.keywordPlanNegativeKeywords.update(keyword_plan_negative_keyword)

// Passing in an array of entities to update, validating only
const result = await customer.keywordPlanNegativeKeywords.update(
  [keyword_plan_negative_keyword, other_keyword_plan_negative_keyword],
  {
    validate_only: true,
  }
)

// Example result
{
	results : ['customers/9262111890/keywordPlanNegativeKeywords/13119148'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a KeywordPlanNegativeKeyword

The customer.keywordPlanNegativeKeywords.delete(resource_name) sets the status field of a KeywordPlanNegativeKeyword 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 KeywordPlanNegativeKeyword

Returns

Nothing

// Deleting the entity

await customer.keywordPlanNegativeKeywords.delete('customers/9262111890/keywordPlanNegativeKeywords/13119148')

Label

The Label object

Fields

id int64

Output only. Id of the label. Read only.

name string

The name of the label. This field is required and should not be empty when creating a new label. The length of this string should be between 1 and 80, inclusive.

resource_name string

Immutable. Name of the resource. Label resource names have the form: customers/{customer_id}/labels/{label_id}

status enum

Output only. Status of the label. Read only.

text_label object

A type of label displaying text on a colored background.

// Example Label
const label = {
  id: 3345231412,
  name: 'My label',
  resource_name: 'customers/3827277046/labels/3345231412',
  status: 2,
  text_label: { background_color: '#e993eb', description: 'Adgroups where Chloe will write new ads that kick butt.' },
}

Get a Label

The customer.labels.get(resource_name) method returns the Label identified by a resource_name.

Arguments

resource_name required

The resource_name of that Label

Returns

Returns that Label as an object.

// Getting the entity
let result = await customer.labels.get('customers/3827277046/labels/3345231412')

// Example result
;({
  id: 3345231412,
  name: 'My label',
  resource_name: 'customers/3827277046/labels/3345231412',
  status: 2,
  text_label: { background_color: '#e993eb', description: 'Adgroups where Chloe will write new ads that kick butt.' },
})

List every instance of Label

The customer.labels.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 Label.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.labels.list({
  constraints: [
    {
      key: 'label.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'label.some_field.sub_field',
})

// Example result
;[
  {
    label: {
      id: 3345231412,
      name: 'My label',
      resource_name: 'customers/3827277046/labels/3345231412',
      status: 2,
      text_label: {
        background_color: '#e993eb',
        description: 'Adgroups where Chloe will write new ads that kick butt.',
      },
    },
    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 a Label

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.labels.create([label, other_label], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/labels/3345231412'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a Label

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

Arguments

entity required

The Label 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 label = {
  resource_name: 'customers/3827277046/labels/3345231412', // The resource_name is required
  // ...any other fields that you would like to update
}

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

// Passing in an array of entities to update, validating only
const result = await customer.labels.update([label, other_label], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/labels/3345231412'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a Label

The customer.labels.delete(resource_name) sets the status field of a Label 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 Label

Returns

Nothing

// Deleting the entity

await customer.labels.delete('customers/3827277046/labels/3345231412')

LanguageConstant

The LanguageConstant object

Fields

code string

Output only. The language code, e.g. "en_US", "en_AU", "es", "fr", etc.

id int64

Output only. The ID of the language constant.

name string

Output only. The full name of the language in English, e.g., "English (US)", "Spanish", etc.

resource_name string

Output only. The resource name of the language constant. Language constant resource names have the form: languageConstants/{criterion_id}

targetable boolean

Output only. Whether the language is targetable.

// Example LanguageConstant
const language_constant = {
  code: 'zh_TW',
  id: 1018,
  name: 'Chinese (traditional)',
  resource_name: 'languageConstants/1018',
  targetable: true,
}

Get a LanguageConstant

The customer.languageConstants.get(resource_name) method returns the LanguageConstant identified by a resource_name.

Arguments

resource_name required

The resource_name of that LanguageConstant

Returns

Returns that LanguageConstant as an object.

// Getting the entity
let result = await customer.languageConstants.get('languageConstants/1018')

// Example result
;({ code: 'zh_TW', id: 1018, name: 'Chinese (traditional)', resource_name: 'languageConstants/1018', targetable: true })

List every instance of LanguageConstant

The customer.languageConstants.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 LanguageConstant.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.languageConstants.list({
  constraints: [
    {
      key: 'language_constant.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'language_constant.some_field.sub_field',
})

// Example result
;[
  {
    language_constant: {
      code: 'zh_TW',
      id: 1018,
      name: 'Chinese (traditional)',
      resource_name: 'languageConstants/1018',
      targetable: true,
    },
  },
]

MediaFile

The MediaFile object

Fields

ONE of the following:

audio object
Output only. Encapsulates an Audio.
Child Fields
ad_duration_millis int64
Output only. The duration of the Audio in milliseconds.
image object
Immutable. Encapsulates an Image.
Child Fields
data byte
Immutable. Raw image data.
media_bundle object
Immutable. A ZIP archive media the content of which contains HTML5 assets.
Child Fields
data byte
Immutable. Raw zipped data.
video object
Immutable. Encapsulates a Video.
Child Fields
ad_duration_millis int64
Output only. The duration of the Video in milliseconds.
advertising_id_code string
Output only. The Advertising Digital Identification code for this video, as defined by the American Association of Advertising Agencies, used mainly for television commercials.
isci_code string
Output only. The Industry Standard Commercial Identifier code for this video, used mainly for television commercials.
youtube_video_id string
Immutable. The YouTube video ID (as seen in YouTube URLs).

file_size int64

Output only. The size of the media file in bytes.

id int64

Output only. The ID of the media file.

mime_type enum

Output only. The mime type of the media file.

name string

Immutable. The name of the media file. The name can be used by clients to help identify previously uploaded media.

resource_name string

Immutable. The resource name of the media file. Media file resource names have the form: customers/{customer_id}/mediaFiles/{media_file_id}

source_url string

Immutable. The URL of where the original media file was downloaded from (or a file name). Only used for media of type AUDIO and IMAGE.

type enum

Immutable. Type of the media file.

// Example MediaFile
const media_file = {
  file_size: 5159,
  id: 44067075104,
  mime_type: 2,
  name: '',
  resource_name: 'customers/3827277046/mediaFiles/44067075104',
  source_url:
    'https://lh3.googleusercontent.com/D3DAe038umSn2ap4q_Ll7HPSTNj5szBbJNOoXeblYkmlZHCGg1JiIq45WIr_CEGM9FXoH1vb9Hi1gF7CLw',
  type: 2,
}

Get a MediaFile

The customer.mediaFiles.get(resource_name) method returns the MediaFile identified by a resource_name.

Arguments

resource_name required

The resource_name of that MediaFile

Returns

Returns that MediaFile as an object.

// Getting the entity
let result = await customer.mediaFiles.get('customers/3827277046/mediaFiles/44067075104')

// Example result
;({
  file_size: 5159,
  id: 44067075104,
  mime_type: 2,
  name: '',
  resource_name: 'customers/3827277046/mediaFiles/44067075104',
  source_url:
    'https://lh3.googleusercontent.com/D3DAe038umSn2ap4q_Ll7HPSTNj5szBbJNOoXeblYkmlZHCGg1JiIq45WIr_CEGM9FXoH1vb9Hi1gF7CLw',
  type: 2,
})

List every instance of MediaFile

The customer.mediaFiles.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 MediaFile.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.mediaFiles.list({
  constraints: [
    {
      key: 'media_file.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'media_file.some_field.sub_field',
})

// Example result
;[
  {
    media_file: {
      file_size: 5159,
      id: 44067075104,
      mime_type: 2,
      name: '',
      resource_name: 'customers/3827277046/mediaFiles/44067075104',
      source_url:
        'https://lh3.googleusercontent.com/D3DAe038umSn2ap4q_Ll7HPSTNj5szBbJNOoXeblYkmlZHCGg1JiIq45WIr_CEGM9FXoH1vb9Hi1gF7CLw',
      type: 2,
    },
    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 a MediaFile

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.mediaFiles.create([media_file, other_media_file], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/mediaFiles/44067075104'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a MediaFile

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

Arguments

entity required

The MediaFile 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 media_file = {
  resource_name: 'customers/3827277046/mediaFiles/44067075104', // 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.mediaFiles.update(media_file)

// Passing in an array of entities to update, validating only
const result = await customer.mediaFiles.update([media_file, other_media_file], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/mediaFiles/44067075104'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a MediaFile

The customer.mediaFiles.delete(resource_name) sets the status field of a MediaFile 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 MediaFile

Returns

Nothing

// Deleting the entity

await customer.mediaFiles.delete('customers/3827277046/mediaFiles/44067075104')

MobileAppCategoryConstant

The MobileAppCategoryConstant object

Fields

id int32

Output only. The ID of the mobile app category constant.

name string

Output only. Mobile app category name.

resource_name string

Output only. The resource name of the mobile app category constant. Mobile app category constant resource names have the form: mobileAppCategoryConstants/{mobile_app_category_id}

// Example MobileAppCategoryConstant
const mobile_app_category_constant = {
  id: 60013,
  name: 'Video Players & Editors',
  resource_name: 'mobileAppCategoryConstants/60013',
}

Get a MobileAppCategoryConstant

The customer.mobileAppCategoryConstants.get(resource_name) method returns the MobileAppCategoryConstant identified by a resource_name.

Arguments

resource_name required

The resource_name of that MobileAppCategoryConstant

Returns

Returns that MobileAppCategoryConstant as an object.

// Getting the entity
let result = await customer.mobileAppCategoryConstants.get('mobileAppCategoryConstants/60013')

// Example result
;({ id: 60013, name: 'Video Players & Editors', resource_name: 'mobileAppCategoryConstants/60013' })

List every instance of MobileAppCategoryConstant

The customer.mobileAppCategoryConstants.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 MobileAppCategoryConstant.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.mobileAppCategoryConstants.list({
  constraints: [
    {
      key: 'mobile_app_category_constant.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'mobile_app_category_constant.some_field.sub_field',
})

// Example result
;[
  {
    mobile_app_category_constant: {
      id: 60013,
      name: 'Video Players & Editors',
      resource_name: 'mobileAppCategoryConstants/60013',
    },
  },
]

MobileDeviceConstant

The MobileDeviceConstant object

Fields

id int64

Output only. The ID of the mobile device constant.

manufacturer_name string

Output only. The manufacturer of the mobile device.

name string

Output only. The name of the mobile device.

operating_system_name string

Output only. The operating system of the mobile device.

resource_name string

Output only. The resource name of the mobile device constant. Mobile device constant resource names have the form: mobileDeviceConstants/{criterion_id}

type enum

Output only. The type of mobile device.

// Example MobileDeviceConstant
const mobile_device_constant = {
  id: 605309,
  manufacturer_name: 'T-Mobile',
  name: 'myTouch 3G Slide',
  operating_system_name: 'Android',
  resource_name: 'mobileDeviceConstants/605309',
  type: 2,
}

Get a MobileDeviceConstant

The customer.mobileDeviceConstants.get(resource_name) method returns the MobileDeviceConstant identified by a resource_name.

Arguments

resource_name required

The resource_name of that MobileDeviceConstant

Returns

Returns that MobileDeviceConstant as an object.

// Getting the entity
let result = await customer.mobileDeviceConstants.get('mobileDeviceConstants/605309')

// Example result
;({
  id: 605309,
  manufacturer_name: 'T-Mobile',
  name: 'myTouch 3G Slide',
  operating_system_name: 'Android',
  resource_name: 'mobileDeviceConstants/605309',
  type: 2,
})

List every instance of MobileDeviceConstant

The customer.mobileDeviceConstants.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 MobileDeviceConstant.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.mobileDeviceConstants.list({
  constraints: [
    {
      key: 'mobile_device_constant.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'mobile_device_constant.some_field.sub_field',
})

// Example result
;[
  {
    mobile_device_constant: {
      id: 605309,
      manufacturer_name: 'T-Mobile',
      name: 'myTouch 3G Slide',
      operating_system_name: 'Android',
      resource_name: 'mobileDeviceConstants/605309',
      type: 2,
    },
  },
]

OperatingSystemVersionConstant

The OperatingSystemVersionConstant object

Fields

id int64

Output only. The ID of the operating system version.

name string

Output only. Name of the operating system.

operator_type enum

Output only. Determines whether this constant represents a single version or a range of versions.

os_major_version int32

Output only. The OS Major Version number.

os_minor_version int32

Output only. The OS Minor Version number.

resource_name string

Output only. The resource name of the operating system version constant. Operating system version constant resource names have the form: operatingSystemVersionConstants/{criterion_id}

// Example OperatingSystemVersionConstant
const operating_system_version_constant = {
  id: 630266,
  name: 'WindowsPhone',
  operator_type: 2,
  os_major_version: -1,
  os_minor_version: -1,
  resource_name: 'operatingSystemVersionConstants/630266',
}

Get an OperatingSystemVersionConstant

The customer.operatingSystemVersionConstants.get(resource_name) method returns the OperatingSystemVersionConstant identified by a resource_name.

Arguments

resource_name required

The resource_name of that OperatingSystemVersionConstant

Returns

Returns that OperatingSystemVersionConstant as an object.

// Getting the entity
let result = await customer.operatingSystemVersionConstants.get('operatingSystemVersionConstants/630266')

// Example result
;({
  id: 630266,
  name: 'WindowsPhone',
  operator_type: 2,
  os_major_version: -1,
  os_minor_version: -1,
  resource_name: 'operatingSystemVersionConstants/630266',
})

List every instance of OperatingSystemVersionConstant

The customer.operatingSystemVersionConstants.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 OperatingSystemVersionConstant.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.operatingSystemVersionConstants.list({
  constraints: [
    {
      key: 'operating_system_version_constant.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'operating_system_version_constant.some_field.sub_field',
})

// Example result
;[
  {
    operating_system_version_constant: {
      id: 630266,
      name: 'WindowsPhone',
      operator_type: 2,
      os_major_version: -1,
      os_minor_version: -1,
      resource_name: 'operatingSystemVersionConstants/630266',
    },
  },
]

ProductBiddingCategoryConstant

The ProductBiddingCategoryConstant object

Fields

country_code string

Output only. Two-letter upper-case country code of the product bidding category.

id int64

Output only. ID of the product bidding category. This ID is equivalent to the google_product_category ID as described in this article: https://support.google.com/merchants/answer/6324436.

language_code string

Output only. Language code of the product bidding category.

level enum

Output only. Level of the product bidding category.

localized_name string

Output only. Display value of the product bidding category localized according to language_code.

product_bidding_category_constant_parent string

Output only. Resource name of the parent product bidding category.

resource_name string

Output only. The resource name of the product bidding category. Product bidding category resource names have the form: productBiddingCategoryConstants/{country_code}~{level}~{id}

status enum

Output only. Status of the product bidding category.

// Example ProductBiddingCategoryConstant
const product_bidding_category_constant = {
  country_code: 'AU',
  id: 55,
  language_code: 'en',
  level: 4,
  localized_name: 'Musical Instrument & Orchestra Accessories',
  product_bidding_category_constant_parent: 'productBiddingCategoryConstants/AU~LEVEL2~5710',
  resource_name: 'productBiddingCategoryConstants/AU~LEVEL3~55',
  status: 2,
}

Get a ProductBiddingCategoryConstant

The customer.productBiddingCategoryConstants.get(resource_name) method returns the ProductBiddingCategoryConstant identified by a resource_name.

Arguments

resource_name required

The resource_name of that ProductBiddingCategoryConstant

Returns

Returns that ProductBiddingCategoryConstant as an object.

// Getting the entity
let result = await customer.productBiddingCategoryConstants.get('productBiddingCategoryConstants/AU~LEVEL3~55')

// Example result
;({
  country_code: 'AU',
  id: 55,
  language_code: 'en',
  level: 4,
  localized_name: 'Musical Instrument & Orchestra Accessories',
  product_bidding_category_constant_parent: 'productBiddingCategoryConstants/AU~LEVEL2~5710',
  resource_name: 'productBiddingCategoryConstants/AU~LEVEL3~55',
  status: 2,
})

List every instance of ProductBiddingCategoryConstant

The customer.productBiddingCategoryConstants.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 ProductBiddingCategoryConstant.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.productBiddingCategoryConstants.list({
  constraints: [
    {
      key: 'product_bidding_category_constant.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'product_bidding_category_constant.some_field.sub_field',
})

// Example result
;[
  {
    product_bidding_category_constant: {
      country_code: 'AU',
      id: 55,
      language_code: 'en',
      level: 4,
      localized_name: 'Musical Instrument & Orchestra Accessories',
      product_bidding_category_constant_parent: 'productBiddingCategoryConstants/AU~LEVEL2~5710',
      resource_name: 'productBiddingCategoryConstants/AU~LEVEL3~55',
      status: 2,
    },
  },
]

Recommendation

The Recommendation object

Fields

ONE of the following:

call_extension_recommendation object
Output only. The Call extension recommendation.
Child Fields
recommended_extensions array of objects
Output only. Call extensions recommended to be added.
call_conversion_action string
The conversion action to attribute a call conversion to. If not set a default conversion action is used. This field only has effect if call_tracking_enabled is set to true. Otherwise this field is ignored.
call_conversion_reporting_state enum
Enum value that indicates whether this call extension uses its own call conversion setting (or just have call conversion disabled), or following the account level setting.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
DISABLED (2)
Call conversion action is disabled.
USE_ACCOUNT_LEVEL_CALL_CONVERSION_ACTION (3)
Call conversion action will use call conversion type set at the account level.
USE_RESOURCE_LEVEL_CALL_CONVERSION_ACTION (4)
Call conversion action will use call conversion type set at the resource (call only ads/call extensions) level.
call_conversion_tracking_disabled boolean
If true, disable call conversion tracking. call_conversion_action should not be set if this is true. Optional.
call_tracking_enabled boolean
Indicates whether call tracking is enabled. By default, call tracking is not enabled.
country_code string
Uppercase two-letter country code of the advertiser's phone number. This string must not be empty.
phone_number string
The advertiser's phone number to append to the ad. This string must not be empty.
callout_extension_recommendation object
Output only. The Callout extension recommendation.
Child Fields
recommended_extensions array of objects
Output only. Callout extensions recommended to be added.
callout_text string
The callout text. The length of this string should be between 1 and 25, inclusive.
campaign_budget_recommendation object
Output only. The campaign budget recommendation.
Child Fields
budget_options array of objects
Output only. The budget amounts and associated impact estimates for some values of possible budget amounts.
budget_amount_micros int64
Output only. The budget amount for this option.
impact object
Output only. The impact estimate if budget is changed to amount specified in this option.
base_metrics object
Output only. Base metrics at the time the recommendation was generated.
clicks double
Output only. Number of ad clicks.
conversions double
Output only. Number of conversions.
cost_micros int64
Output only. Cost (in micros) for advertising, in the local currency for the account.
impressions double
Output only. Number of ad impressions.
video_views double
Output only. Number of video views for a video ad campaign.
potential_metrics object
Output only. Estimated metrics if the recommendation is applied.
clicks double
Output only. Number of ad clicks.
conversions double
Output only. Number of conversions.
cost_micros int64
Output only. Cost (in micros) for advertising, in the local currency for the account.
impressions double
Output only. Number of ad impressions.
video_views double
Output only. Number of video views for a video ad campaign.
current_budget_amount_micros int64
Output only. The current budget amount in micros.
recommended_budget_amount_micros int64
Output only. The recommended budget amount in micros.
enhanced_cpc_opt_in_recommendation object
Output only. The Enhanced Cost-Per-Click Opt-In recommendation.
Child Fields
keyword_match_type_recommendation object
Output only. The keyword match type recommendation.
Child Fields
keyword object
Output only. The existing keyword where the match type should be more broad.
match_type enum
The match type of the keyword.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EXACT (2)
Exact match.
PHRASE (3)
Phrase match.
BROAD (4)
Broad match.
text string
The text of the keyword (at most 80 characters and 10 words).
recommended_match_type enum
Output only. The recommended new match type.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EXACT (2)
Exact match.
PHRASE (3)
Phrase match.
BROAD (4)
Broad match.
keyword_recommendation object
Output only. The keyword recommendation.
Child Fields
keyword object
Output only. The recommended keyword.
match_type enum
The match type of the keyword.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EXACT (2)
Exact match.
PHRASE (3)
Phrase match.
BROAD (4)
Broad match.
text string
The text of the keyword (at most 80 characters and 10 words).
recommended_cpc_bid_micros int64
Output only. The recommended CPC (cost-per-click) bid.
maximize_clicks_opt_in_recommendation object
Output only. The MaximizeClicks Opt-In recommendation.
Child Fields
recommended_budget_amount_micros int64
Output only. The recommended new budget amount. Only set if the current budget is too high.
maximize_conversions_opt_in_recommendation object
Output only. The MaximizeConversions Opt-In recommendation.
Child Fields
recommended_budget_amount_micros int64
Output only. The recommended new budget amount.
move_unused_budget_recommendation object
Output only. The move unused budget recommendation.
Child Fields
budget_recommendation object
Output only. The recommendation for the constrained budget to increase.
budget_options array of objects
Output only. The budget amounts and associated impact estimates for some values of possible budget amounts.
budget_amount_micros int64
Output only. The budget amount for this option.
impact object
Output only. The impact estimate if budget is changed to amount specified in this option.
base_metrics object
Output only. Base metrics at the time the recommendation was generated.
clicks double
Output only. Number of ad clicks.
conversions double
Output only. Number of conversions.
cost_micros int64
Output only. Cost (in micros) for advertising, in the local currency for the account.
impressions double
Output only. Number of ad impressions.
video_views double
Output only. Number of video views for a video ad campaign.
potential_metrics object
Output only. Estimated metrics if the recommendation is applied.
clicks double
Output only. Number of ad clicks.
conversions double
Output only. Number of conversions.
cost_micros int64
Output only. Cost (in micros) for advertising, in the local currency for the account.
impressions double
Output only. Number of ad impressions.
video_views double
Output only. Number of video views for a video ad campaign.
current_budget_amount_micros int64
Output only. The current budget amount in micros.
recommended_budget_amount_micros int64
Output only. The recommended budget amount in micros.
excess_campaign_budget string
Output only. The excess budget's resource_name.
optimize_ad_rotation_recommendation object
Output only. The Optimize Ad Rotation recommendation.
Child Fields
search_partners_opt_in_recommendation object
Output only. The Search Partners Opt-In recommendation.
Child Fields
sitelink_extension_recommendation object
Output only. The Sitelink extension recommendation.
Child Fields
recommended_extensions array of objects
Output only. Sitelink extensions recommended to be added.
final_mobile_urls array of strings
A list of possible final mobile URLs after all cross domain redirects.
final_url_suffix string
Final URL suffix to be appended to landing page URLs served with parallel tracking.
final_urls array of strings
A list of possible final URLs after all cross domain redirects.
line1 string
First line of the description for the sitelink. If this value is set, line2 must also be set. The length of this string should be between 0 and 35, inclusive.
line2 string
Second line of the description for the sitelink. If this value is set, line1 must also be set. The length of this string should be between 0 and 35, inclusive.
link_text string
URL display text for the sitelink. The length of this string should be between 1 and 25, inclusive.
tracking_url_template string
URL template for constructing a tracking URL.
url_custom_parameters array of objects
A list of mappings to be used for substituting URL custom parameter tags in the tracking_url_template, final_urls, and/or final_mobile_urls.
key string
The key matching the parameter tag name.
value string
The value to be substituted.
target_cpa_opt_in_recommendation object
Output only. The TargetCPA opt-in recommendation.
Child Fields
options array of objects
Output only. The available goals and corresponding options for Target CPA strategy.
goal enum
Output only. The goal achieved by this option.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
SAME_COST (2)
Recommendation to set Target CPA to maintain the same cost.
SAME_CONVERSIONS (3)
Recommendation to set Target CPA to maintain the same conversions.
SAME_CPA (4)
Recommendation to set Target CPA to maintain the same CPA.
CLOSEST_CPA (5)
Recommendation to set Target CPA to a value that is as close as possible to, yet lower than, the actual CPA (computed for past 28 days).
impact object
Output only. The impact estimate if this option is selected.
base_metrics object
Output only. Base metrics at the time the recommendation was generated.
clicks double
Output only. Number of ad clicks.
conversions double
Output only. Number of conversions.
cost_micros int64
Output only. Cost (in micros) for advertising, in the local currency for the account.
impressions double
Output only. Number of ad impressions.
video_views double
Output only. Number of video views for a video ad campaign.
potential_metrics object
Output only. Estimated metrics if the recommendation is applied.
clicks double
Output only. Number of ad clicks.
conversions double
Output only. Number of conversions.
cost_micros int64
Output only. Cost (in micros) for advertising, in the local currency for the account.
impressions double
Output only. Number of ad impressions.
video_views double
Output only. Number of video views for a video ad campaign.
required_campaign_budget_amount_micros int64
Output only. The minimum campaign budget, in local currency for the account, required to achieve the target CPA. Amount is specified in micros, where one million is equivalent to one currency unit.
target_cpa_micros int64
Output only. Average CPA target.
recommended_target_cpa_micros int64
Output only. The recommended average CPA target. See required budget amount and impact of using this recommendation in options list.
text_ad_recommendation object
Output only. Add expanded text ad recommendation.
Child Fields
ad object
Output only. Recommended ad.
ONE of the following:
app_ad object
Details pertaining to an app ad.
Child Fields
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
html_5_media_bundles array of objects
List of media bundle assets that may be used with the ad.
asset string
The Asset resource name of this media bundle.
images array of objects
List of image assets that may be displayed with the ad.
asset string
The Asset resource name of this image.
mandatory_ad_text object
An optional text asset that, if specified, must always be displayed when the ad is served.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
youtube_videos array of objects
List of YouTube video assets that may be displayed with the ad.
asset string
The Asset resource name of this video.
app_engagement_ad object
Details pertaining to an app engagement ad.
Child Fields
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
images array of objects
List of image assets that may be displayed with the ad.
asset string
The Asset resource name of this image.
videos array of objects
List of video assets that may be displayed with the ad.
asset string
The Asset resource name of this video.
call_only_ad object
Details pertaining to a call-only ad.
Child Fields
business_name string
The business name in the ad.
call_tracked boolean
Whether to enable call tracking for the creative. Enabling call tracking also enables call conversions.
conversion_action string
The conversion action to attribute a call conversion to. If not set a default conversion action is used. This field only has effect if call_tracked is set to true. Otherwise this field is ignored.
conversion_reporting_state enum
The call conversion behavior of this call only ad. It can use its own call conversion setting, inherit the account level setting, or be disabled.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
DISABLED (2)
Call conversion action is disabled.
USE_ACCOUNT_LEVEL_CALL_CONVERSION_ACTION (3)
Call conversion action will use call conversion type set at the account level.
USE_RESOURCE_LEVEL_CALL_CONVERSION_ACTION (4)
Call conversion action will use call conversion type set at the resource (call only ads/call extensions) level.
country_code string
The country code in the ad.
description1 string
The first line of the ad's description.
description2 string
The second line of the ad's description.
disable_call_conversion boolean
Whether to disable call conversion for the creative. If set to true, disables call conversions even when call_tracked is true. If call_tracked is false, this field is ignored.
headline1 string
First headline in the ad.
headline2 string
Second headline in the ad.
phone_number string
The phone number in the ad.
phone_number_verification_url string
The URL to be used for phone number verification.
display_upload_ad object
Details pertaining to a display upload ad.
Child Fields
display_upload_product_type enum
The product type of this ad. See comments on the enum for details.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
HTML5_UPLOAD_AD (2)
HTML5 upload ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set.
DYNAMIC_HTML5_EDUCATION_AD (3)
Dynamic HTML5 education ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in an education campaign.
DYNAMIC_HTML5_FLIGHT_AD (4)
Dynamic HTML5 flight ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a flight campaign.
DYNAMIC_HTML5_HOTEL_RENTAL_AD (5)
Dynamic HTML5 hotel and rental ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a hotel campaign.
DYNAMIC_HTML5_JOB_AD (6)
Dynamic HTML5 job ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a job campaign.
DYNAMIC_HTML5_LOCAL_AD (7)
Dynamic HTML5 local ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a local campaign.
DYNAMIC_HTML5_REAL_ESTATE_AD (8)
Dynamic HTML5 real estate ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a real estate campaign.
DYNAMIC_HTML5_CUSTOM_AD (9)
Dynamic HTML5 custom ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a custom campaign.
DYNAMIC_HTML5_TRAVEL_AD (10)
Dynamic HTML5 travel ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a travel campaign.
DYNAMIC_HTML5_HOTEL_AD (11)
Dynamic HTML5 hotel ad. This product type requires the upload_media_bundle field in DisplayUploadAdInfo to be set. Can only be used in a hotel campaign.
media_bundle object
A media bundle asset to be used in the ad. For information about the media bundle for HTML5_UPLOAD_AD see https://support.google.com/google-ads/answer/1722096 Media bundles that are part of dynamic product types use a special format that needs to be created through the Google Web Designer. See https://support.google.com/webdesigner/answer/7543898 for more information.
asset string
The Asset resource name of this media bundle.
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.
Child Fields
description string
The description of the ad.
description2 string
The second description of the ad.
expanded_text_ad object
Details pertaining to an expanded text ad.
Child Fields
description string
The description of the ad.
description2 string
The second description of the ad.
headline_part1 string
The first part of the ad's headline.
headline_part2 string
The second part of the ad's headline.
headline_part3 string
The third part of the ad's headline.
path1 string
The text that can appear alongside the ad's displayed URL.
path2 string
Additional text that can appear alongside the ad's displayed URL.
gmail_ad object
Immutable. Details pertaining to a Gmail ad.
Child Fields
header_image string
The MediaFile resource name of the header image. Valid image types are GIF, JPEG and PNG. The minimum size is 300x100 pixels and the aspect ratio must be between 3:1 and 5:1 (+-1%).
marketing_image string
The MediaFile resource name of the marketing image. Valid image types are GIF, JPEG and PNG. The image must either be landscape with a minimum size of 600x314 pixels and aspect ratio of 600:314 (+-1%) or square with a minimum size of 300x300 pixels and aspect ratio of 1:1 (+-1%)
marketing_image_description string
Description of the marketing image.
marketing_image_display_call_to_action object
Display-call-to-action of the marketing image.
text string
Text for the display-call-to-action.
text_color string
Text color for the display-call-to-action in hexadecimal, e.g. #ffffff for white.
url_collection_id string
Identifies the url collection in the ad.url_collections field. If not set the url defaults to final_url.
marketing_image_headline string
Headline of the marketing image.
product_images array of objects
Product images. Up to 15 images are supported.
description string
Description of the product.
display_call_to_action object
Display-call-to-action of the product image.
text string
Text for the display-call-to-action.
text_color string
Text color for the display-call-to-action in hexadecimal, e.g. #ffffff for white.
url_collection_id string
Identifies the url collection in the ad.url_collections field. If not set the url defaults to final_url.
product_image string
The MediaFile resource name of the product image. Valid image types are GIF, JPEG and PNG. The minimum size is 300x300 pixels and the aspect ratio must be 1:1 (+-1%).
product_videos array of objects
Product videos. Up to 7 videos are supported. At least one product video or a marketing image must be specified.
product_video string
The MediaFile resource name of a video which must be hosted on YouTube.
teaser object
The Gmail teaser.
business_name string
Business name of the advertiser.
description string
Description of the teaser.
headline string
Headline of the teaser.
logo_image string
The MediaFile resource name of the logo image. Valid image types are GIF, JPEG and PNG. The minimum size is 144x144 pixels and the aspect ratio must be 1:1 (+-1%).
hotel_ad object
Details pertaining to a hotel ad.
Child Fields
image_ad object
Immutable. Details pertaining to an Image ad.
Child Fields
ad_id_to_copy_image_from int64
An ad ID to copy the image from.
data byte
Raw image data as bytes.
image_url string
URL of the full size image.
media_file string
The MediaFile resource to use for the image.
mime_type enum
The mime type of the image.
UNSPECIFIED (0)
The mime type has not been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
IMAGE_JPEG (2)
MIME type of image/jpeg.
IMAGE_GIF (3)
MIME type of image/gif.
IMAGE_PNG (4)
MIME type of image/png.
FLASH (5)
MIME type of application/x-shockwave-flash.
TEXT_HTML (6)
MIME type of text/html.
PDF (7)
MIME type of application/pdf.
MSWORD (8)
MIME type of application/msword.
MSEXCEL (9)
MIME type of application/vnd.ms-excel.
RTF (10)
MIME type of application/rtf.
AUDIO_WAV (11)
MIME type of audio/wav.
AUDIO_MP3 (12)
MIME type of audio/mp3.
HTML5_AD_ZIP (13)
MIME type of application/x-html5-ad-zip.
name string
The name of the image. If the image was created from a MediaFile, this is the MediaFile's name. If the image was created from bytes, this is empty.
pixel_height int64
Height in pixels of the full size image.
pixel_width int64
Width in pixels of the full size image.
preview_image_url string
URL of the preview size image.
preview_pixel_height int64
Height in pixels of the preview size image.
preview_pixel_width int64
Width in pixels of the preview size image.
legacy_app_install_ad object
Immutable. Details pertaining to a legacy app install ad.
Child Fields
app_id string
The id of the mobile app.
app_store enum
The app store the mobile app is available in.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
APPLE_APP_STORE (2)
Apple iTunes.
GOOGLE_PLAY (3)
Google Play.
WINDOWS_STORE (4)
Windows Store.
WINDOWS_PHONE_STORE (5)
Windows Phone Store.
CN_APP_STORE (6)
The app is hosted in a Chinese app store.
description1 string
The first description line of the ad.
description2 string
The second description line of the ad.
headline string
The headline of the ad.
legacy_responsive_display_ad object
Details pertaining to a legacy responsive display ad.
Child Fields
accent_color string
The accent color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
allow_flexible_color boolean
Advertiser's consent to allow flexible color. When true, the ad may be served with different color if necessary. When false, the ad will be served with the specified colors or a neutral color. The default value is true. Must be true if main_color and accent_color are not set.
business_name string
The business name in the ad.
call_to_action_text string
The call-to-action text for the ad.
description string
The description of the ad.
format_setting enum
Specifies which format the ad will be served in. Default is ALL_FORMATS.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
ALL_FORMATS (2)
Text, image and native formats.
NON_NATIVE (3)
Text and image formats.
NATIVE (4)
Native format, i.e. the format rendering is controlled by the publisher and not by Google.
logo_image string
The MediaFile resource name of the logo image used in the ad.
long_headline string
The long version of the ad's headline.
main_color string
The main color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
marketing_image string
The MediaFile resource name of the marketing image used in the ad.
price_prefix string
Prefix before price. E.g. 'as low as'.
promo_text string
Promotion text used for dyanmic formats of responsive ads. For example 'Free two-day shipping'.
short_headline string
The short version of the ad's headline.
square_logo_image string
The MediaFile resource name of the square logo image used in the ad.
square_marketing_image string
The MediaFile resource name of the square marketing image used in the ad.
local_ad object
Details pertaining to a local ad.
Child Fields
call_to_actions array of objects
List of text assets for call-to-actions. When the ad serves the call-to-actions will be selected from this list. Call-to-actions are optional and at most 5 can be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list. At least 1 and at most 5 descriptions must be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list. At least 1 and at most 5 headlines must be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
logo_images array of objects
List of logo image assets that may be displayed with the ad. The images must be 128x128 pixels and not larger than 120KB. At least 1 and at most 5 image assets must be specified.
asset string
The Asset resource name of this image.
marketing_images array of objects
List of marketing image assets that may be displayed with the ad. The images must be 314x600 pixels or 320x320 pixels. At least 1 and at most 20 image assets must be specified.
asset string
The Asset resource name of this image.
path1 string
First part of optional text that may appear appended to the url displayed in the ad.
path2 string
Second part of optional text that may appear appended to the url displayed in the ad. This field can only be set when path1 is also set.
videos array of objects
List of YouTube video assets that may be displayed with the ad. Videos are optional and at most 20 can be specified.
asset string
The Asset resource name of this video.
responsive_display_ad object
Details pertaining to a responsive display ad.
Child Fields
accent_color string
The accent color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
allow_flexible_color boolean
Advertiser's consent to allow flexible color. When true, the ad may be served with different color if necessary. When false, the ad will be served with the specified colors or a neutral color. The default value is true. Must be true if main_color and accent_color are not set.
business_name string
The advertiser/brand name. Maximum display width is 25.
call_to_action_text string
The call-to-action text for the ad. Maximum display width is 30.
descriptions array of objects
Descriptive texts for the ad. The maximum length is 90 characters. At least 1 and max 5 headlines can be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
format_setting enum
Specifies which format the ad will be served in. Default is ALL_FORMATS.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
The value is unknown in this version.
ALL_FORMATS (2)
Text, image and native formats.
NON_NATIVE (3)
Text and image formats.
NATIVE (4)
Native format, i.e. the format rendering is controlled by the publisher and not by Google.
headlines array of objects
Short format headlines for the ad. The maximum length is 30 characters. At least 1 and max 5 headlines can be specified.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
logo_images array of objects
Logo images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 512x128 and the aspect ratio must be 4:1 (+-1%). Combined with square_logo_images the maximum is 5.
asset string
The Asset resource name of this image.
long_headline object
A required long format headline. The maximum length is 90 characters.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
main_color string
The main color of the ad in hexadecimal, e.g. #ffffff for white. If one of main_color and accent_color is set, the other is required as well.
marketing_images array of objects
Marketing images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 600x314 and the aspect ratio must be 1.91:1 (+-1%). At least one marketing_image is required. Combined with square_marketing_images the maximum is 15.
asset string
The Asset resource name of this image.
price_prefix string
Prefix before price. E.g. 'as low as'.
promo_text string
Promotion text used for dyanmic formats of responsive ads. For example 'Free two-day shipping'.
square_logo_images array of objects
Square logo images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 128x128 and the aspect ratio must be 1:1 (+-1%). Combined with square_logo_images the maximum is 5.
asset string
The Asset resource name of this image.
square_marketing_images array of objects
Square marketing images to be used in the ad. Valid image types are GIF, JPEG, and PNG. The minimum size is 300x300 and the aspect ratio must be 1:1 (+-1%). At least one square marketing_image is required. Combined with marketing_images the maximum is 15.
asset string
The Asset resource name of this image.
youtube_videos array of objects
Optional YouTube videos for the ad. A maximum of 5 videos can be specified.
asset string
The Asset resource name of this video.
responsive_search_ad object
Details pertaining to a responsive search ad.
Child Fields
descriptions array of objects
List of text assets for descriptions. When the ad serves the descriptions will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
headlines array of objects
List of text assets for headlines. When the ad serves the headlines will be selected from this list.
pinned_field enum
The pinned field of the asset. This restricts the asset to only serve within this field. Multiple assets can be pinned to the same field. An asset that is unpinned or pinned to a different field will not serve in a field where some other asset has been pinned.
UNSPECIFIED (0)
No value has been specified.
UNKNOWN (1)
The received value is not known in this version. This is a response-only value.
HEADLINE_1 (2)
The asset is used in headline 1.
HEADLINE_2 (3)
The asset is used in headline 2.
HEADLINE_3 (4)
The asset is used in headline 3.
DESCRIPTION_1 (5)
The asset is used in description 1.
DESCRIPTION_2 (6)
The asset is used in description 2.
text string
Asset text.
path1 string
First part of text that may appear appended to the url displayed in the ad.
path2 string
Second part of text that may appear appended to the url displayed in the ad. This field can only be set when path1 is also set.
shopping_comparison_listing_ad object
Details pertaining to a Shopping Comparison Listing ad.
Child Fields
headline string
Headline of the ad. This field is required. Allowed length is between 25 and 45 characters.
shopping_product_ad object
Details pertaining to a Shopping product ad.
Child Fields
shopping_smart_ad object
Details pertaining to a Smart Shopping ad.
Child Fields
text_ad object
Immutable. Details pertaining to a text ad.
Child Fields
description1 string
The first line of the ad's description.
description2 string
The second line of the ad's description.
headline string
The headline of the ad.
video_ad object
Details pertaining to a Video ad.
Child Fields
bumper object
Video bumper in-stream ad format.
companion_banner string
The MediaFile resource name of the companion banner used with the ad.
discovery object
Video TrueView discovery ad format.
description1 string
First text line for a TrueView video discovery ad.
description2 string
Second text line for a TrueView video discovery ad.
headline string
The headline of the ad.
in_stream object
Video TrueView in-stream ad format.
action_button_label string
Label on the CTA (call-to-action) button taking the user to the video ad's final URL. Required for TrueView for action campaigns, optional otherwise.
action_headline string
Additional text displayed with the CTA (call-to-action) button to give context and encourage clicking on the button.
companion_banner string
The MediaFile resource name of the companion banner used with the ad.
media_file string
The MediaFile resource to use for the video.
non_skippable object
Video non-skippable in-stream ad format.
companion_banner string
The MediaFile resource name of the companion banner used with the ad.
out_stream object
Video out-stream ad format.
description string
The description line.
headline string
The headline of the 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.
auto_apply_date string
Output only. Date, if present, is the earliest when the recommendation will be auto applied. YYYY-MM-DD format, e.g., 2018-04-17.
creation_date string
Output only. Creation date of the recommended ad. YYYY-MM-DD format, e.g., 2018-04-17.

ad_group string

Output only. The ad group targeted by this recommendation. This will be set only when the recommendation affects a single ad group. This field will be set for the following recommendation types: KEYWORD, OPTIMIZE_AD_ROTATION, TEXT_AD

campaign string

Output only. The campaign targeted by this recommendation. This will be set only when the recommendation affects a single campaign. This field will be set for the following recommendation types: CALL_EXTENSION, CALLOUT_EXTENSION, ENHANCED_CPC_OPT_IN, KEYWORD, KEYWORD_MATCH_TYPE, MAXIMIZE_CLICKS_OPT_IN, MAXIMIZE_CONVERSIONS_OPT_IN, OPTIMIZE_AD_ROTATION, SEARCH_PARTNERS_OPT_IN, SITELINK_EXTENSION, TARGET_CPA_OPT_IN, TEXT_AD

campaign_budget string

Output only. The budget targeted by this recommendation. This will be set only when the recommendation affects a single campaign budget. This field will be set for the following recommendation types: CAMPAIGN_BUDGET, FORECASTING_CAMPAIGN_BUDGET, MOVE_UNUSED_BUDGET

dismissed boolean

Output only. Whether the recommendation is dismissed or not.

impact object

Output only. The impact on account performance as a result of applying the recommendation.

resource_name string

Immutable. The resource name of the recommendation. customers/{customer_id}/recommendations/{recommendation_id}

type enum

Output only. The type of recommendation.

// Example Recommendation
const recommendation = {
  ad_group: 'customers/3827277046/adGroups/77057363272',
  campaign: 'customers/3827277046/campaigns/2081620948',
  campaign_budget: 'customers/3827277046/campaignBudgets/6449346162',
  dismissed: false,
  impact: {
    base_metrics: { clicks: 2, cost_micros: 20460000, impressions: 12 },
    potential_metrics: { clicks: 4, conversions: 0.05, cost_micros: 36006832, impressions: 110 },
  },
  keyword_recommendation: {
    keyword: { match_type: 2, text: 'google adwords management' },
    recommended_cpc_bid_micros: 9600000,
  },
  resource_name:
    'customers/3827277046/recommendations/MTk5MDY3NzIzLTE2My0xNTk1MTg1NjIwMDAwLSsyMDgxNjIwOTQ4LTc3MDU3MzYzMjcyLTIyNzkzMTg2Nzk5NTk5NTgxOTU',
  type: 3,
}

Get a Recommendation

The customer.recommendations.get(resource_name) method returns the Recommendation identified by a resource_name.

Arguments

resource_name required

The resource_name of that Recommendation

Returns

Returns that Recommendation as an object.

// Getting the entity
let result = await customer.recommendations.get(
  'customers/3827277046/recommendations/MTk5MDY3NzIzLTE2My0xNTk1MTg1NjIwMDAwLSsyMDgxNjIwOTQ4LTc3MDU3MzYzMjcyLTIyNzkzMTg2Nzk5NTk5NTgxOTU'
)

// Example result
;({
  ad_group: 'customers/3827277046/adGroups/77057363272',
  campaign: 'customers/3827277046/campaigns/2081620948',
  campaign_budget: 'customers/3827277046/campaignBudgets/6449346162',
  dismissed: false,
  impact: {
    base_metrics: { clicks: 2, cost_micros: 20460000, impressions: 12 },
    potential_metrics: { clicks: 4, conversions: 0.05, cost_micros: 36006832, impressions: 110 },
  },
  keyword_recommendation: {
    keyword: { match_type: 2, text: 'google adwords management' },
    recommended_cpc_bid_micros: 9600000,
  },
  resource_name:
    'customers/3827277046/recommendations/MTk5MDY3NzIzLTE2My0xNTk1MTg1NjIwMDAwLSsyMDgxNjIwOTQ4LTc3MDU3MzYzMjcyLTIyNzkzMTg2Nzk5NTk5NTgxOTU',
  type: 3,
})

List every instance of Recommendation

The customer.recommendations.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 Recommendation.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.recommendations.list({
  constraints: [
    {
      key: 'recommendation.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'recommendation.some_field.sub_field',
})

// Example result
;[
  {
    recommendation: {
      ad_group: 'customers/3827277046/adGroups/77057363272',
      campaign: 'customers/3827277046/campaigns/2081620948',
      campaign_budget: 'customers/3827277046/campaignBudgets/6449346162',
      dismissed: false,
      impact: {
        base_metrics: { clicks: 2, cost_micros: 20460000, impressions: 12 },
        potential_metrics: { clicks: 4, conversions: 0.05, cost_micros: 36006832, impressions: 110 },
      },
      keyword_recommendation: {
        keyword: { match_type: 2, text: 'google adwords management' },
        recommended_cpc_bid_micros: 9600000,
      },
      resource_name:
        'customers/3827277046/recommendations/MTk5MDY3NzIzLTE2My0xNTk1MTg1NjIwMDAwLSsyMDgxNjIwOTQ4LTc3MDU3MzYzMjcyLTIyNzkzMTg2Nzk5NTk5NTgxOTU',
      type: 3,
    },
    campaign_budget: {
      amount_micros: 290000000,
      delivery_method: 2,
      explicitly_shared: false,
      has_recommended_budget: false,
      id: 6449346162,
      name: 'My campaign budget',
      period: 2,
      reference_count: 1,
      resource_name: 'customers/3827277046/campaignBudgets/6449346162',
      status: 2,
      type: 2,
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/77057363272',
      campaign: 'customers/3827277046/campaigns/2081620948',
      cpc_bid_micros: 9600000,
      cpm_bid_micros: 10000000,
      cpv_bid_micros: 0,
      display_custom_bid_dimension: 0,
      effective_target_cpa_micros: 12000000,
      effective_target_cpa_source: 6,
      effective_target_roas_source: 0,
      explorer_auto_optimizer_setting: { opt_in: false },
      id: 77057363272,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/77057363272',
      status: 2,
      target_cpa_micros: 12000000,
      target_cpm_micros: 10000000,
      targeting_setting: {
        target_restrictions: [
          { targeting_dimension: 3, bid_only: true },
          { 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: 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/3827277046/campaigns/2081620948',
      bidding_strategy_type: 3,
      campaign_budget: 'customers/3827277046/campaignBudgets/6449346162',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [],
      geo_target_type_setting: { negative_geo_target_type: 5, positive_geo_target_type: 7 },
      id: 2081620948,
      labels: [
        'customers/3827277046/labels/3889728216',
        'customers/3827277046/labels/3889728468',
        'customers/3827277046/labels/3889728480',
      ],
      manual_cpc: { enhanced_cpc_enabled: true },
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: true,
        target_partner_search_network: false,
        target_search_network: false,
      },
      optimization_score: 0.8309262174345264,
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/2081620948',
      serving_status: 2,
      start_date: '2019-07-30',
      status: 2,
      targeting_setting: { target_restrictions: [{ targeting_dimension: 3, bid_only: true }] },
      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}',
    },
  },
]

RemarketingAction

The RemarketingAction object

Fields

id int64

Output only. Id of the remarketing action.

name string

The name of the remarketing action. This field is required and should not be empty when creating new remarketing actions.

resource_name string

Immutable. The resource name of the remarketing action. Remarketing action resource names have the form: customers/{customer_id}/remarketingActions/{remarketing_action_id}

tag_snippets array of objects

Output only. The snippets used for tracking remarketing actions.

// Example RemarketingAction
const remarketing_action = /* Todo: add example get() return here */

Get a RemarketingAction

The customer.remarketingActions.get(resource_name) method returns the RemarketingAction identified by a resource_name.

Arguments

resource_name required

The resource_name of that RemarketingAction

Returns

Returns that RemarketingAction as an object.

// Getting the entity
let result = await customer.remarketingActions.get('customers/1234567890/remarketingActions/123123123')

// Example result
(/* Todo: add example get() return here */)

List every instance of RemarketingAction

The customer.remarketingActions.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 RemarketingAction.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.remarketingActions.list({
  constraints: [
    {
      key: 'remarketing_action.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'remarketing_action.some_field.sub_field',
})

// Example result
;[
  /* Todo: add example list() return here */
]

Create a RemarketingAction

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.remarketingActions.create([remarketing_action, other_remarketing_action], {
  validate_only: true,
})

// Example result
{
	results : ['customers/1234567890/remarketingActions/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a RemarketingAction

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

Arguments

entity required

The RemarketingAction 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 remarketing_action = {
  resource_name: 'customers/1234567890/remarketingActions/123123123', // 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.remarketingActions.update(remarketing_action)

// Passing in an array of entities to update, validating only
const result = await customer.remarketingActions.update([remarketing_action, other_remarketing_action], {
  validate_only: true,
})

// Example result
{
	results : ['customers/1234567890/remarketingActions/123123123'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a RemarketingAction

The customer.remarketingActions.delete(resource_name) sets the status field of a RemarketingAction 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 RemarketingAction

Returns

Nothing

// Deleting the entity

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

SharedCriterion

The SharedCriterion object

Fields

ONE of the following:

keyword object
Immutable. Keyword.
Child Fields
match_type enum
The match type of the keyword.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EXACT (2)
Exact match.
PHRASE (3)
Phrase match.
BROAD (4)
Broad match.
text string
The text of the keyword (at most 80 characters and 10 words).
mobile_app_category object
Immutable. Mobile App Category.
Child Fields
mobile_app_category_constant string
The mobile app category constant resource name.
mobile_application object
Immutable. Mobile application.
Child Fields
app_id string
A string that uniquely identifies a mobile application to Google Ads API. The format of this string is "{platform}-{platform_native_id}", where platform is "1" for iOS apps and "2" for Android apps, and where platform_native_id is the mobile application identifier native to the corresponding platform. For iOS, this native identifier is the 9 digit string that appears at the end of an App Store URL (e.g., "476943146" for "Flood-It! 2" whose App Store link is "http://itunes.apple.com/us/app/flood-it!-2/id476943146"). For Android, this native identifier is the application's package name (e.g., "com.labpixies.colordrips" for "Color Drips" given Google Play link "https://play.google.com/store/apps/details?id=com.labpixies.colordrips"). A well formed app id for Google Ads API would thus be "1-476943146" for iOS and "2-com.labpixies.colordrips" for Android. This field is required and must be set in CREATE operations.
name string
Name of this mobile application.
placement object
Immutable. Placement.
Child Fields
url string
URL of the placement. For example, "http://www.domain.com".
youtube_channel object
Immutable. YouTube Channel.
Child Fields
channel_id string
The YouTube uploader channel id or the channel code of a YouTube channel.
youtube_video object
Immutable. YouTube Video.
Child Fields
video_id string
YouTube video id as it appears on the YouTube watch page.

criterion_id int64

Output only. The ID of the criterion. This field is ignored for mutates.

resource_name string

Immutable. The resource name of the shared criterion. Shared set resource names have the form: customers/{customer_id}/sharedCriteria/{shared_set_id}~{criterion_id}

shared_set string

Immutable. The shared set to which the shared criterion belongs.

type enum

Output only. The type of the criterion.

// Example SharedCriterion
const shared_criterion = {
  criterion_id: 627191652608,
  keyword: { match_type: 2, text: 'test-keyword-399026' },
  resource_name: 'customers/9262111890/sharedCriteria/1788591305~627191652608',
  shared_set: 'customers/9262111890/sharedSets/1788591305',
  type: 2,
}

Get a SharedCriterion

The customer.sharedCriteria.get(resource_name) method returns the SharedCriterion identified by a resource_name.

Arguments

resource_name required

The resource_name of that SharedCriterion

Returns

Returns that SharedCriterion as an object.

// Getting the entity
let result = await customer.sharedCriteria.get('customers/9262111890/sharedCriteria/1788591305~627191652608')

// Example result
;({
  criterion_id: 627191652608,
  keyword: { match_type: 2, text: 'test-keyword-399026' },
  resource_name: 'customers/9262111890/sharedCriteria/1788591305~627191652608',
  shared_set: 'customers/9262111890/sharedSets/1788591305',
  type: 2,
})

List every instance of SharedCriterion

The customer.sharedCriteria.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 SharedCriterion.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.sharedCriteria.list({
  constraints: [
    {
      key: 'shared_criterion.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'shared_criterion.some_field.sub_field',
})

// Example result
;[
  {
    shared_criterion: {
      criterion_id: 627191652608,
      keyword: { match_type: 2, text: 'test-keyword-399026' },
      resource_name: 'customers/9262111890/sharedCriteria/1788591305~627191652608',
      shared_set: 'customers/9262111890/sharedSets/1788591305',
      type: 2,
    },
    shared_set: {
      id: 1788591305,
      member_count: 6,
      name: 'My shared set',
      reference_count: 0,
      resource_name: 'customers/9262111890/sharedSets/1788591305',
      status: 2,
      type: 2,
    },
    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 a SharedCriterion

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.sharedCriteria.create([shared_criterion, other_shared_criterion], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/sharedCriteria/1788591305~627191652608'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a SharedCriterion

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

Arguments

entity required

The SharedCriterion 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 shared_criterion = {
  resource_name: 'customers/9262111890/sharedCriteria/1788591305~627191652608', // 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.sharedCriteria.update(shared_criterion)

// Passing in an array of entities to update, validating only
const result = await customer.sharedCriteria.update([shared_criterion, other_shared_criterion], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/sharedCriteria/1788591305~627191652608'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a SharedCriterion

The customer.sharedCriteria.delete(resource_name) sets the status field of a SharedCriterion 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 SharedCriterion

Returns

Nothing

// Deleting the entity

await customer.sharedCriteria.delete('customers/9262111890/sharedCriteria/1788591305~627191652608')

SharedSet

The SharedSet object

Fields

id int64

Output only. The ID of this shared set. Read only.

member_count int64

Output only. The number of shared criteria within this shared set. Read only.

name string

The name of this shared set. Required. Shared Sets must have names that are unique among active shared sets of the same type. The length of this string should be between 1 and 255 UTF-8 bytes, inclusive.

reference_count int64

Output only. The number of campaigns associated with this shared set. Read only.

resource_name string

Immutable. The resource name of the shared set. Shared set resource names have the form: customers/{customer_id}/sharedSets/{shared_set_id}

status enum

Output only. The status of this shared set. Read only.

type enum

Immutable. The type of this shared set: each shared set holds only a single kind of resource. Required. Immutable.

// Example SharedSet
const shared_set = {
  id: 1788591305,
  member_count: 6,
  name: 'My shared set',
  reference_count: 0,
  resource_name: 'customers/9262111890/sharedSets/1788591305',
  status: 2,
  type: 2,
}

Get a SharedSet

The customer.sharedSets.get(resource_name) method returns the SharedSet identified by a resource_name.

Arguments

resource_name required

The resource_name of that SharedSet

Returns

Returns that SharedSet as an object.

// Getting the entity
let result = await customer.sharedSets.get('customers/9262111890/sharedSets/1788591305')

// Example result
;({
  id: 1788591305,
  member_count: 6,
  name: 'My shared set',
  reference_count: 0,
  resource_name: 'customers/9262111890/sharedSets/1788591305',
  status: 2,
  type: 2,
})

List every instance of SharedSet

The customer.sharedSets.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 SharedSet.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.sharedSets.list({
  constraints: [
    {
      key: 'shared_set.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'shared_set.some_field.sub_field',
})

// Example result
;[
  {
    shared_set: {
      id: 1788591305,
      member_count: 6,
      name: 'My shared set',
      reference_count: 0,
      resource_name: 'customers/9262111890/sharedSets/1788591305',
      status: 2,
      type: 2,
    },
    campaign_shared_set: {
      campaign: 'customers/9262111890/campaigns/1485014801',
      resource_name: 'customers/9262111890/campaignSharedSets/1485014801~1788591305',
      shared_set: 'customers/9262111890/sharedSets/1788591305',
      status: 3,
    },
    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 a SharedSet

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.sharedSets.create([shared_set, other_shared_set], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/sharedSets/1788591305'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a SharedSet

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

Arguments

entity required

The SharedSet 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 shared_set = {
  resource_name: 'customers/9262111890/sharedSets/1788591305', // 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.sharedSets.update(shared_set)

// Passing in an array of entities to update, validating only
const result = await customer.sharedSets.update([shared_set, other_shared_set], {
  validate_only: true,
})

// Example result
{
	results : ['customers/9262111890/sharedSets/1788591305'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a SharedSet

The customer.sharedSets.delete(resource_name) sets the status field of a SharedSet 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 SharedSet

Returns

Nothing

// Deleting the entity

await customer.sharedSets.delete('customers/9262111890/sharedSets/1788591305')

TopicConstant

The TopicConstant object

Fields

id int64

Output only. The ID of the topic.

path array of strings

Output only. The category to target or exclude. Each subsequent element in the array describes a more specific sub-category. For example, {"Pets & Animals", "Pets", "Dogs"} represents the "Pets & Animals/Pets/Dogs" category. List of available topic categories at https://developers.google.com/adwords/api/docs/appendix/verticals

resource_name string

Output only. The resource name of the topic constant. topic constant resource names have the form: topicConstants/{topic_id}

topic_constant_parent string

Output only. Resource name of parent of the topic constant.

// Example TopicConstant
const topic_constant = {
  id: 115,
  path: [
    '',
    'People & Society',
    'Family & Relationships',
    'Family',
    'Parenting',
    'Babies & Toddlers',
    'Baby Care & Hygiene',
  ],
  resource_name: 'topicConstants/115',
  topic_constant_parent: 'topicConstants/1374',
}

Get a TopicConstant

The customer.topicConstants.get(resource_name) method returns the TopicConstant identified by a resource_name.

Arguments

resource_name required

The resource_name of that TopicConstant

Returns

Returns that TopicConstant as an object.

// Getting the entity
let result = await customer.topicConstants.get('topicConstants/115')

// Example result
;({
  id: 115,
  path: [
    '',
    'People & Society',
    'Family & Relationships',
    'Family',
    'Parenting',
    'Babies & Toddlers',
    'Baby Care & Hygiene',
  ],
  resource_name: 'topicConstants/115',
  topic_constant_parent: 'topicConstants/1374',
})

List every instance of TopicConstant

The customer.topicConstants.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 TopicConstant.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.topicConstants.list({
  constraints: [
    {
      key: 'topic_constant.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'topic_constant.some_field.sub_field',
})

// Example result
;[
  {
    topic_constant: {
      id: 115,
      path: [
        '',
        'People & Society',
        'Family & Relationships',
        'Family',
        'Parenting',
        'Babies & Toddlers',
        'Baby Care & Hygiene',
      ],
      resource_name: 'topicConstants/115',
      topic_constant_parent: 'topicConstants/1374',
    },
  },
]

UserInterest

The UserInterest object

Fields

availabilities array of objects

Output only. Availability information of the user interest.

channel object

Channel types and subtypes that are available to the category.

locale array of objects

Locales that are available to the category for the channel.

launched_to_all boolean

Output only. True if the user interest is launched to all channels and locales.

name string

Output only. The name of the user interest.

resource_name string

Output only. The resource name of the user interest. User interest resource names have the form: customers/{customer_id}/userInterests/{user_interest_id}

taxonomy_type enum

Output only. Taxonomy type of the user interest.

user_interest_id int64

Output only. The ID of the user interest.

user_interest_parent string

Output only. The parent of the user interest.

// Example UserInterest
const user_interest = {
  availabilities: [],
  launched_to_all: true,
  name: 'My user interest',
  resource_name: 'customers/9262111890/userInterests/84',
  taxonomy_type: 5,
  user_interest_id: 84,
  user_interest_parent: 'customers/9262111890/userInterests/302',
}

Get a UserInterest

The customer.userInterests.get(resource_name) method returns the UserInterest identified by a resource_name.

Arguments

resource_name required

The resource_name of that UserInterest

Returns

Returns that UserInterest as an object.

// Getting the entity
let result = await customer.userInterests.get('customers/9262111890/userInterests/84')

// Example result
;({
  availabilities: [],
  launched_to_all: true,
  name: 'My user interest',
  resource_name: 'customers/9262111890/userInterests/84',
  taxonomy_type: 5,
  user_interest_id: 84,
  user_interest_parent: 'customers/9262111890/userInterests/302',
})

List every instance of UserInterest

The customer.userInterests.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 UserInterest.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.userInterests.list({
  constraints: [
    {
      key: 'user_interest.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'user_interest.some_field.sub_field',
})

// Example result
;[
  {
    user_interest: {
      availabilities: [],
      launched_to_all: true,
      name: 'My user interest',
      resource_name: 'customers/9262111890/userInterests/84',
      taxonomy_type: 5,
      user_interest_id: 84,
      user_interest_parent: 'customers/9262111890/userInterests/302',
    },
  },
]

UserList

The UserList object

Fields

ONE of the following:

basic_user_list object
User list targeting as a collection of conversion or remarketing actions.
Child Fields
actions array of objects
Actions associated with this user list.
conversion_action string
A conversion action that's not generated from remarketing.
remarketing_action string
A remarketing action.
crm_based_user_list object
User list of CRM users provided by the advertiser.
Child Fields
app_id string
A string that uniquely identifies a mobile application from which the data was collected to the Google Ads API. For iOS, the ID string is the 9 digit string that appears at the end of an App Store URL (e.g., "476943146" for "Flood-It! 2" whose App Store link is http://itunes.apple.com/us/app/flood-it!-2/id476943146). For Android, the ID string is the application's package name (e.g., "com.labpixies.colordrips" for "Color Drips" given Google Play link https://play.google.com/store/apps/details?id=com.labpixies.colordrips). Required when creating CrmBasedUserList for uploading mobile advertising IDs.
data_source_type enum
Data source of the list. Default value is FIRST_PARTY. Only whitelisted customers can create third-party sourced CRM lists.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
FIRST_PARTY (2)
The uploaded data is first-party data.
THIRD_PARTY_CREDIT_BUREAU (3)
The uploaded data is from a third-party credit bureau.
THIRD_PARTY_VOTER_FILE (4)
The uploaded data is from a third-party voter file.
upload_key_type enum
Matching key type of the list. Mixed data types are not allowed on the same list. This field is required for an ADD operation.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
CONTACT_INFO (2)
Members are matched from customer info such as email address, phone number or physical address.
CRM_ID (3)
Members are matched from a user id generated and assigned by the advertiser.
MOBILE_ADVERTISING_ID (4)
Members are matched from mobile advertising ids.
logical_user_list object
User list that is a custom combination of user lists and user interests.
Child Fields
rules array of objects
Logical list rules that define this user list. The rules are defined as a logical operator (ALL/ANY/NONE) and a list of user lists. All the rules are ANDed when they are evaluated. Required for creating a logical user list.
operator enum
The logical operator of the rule.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
ALL (2)
And - all of the operands.
ANY (3)
Or - at least one of the operands.
NONE (4)
Not - none of the operands.
rule_operands array of objects
The list of operands of the rule.
user_list string
Resource name of a user list as an operand.
rule_based_user_list object
User list generated by a rule.
Child Fields
combined_rule_user_list object
User lists defined by combining two rules. There are two operators: AND, where the left and right operands have to be true; AND_NOT where left operand is true but right operand is false.
left_operand object
Left operand of the combined rule. This field is required and must be populated when creating new combined rule based user list.
rule_item_groups array of objects
List of rule item groups that defines this rule. Rule item groups are grouped together based on rule_type.
rule_items array of objects
Rule items that will be grouped together based on rule_type.
date_rule_item object
An atomic rule item composed of a date operation.
offset_in_days int64
The relative date value of the right hand side denoted by number of days offset from now. The value field will override this field when both are present.
operator enum
Date comparison operator. This field is required and must be populated when creating new date rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EQUALS (2)
Equals.
NOT_EQUALS (3)
Not Equals.
BEFORE (4)
Before.
AFTER (5)
After.
value string
String representing date value to be compared with the rule variable. Supported date format is YYYY-MM-DD. Times are reported in the customer's time zone.
name string
Rule variable name. It should match the corresponding key name fired by the pixel. A name must begin with US-ascii letters or underscore or UTF8 code that is greater than 127 and consist of US-ascii letters or digits or underscore or UTF8 code that is greater than 127. For websites, there are two built-in variable URL (name = 'url__') and referrer URL (name = 'ref_url__'). This field must be populated when creating a new rule item.
number_rule_item object
An atomic rule item composed of a number operation.
operator enum
Number comparison operator. This field is required and must be populated when creating a new number rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
GREATER_THAN (2)
Greater than.
GREATER_THAN_OR_EQUAL (3)
Greater than or equal.
EQUALS (4)
Equals.
NOT_EQUALS (5)
Not equals.
LESS_THAN (6)
Less than.
LESS_THAN_OR_EQUAL (7)
Less than or equal.
value double
Number value to be compared with the variable. This field is required and must be populated when creating a new number rule item.
string_rule_item object
An atomic rule item composed of a string operation.
operator enum
String comparison operator. This field is required and must be populated when creating a new string rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
CONTAINS (2)
Contains.
EQUALS (3)
Equals.
STARTS_WITH (4)
Starts with.
ENDS_WITH (5)
Ends with.
NOT_EQUALS (6)
Not equals.
NOT_CONTAINS (7)
Not contains.
NOT_STARTS_WITH (8)
Not starts with.
NOT_ENDS_WITH (9)
Not ends with.
value string
The right hand side of the string rule item. For URLs or referrer URLs, the value can not contain illegal URL chars such as newlines, quotes, tabs, or parentheses. This field is required and must be populated when creating a new string rule item.
rule_type enum
Rule type is used to determine how to group rule items. The default is OR of ANDs (disjunctive normal form). That is, rule items will be ANDed together within rule item groups and the groups themselves will be ORed together. Currently AND of ORs (conjunctive normal form) is only supported for ExpressionRuleUserList.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
AND_OF_ORS (2)
Conjunctive normal form.
OR_OF_ANDS (3)
Disjunctive normal form.
right_operand object
Right operand of the combined rule. This field is required and must be populated when creating new combined rule based user list.
rule_item_groups array of objects
List of rule item groups that defines this rule. Rule item groups are grouped together based on rule_type.
rule_items array of objects
Rule items that will be grouped together based on rule_type.
date_rule_item object
An atomic rule item composed of a date operation.
offset_in_days int64
The relative date value of the right hand side denoted by number of days offset from now. The value field will override this field when both are present.
operator enum
Date comparison operator. This field is required and must be populated when creating new date rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EQUALS (2)
Equals.
NOT_EQUALS (3)
Not Equals.
BEFORE (4)
Before.
AFTER (5)
After.
value string
String representing date value to be compared with the rule variable. Supported date format is YYYY-MM-DD. Times are reported in the customer's time zone.
name string
Rule variable name. It should match the corresponding key name fired by the pixel. A name must begin with US-ascii letters or underscore or UTF8 code that is greater than 127 and consist of US-ascii letters or digits or underscore or UTF8 code that is greater than 127. For websites, there are two built-in variable URL (name = 'url__') and referrer URL (name = 'ref_url__'). This field must be populated when creating a new rule item.
number_rule_item object
An atomic rule item composed of a number operation.
operator enum
Number comparison operator. This field is required and must be populated when creating a new number rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
GREATER_THAN (2)
Greater than.
GREATER_THAN_OR_EQUAL (3)
Greater than or equal.
EQUALS (4)
Equals.
NOT_EQUALS (5)
Not equals.
LESS_THAN (6)
Less than.
LESS_THAN_OR_EQUAL (7)
Less than or equal.
value double
Number value to be compared with the variable. This field is required and must be populated when creating a new number rule item.
string_rule_item object
An atomic rule item composed of a string operation.
operator enum
String comparison operator. This field is required and must be populated when creating a new string rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
CONTAINS (2)
Contains.
EQUALS (3)
Equals.
STARTS_WITH (4)
Starts with.
ENDS_WITH (5)
Ends with.
NOT_EQUALS (6)
Not equals.
NOT_CONTAINS (7)
Not contains.
NOT_STARTS_WITH (8)
Not starts with.
NOT_ENDS_WITH (9)
Not ends with.
value string
The right hand side of the string rule item. For URLs or referrer URLs, the value can not contain illegal URL chars such as newlines, quotes, tabs, or parentheses. This field is required and must be populated when creating a new string rule item.
rule_type enum
Rule type is used to determine how to group rule items. The default is OR of ANDs (disjunctive normal form). That is, rule items will be ANDed together within rule item groups and the groups themselves will be ORed together. Currently AND of ORs (conjunctive normal form) is only supported for ExpressionRuleUserList.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
AND_OF_ORS (2)
Conjunctive normal form.
OR_OF_ANDS (3)
Disjunctive normal form.
rule_operator enum
Operator to connect the two operands. Required for creating a combined rule user list.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
AND (2)
A AND B.
AND_NOT (3)
A AND NOT B.
date_specific_rule_user_list object
Visitors of a page during specific dates. The visiting periods are defined as follows: Between start_date (inclusive) and end_date (inclusive); Before end_date (exclusive) with start_date = 2000-01-01; After start_date (exclusive) with end_date = 2037-12-30.
end_date string
End date of users visit. If set to 2037-12-30, then the list includes all users after start_date. The date's format should be YYYY-MM-DD. Required for creating a data specific rule user list.
rule object
Boolean rule that defines visitor of a page. Required for creating a date specific rule user list.
rule_item_groups array of objects
List of rule item groups that defines this rule. Rule item groups are grouped together based on rule_type.
rule_items array of objects
Rule items that will be grouped together based on rule_type.
date_rule_item object
An atomic rule item composed of a date operation.
offset_in_days int64
The relative date value of the right hand side denoted by number of days offset from now. The value field will override this field when both are present.
operator enum
Date comparison operator. This field is required and must be populated when creating new date rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EQUALS (2)
Equals.
NOT_EQUALS (3)
Not Equals.
BEFORE (4)
Before.
AFTER (5)
After.
value string
String representing date value to be compared with the rule variable. Supported date format is YYYY-MM-DD. Times are reported in the customer's time zone.
name string
Rule variable name. It should match the corresponding key name fired by the pixel. A name must begin with US-ascii letters or underscore or UTF8 code that is greater than 127 and consist of US-ascii letters or digits or underscore or UTF8 code that is greater than 127. For websites, there are two built-in variable URL (name = 'url__') and referrer URL (name = 'ref_url__'). This field must be populated when creating a new rule item.
number_rule_item object
An atomic rule item composed of a number operation.
operator enum
Number comparison operator. This field is required and must be populated when creating a new number rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
GREATER_THAN (2)
Greater than.
GREATER_THAN_OR_EQUAL (3)
Greater than or equal.
EQUALS (4)
Equals.
NOT_EQUALS (5)
Not equals.
LESS_THAN (6)
Less than.
LESS_THAN_OR_EQUAL (7)
Less than or equal.
value double
Number value to be compared with the variable. This field is required and must be populated when creating a new number rule item.
string_rule_item object
An atomic rule item composed of a string operation.
operator enum
String comparison operator. This field is required and must be populated when creating a new string rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
CONTAINS (2)
Contains.
EQUALS (3)
Equals.
STARTS_WITH (4)
Starts with.
ENDS_WITH (5)
Ends with.
NOT_EQUALS (6)
Not equals.
NOT_CONTAINS (7)
Not contains.
NOT_STARTS_WITH (8)
Not starts with.
NOT_ENDS_WITH (9)
Not ends with.
value string
The right hand side of the string rule item. For URLs or referrer URLs, the value can not contain illegal URL chars such as newlines, quotes, tabs, or parentheses. This field is required and must be populated when creating a new string rule item.
rule_type enum
Rule type is used to determine how to group rule items. The default is OR of ANDs (disjunctive normal form). That is, rule items will be ANDed together within rule item groups and the groups themselves will be ORed together. Currently AND of ORs (conjunctive normal form) is only supported for ExpressionRuleUserList.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
AND_OF_ORS (2)
Conjunctive normal form.
OR_OF_ANDS (3)
Disjunctive normal form.
start_date string
Start date of users visit. If set to 2000-01-01, then the list includes all users before end_date. The date's format should be YYYY-MM-DD. Required for creating a data specific rule user list.
expression_rule_user_list object
Visitors of a page. The page visit is defined by one boolean rule expression.
rule object
Boolean rule that defines this user list. The rule consists of a list of rule item groups and each rule item group consists of a list of rule items. All the rule item groups are ORed or ANDed together for evaluation based on rule.rule_type. Required for creating an expression rule user list.
rule_item_groups array of objects
List of rule item groups that defines this rule. Rule item groups are grouped together based on rule_type.
rule_items array of objects
Rule items that will be grouped together based on rule_type.
date_rule_item object
An atomic rule item composed of a date operation.
offset_in_days int64
The relative date value of the right hand side denoted by number of days offset from now. The value field will override this field when both are present.
operator enum
Date comparison operator. This field is required and must be populated when creating new date rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
EQUALS (2)
Equals.
NOT_EQUALS (3)
Not Equals.
BEFORE (4)
Before.
AFTER (5)
After.
value string
String representing date value to be compared with the rule variable. Supported date format is YYYY-MM-DD. Times are reported in the customer's time zone.
name string
Rule variable name. It should match the corresponding key name fired by the pixel. A name must begin with US-ascii letters or underscore or UTF8 code that is greater than 127 and consist of US-ascii letters or digits or underscore or UTF8 code that is greater than 127. For websites, there are two built-in variable URL (name = 'url__') and referrer URL (name = 'ref_url__'). This field must be populated when creating a new rule item.
number_rule_item object
An atomic rule item composed of a number operation.
operator enum
Number comparison operator. This field is required and must be populated when creating a new number rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
GREATER_THAN (2)
Greater than.
GREATER_THAN_OR_EQUAL (3)
Greater than or equal.
EQUALS (4)
Equals.
NOT_EQUALS (5)
Not equals.
LESS_THAN (6)
Less than.
LESS_THAN_OR_EQUAL (7)
Less than or equal.
value double
Number value to be compared with the variable. This field is required and must be populated when creating a new number rule item.
string_rule_item object
An atomic rule item composed of a string operation.
operator enum
String comparison operator. This field is required and must be populated when creating a new string rule item.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
CONTAINS (2)
Contains.
EQUALS (3)
Equals.
STARTS_WITH (4)
Starts with.
ENDS_WITH (5)
Ends with.
NOT_EQUALS (6)
Not equals.
NOT_CONTAINS (7)
Not contains.
NOT_STARTS_WITH (8)
Not starts with.
NOT_ENDS_WITH (9)
Not ends with.
value string
The right hand side of the string rule item. For URLs or referrer URLs, the value can not contain illegal URL chars such as newlines, quotes, tabs, or parentheses. This field is required and must be populated when creating a new string rule item.
rule_type enum
Rule type is used to determine how to group rule items. The default is OR of ANDs (disjunctive normal form). That is, rule items will be ANDed together within rule item groups and the groups themselves will be ORed together. Currently AND of ORs (conjunctive normal form) is only supported for ExpressionRuleUserList.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
AND_OF_ORS (2)
Conjunctive normal form.
OR_OF_ANDS (3)
Disjunctive normal form.
prepopulation_status enum
The status of pre-population. The field is default to NONE if not set which means the previous users will not be considered. If set to REQUESTED, past site visitors or app users who match the list definition will be included in the list (works on the Display Network only). This will only add past users from within the last 30 days, depending on the list's membership duration and the date when the remarketing tag is added. The status will be updated to FINISHED once request is processed, or FAILED if the request fails.
UNSPECIFIED (0)
Not specified.
UNKNOWN (1)
Used for return value only. Represents value unknown in this version.
REQUESTED (2)
Prepopoulation is being requested.
FINISHED (3)
Prepopulation is finished.
FAILED (4)
Prepopulation failed.
similar_user_list object
Output only. User list which are similar to users from another UserList. These lists are readonly and automatically created by google.
Child Fields
seed_user_list string
Seed UserList from which this list is derived.

access_reason enum

Output only. Indicates the reason this account has been granted access to the list. The reason can be SHARED, OWNED, LICENSED or SUBSCRIBED. This field is read-only.

account_user_list_status enum

Indicates if this share is still enabled. When a UserList is shared with the user this field is set to ENABLED. Later the userList owner can decide to revoke the share and make it DISABLED. The default value of this field is set to ENABLED.

closing_reason enum

Indicating the reason why this user list membership status is closed. It is only populated on lists that were automatically closed due to inactivity, and will be cleared once the list membership status becomes open.

description string

Description of this user list.

eligible_for_display boolean

Output only. Indicates this user list is eligible for Google Display Network. This field is read-only.

eligible_for_search boolean

Indicates if this user list is eligible for Google Search Network.

id int64

Output only. Id of the user list.

integration_code string

An ID from external system. It is used by user list sellers to correlate IDs on their systems.

membership_life_span int64

Number of days a user's cookie stays on your list since its most recent addition to the list. This field must be between 0 and 540 inclusive. However, for CRM based userlists, this field can be set to 10000 which means no expiration. It'll be ignored for logical_user_list.

membership_status enum

Membership status of this user list. Indicates whether a user list is open or active. Only open user lists can accumulate more users and can be targeted to.

name string

Name of this user list. Depending on its access_reason, the user list name may not be unique (e.g. if access_reason=SHARED)

read_only boolean

Output only. A flag that indicates if a user may edit a list. Depends on the list ownership and list type. For example, external remarketing user lists are not editable. This field is read-only.

resource_name string

Immutable. The resource name of the user list. User list resource names have the form: customers/{customer_id}/userLists/{user_list_id}

size_for_display int64

Output only. Estimated number of users in this user list, on the Google Display Network. This value is null if the number of users has not yet been determined. This field is read-only.

size_for_search int64

Output only. Estimated number of users in this user list in the google.com domain. These are the users available for targeting in Search campaigns. This value is null if the number of users has not yet been determined. This field is read-only.

size_range_for_display enum

Output only. Size range in terms of number of users of the UserList, on the Google Display Network. This field is read-only.

size_range_for_search enum

Output only. Size range in terms of number of users of the UserList, for Search ads. This field is read-only.

type enum

Output only. Type of this list. This field is read-only.

// Example UserList
const user_list = {
  access_reason: 2,
  account_user_list_status: 2,
  closing_reason: 0,
  description: 'Combined audience based on available data sources',
  eligible_for_display: true,
  eligible_for_search: true,
  id: 509186086,
  logical_user_list: {
    rules: [
      {
        operator: 3,
        rule_operands_list: [
          { user_list: 'customers/3827277046/userLists/814539380' },
          { user_list: 'customers/3827277046/userLists/508846109' },
          { user_list: 'customers/3827277046/userLists/614318739' },
        ],
      },
    ],
  },
  membership_life_span: 30,
  membership_status: 2,
  name: 'My user list',
  read_only: true,
  resource_name: 'customers/3827277046/userLists/509186086',
  size_for_display: 320,
  size_for_search: 490,
  size_range_for_display: 2,
  size_range_for_search: 2,
  type: 3,
}

Get a UserList

The customer.userLists.get(resource_name) method returns the UserList identified by a resource_name.

Arguments

resource_name required

The resource_name of that UserList

Returns

Returns that UserList as an object.

// Getting the entity
let result = await customer.userLists.get('customers/3827277046/userLists/509186086')

// Example result
;({
  access_reason: 2,
  account_user_list_status: 2,
  closing_reason: 0,
  description: 'Combined audience based on available data sources',
  eligible_for_display: true,
  eligible_for_search: true,
  id: 509186086,
  logical_user_list: {
    rules: [
      {
        operator: 3,
        rule_operands_list: [
          { user_list: 'customers/3827277046/userLists/814539380' },
          { user_list: 'customers/3827277046/userLists/508846109' },
          { user_list: 'customers/3827277046/userLists/614318739' },
        ],
      },
    ],
  },
  membership_life_span: 30,
  membership_status: 2,
  name: 'My user list',
  read_only: true,
  resource_name: 'customers/3827277046/userLists/509186086',
  size_for_display: 320,
  size_for_search: 490,
  size_range_for_display: 2,
  size_range_for_search: 2,
  type: 3,
})

List every instance of UserList

The customer.userLists.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 UserList.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.userLists.list({
  constraints: [
    {
      key: 'user_list.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'user_list.some_field.sub_field',
})

// Example result
;[
  {
    user_list: {
      access_reason: 2,
      account_user_list_status: 2,
      closing_reason: 0,
      description: 'Combined audience based on available data sources',
      eligible_for_display: true,
      eligible_for_search: true,
      id: 509186086,
      logical_user_list: {
        rules: [
          {
            operator: 3,
            rule_operands_list: [
              { user_list: 'customers/3827277046/userLists/814539380' },
              { user_list: 'customers/3827277046/userLists/508846109' },
              { user_list: 'customers/3827277046/userLists/614318739' },
            ],
          },
        ],
      },
      membership_life_span: 30,
      membership_status: 2,
      name: 'My user list',
      read_only: true,
      resource_name: 'customers/3827277046/userLists/509186086',
      size_for_display: 320,
      size_for_search: 490,
      size_range_for_display: 2,
      size_range_for_search: 2,
      type: 3,
    },
    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 a UserList

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

Arguments

entity required

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

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

// Passing in an array of entities to create, validating only
const result = await customer.userLists.create([user_list, other_user_list], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/userLists/509186086'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Update a UserList

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

Arguments

entity required

The UserList 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 user_list = {
  resource_name: 'customers/3827277046/userLists/509186086', // 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.userLists.update(user_list)

// Passing in an array of entities to update, validating only
const result = await customer.userLists.update([user_list, other_user_list], {
  validate_only: true,
})

// Example result
{
	results : ['customers/3827277046/userLists/509186086'],
	partial_failure_error : null,
	request: { /* your request object */ }
}

Delete a UserList

The customer.userLists.delete(resource_name) sets the status field of a UserList 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 UserList

Returns

Nothing

// Deleting the entity

await customer.userLists.delete('customers/3827277046/userLists/509186086')

Video

The Video object

Fields

channel_id string

Output only. The owner channel id of the video.

duration_millis int64

Output only. The duration of the video in milliseconds.

id string

Output only. The ID of the video.

resource_name string

Output only. The resource name of the video. Video resource names have the form: customers/{customer_id}/videos/{video_id}

title string

Output only. The title of the video.

// Example Video
const video = {
  channel_id: 'UCOSYb4yvogm0SAI8rX8kGWQ',
  duration_millis: 40356,
  id: 'V_jS8nLLpZI',
  resource_name: 'customers/3827277046/videos/Vl9qUzhuTExwWkk',
  title: 'Opteo',
}

Get a Video

The customer.videos.get(resource_name) method returns the Video identified by a resource_name.

Arguments

resource_name required

The resource_name of that Video

Returns

Returns that Video as an object.

// Getting the entity
let result = await customer.videos.get('customers/3827277046/videos/Vl9qUzhuTExwWkk')

// Example result
;({
  channel_id: 'UCOSYb4yvogm0SAI8rX8kGWQ',
  duration_millis: 40356,
  id: 'V_jS8nLLpZI',
  resource_name: 'customers/3827277046/videos/Vl9qUzhuTExwWkk',
  title: 'Opteo',
})

List every instance of Video

The customer.videos.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 Video.

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

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

// Listing with constraints, sorting, and a limited number of results
let result = await customer.videos.list({
  constraints: [
    {
      key: 'video.some_field',
      op: '=',
      val: 'yellow submarine',
    },
  ],
  limit: 15,
  order_by: 'video.some_field.sub_field',
})

// Example result
;[
  {
    video: {
      channel_id: 'UCOSYb4yvogm0SAI8rX8kGWQ',
      duration_millis: 40356,
      id: 'V_jS8nLLpZI',
      resource_name: 'customers/3827277046/videos/Vl9qUzhuTExwWkk',
      title: 'Opteo',
    },
    ad_group_ad: {
      ad: {
        added_by_google_ads: false,
        device_preference: 0,
        display_url: 'opteo.com',
        final_app_urls: [],
        final_mobile_urls: [],
        final_urls: ['https://opteo.com'],
        id: 376678647998,
        name: 'Animation',
        resource_name: 'customers/3827277046/ads/376678647998',
        system_managed_resource_source: 0,
        type: 29,
        url_collections: [],
        url_custom_parameters: [],
        video_ad: {
          in_stream: { companion_banner: 'customers/3827277046/mediaFiles/4570107325' },
          media_file: 'customers/3827277046/mediaFiles/4565915444',
        },
      },
      ad_group: 'customers/3827277046/adGroups/55719719421',
      ad_strength: 0,
      policy_summary: { approval_status: 4, policy_topic_entries: [], review_status: 3 },
      resource_name: 'customers/3827277046/adGroupAds/55719719421~376678647998',
      status: 2,
    },
    ad_group: {
      ad_rotation_mode: 0,
      base_ad_group: 'customers/3827277046/adGroups/55719719421',
      campaign: 'customers/3827277046/campaigns/1546686126',
      cpc_bid_micros: 0,
      cpm_bid_micros: 10000,
      cpv_bid_micros: 100000,
      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: 55719719421,
      labels: [],
      name: 'My ad group',
      resource_name: 'customers/3827277046/adGroups/55719719421',
      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: 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: 9,
      url_custom_parameters: [],
    },
    campaign: {
      ad_serving_optimization_status: 2,
      advertising_channel_sub_type: 0,
      advertising_channel_type: 6,
      base_campaign: 'customers/3827277046/campaigns/1546686126',
      bidding_strategy_type: 13,
      campaign_budget: 'customers/3827277046/campaignBudgets/1601905358',
      end_date: '2037-12-30',
      experiment_type: 2,
      frequency_caps: [{ key: { level: 4, event_type: 2, time_unit: 2, time_length: 1 }, cap: 1 }],
      geo_target_type_setting: { negative_geo_target_type: 5, positive_geo_target_type: 7 },
      id: 1546686126,
      labels: ['customers/3827277046/labels/3353203258'],
      manual_cpv: {},
      name: 'My campaign',
      network_settings: {
        target_content_network: false,
        target_google_search: false,
        target_partner_search_network: false,
        target_search_network: false,
      },
      payment_mode: 4,
      resource_name: 'customers/3827277046/campaigns/1546686126',
      serving_status: 2,
      start_date: '2018-09-07',
      status: 2,
      url_custom_parameters: [],
      video_brand_safety_suitability: 3,
    },
    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}',
    },
  },
]

Google Ads API

Unofficial Google Ads API client library for Node

Overview

Features

Installation

Why does this library exist?

Google Ads API versions

Authentication

Reporting

Resources

Fields

Using GAQL

Using the query builder

Using Report Stream

Mutations

Making changes using core resources

Create

Update

Delete

Atomic mutations using customer.mutateResources()

Enums

Handling Errors with Enums

Utilities

Typescript

Changelog

FAQ

Core resources

AccountBudget

The AccountBudget object

Fields

Get an AccountBudget

Arguments

resource_name required

Returns

List every instance of AccountBudget

Arguments

options optional

limit optional, number

order_by optional, string

constraints optional, array/object

Returns

AccountBudgetProposal

The AccountBudgetProposal object

Fields

Get an AccountBudgetProposal

Arguments

resource_name required

Returns

List every instance of AccountBudgetProposal

Arguments

options optional

limit optional, number

order_by optional, string

constraints optional, array/object

Returns

Create an AccountBudgetProposal

Arguments

entity required

options optional

validate_only optional, boolean

partial_failure optional, boolean

Returns

results

partial_failure_error

request

Update an AccountBudgetProposal

Arguments

entity required

options optional

validate_only optional, boolean

partial_failure optional, boolean

Returns

results

partial_failure_error

request

Delete an AccountBudgetProposal

Arguments

resource_name required

Returns

Ad

Atomic mutations using `customer.mutateResources()`