Share your feedback about the Google Ads API! Take our annual survey.

Package google.ads.googleads.v0.resources

Index

AccountBudget

An account-level budget.

Fields
resource_name

string

The resource name of the account-level budget. AccountBudget resource names have the form:

customers/{customer_id}/accountBudgets/{account_budget_id}

AccountBudgetProposal

An account-level budget proposal.

All fields prefixed with 'proposed' may not necessarily be applied directly. For example, proposed spending limits may be adjusted before their application. This is true if the 'proposed' field has an 'approved' counterpart, to be introduced in a future version.

Please note that the proposal type (proposal_type) changes which fields are required and which must remain empty.

Fields
resource_name

string

The resource name of the proposal. AccountBudgetProposal resource names have the form:

customers/{customer_id}/accountBudgetProposals/{account_budget_proposal_id}

id

Int64Value

The ID of the proposal.

billing_setup

StringValue

The resource name of the billing setup associated with this proposal.

account_budget

StringValue

The resource name of the account-level budget associated with this proposal.

proposal_type

AccountBudgetProposalType

The type of this proposal, e.g. END to end the budget associated with this proposal.

status

AccountBudgetProposalStatus

The status of this proposal. When a new proposal is created, the status defaults to PENDING.

proposed_name

StringValue

The name to assign to the account-level budget.

proposed_purchase_order_number

StringValue

A purchase order number is a value that enables the user to help them reference this budget in their monthly invoices.

proposed_notes

StringValue

Notes associated with this budget.

creation_date_time

StringValue

The date time when this account-level budget proposal was created, which is not the same as its approval date time, if applicable.

approval_date_time

StringValue

The date time when this account-level budget was approved, if applicable.

Union field proposed_start_time. The proposed start date time of the account-level budget, which cannot be in the past. proposed_start_time can be only one of the following:
proposed_start_date_time

StringValue

The proposed start date time in yyyy-MM-dd HH:mm:ss format.

proposed_start_time_type

TimeType

The proposed start date time as a well-defined type, e.g. NOW.

Union field proposed_end_time. The proposed end date time of the account-level budget, which cannot be in the past. proposed_end_time can be only one of the following:
proposed_end_date_time

StringValue

The proposed end date time in yyyy-MM-dd HH:mm:ss format.

proposed_end_time_type

TimeType

The proposed end date time as a well-defined type, e.g. INDEFINITE.

Union field proposed_spending_limit. The proposed spending limit. proposed_spending_limit can be only one of the following:
proposed_spending_limit_micros

Int64Value

The proposed spending limit in micros. One million is equivalent to one unit.

proposed_spending_limit_type

SpendingLimitType

The proposed spending limit as a well-defined type, e.g. INFINITE.

Ad

An ad.

Fields
id

Int64Value

The ID of the ad.

final_urls[]

StringValue

The list of possible final URLs after all cross-domain redirects for the ad.

final_mobile_urls[]

StringValue

The list of possible final mobile URLs after all cross-domain redirects for the ad.

tracking_url_template

StringValue

The URL template for constructing a tracking URL.

url_custom_parameters[]

CustomParameter

The list of mappings that can be used to substitute custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls.

display_url

StringValue

The URL that appears in the ad description for some ad formats.

type

AdType

The type of ad.

added_by_google_ads

BoolValue

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

Device

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.

Union field ad_data. Details pertinent to the ad type. Exactly one value must be set. ad_data can be only one of the following:
text_ad

TextAdInfo

Details pertaining to a text ad.

expanded_text_ad

ExpandedTextAdInfo

Details pertaining to an expanded text ad.

dynamic_search_ad

DynamicSearchAdInfo

Details pertaining to a Dynamic Search Ad.

responsive_display_ad

ResponsiveDisplayAdInfo

Details pertaining to a responsive display ad.

call_only_ad

CallOnlyAdInfo

Details pertaining to a call-only ad.

expanded_dynamic_search_ad

ExpandedDynamicSearchAdInfo

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.

hotel_ad

HotelAdInfo

Details pertaining to a hotel ad.

shopping_smart_ad

ShoppingSmartAdInfo

Details pertaining to a Smart Shopping ad.

shopping_product_ad

ShoppingProductAdInfo

Details pertaining to a Shopping product ad.

AdGroup

An ad group.

Fields
resource_name

string

The resource name of the ad group. Ad group resource names have the form:

customers/{customer_id}/adGroups/{ad_group_id}

id

Int64Value

The ID of the ad group.

name

StringValue

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.

status

AdGroupStatus

The status of the ad group.

type

AdGroupType

The type of the ad group.

tracking_url_template

StringValue

The URL template for constructing a tracking URL.

url_custom_parameters[]

CustomParameter

The list of mappings used to substitute custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls.

campaign

StringValue

The campaign to which the ad group belongs.

This field must not be used in WHERE clauses.

cpc_bid_micros

Int64Value

The maximum CPC (cost-per-click) bid.

cpm_bid_micros

Int64Value

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

cpa_bid_micros

Int64Value

The target cost-per-acquisition (conversion) bid.

cpv_bid_micros

Int64Value

The CPV (cost-per-view) bid.

target_roas_override

DoubleValue

The target return on ad spend (ROAS) 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.

percent_cpc_bid_micros

Int64Value

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

AdGroupAd

An ad group ad.

Fields
resource_name

string

The resource name of the ad. Ad group ad resource names have the form:

customers/{customer_id}/adGroupAds/{ad_group_id}_{ad_id}

status

AdGroupAdStatus

The status of the ad.

ad_group

StringValue

The ad group to which the ad belongs.

This field must not be used in WHERE clauses.

ad

Ad

The ad.

policy_summary

AdGroupAdPolicySummary

Policy information for the ad.

AdGroupAdPolicySummary

Contains policy information for an ad.

Fields
policy_topic_entries[]

PolicyTopicEntry

The list of policy findings for this ad.

review_status

PolicyReviewStatus

Where in the review process this ad is.

approval_status

PolicyApprovalStatus

The overall approval status of this ad, calculated based on the status of its individual policy topic entries.

AdGroupBidModifier

Represents an ad group bid modifier.

Fields
resource_name

string

The resource name of the ad group bid modifier. Ad group bid modifier resource names have the form:

customers/{customer_id}/adGroupBidModifiers/{ad_group_id}_{criterion_id}

ad_group

StringValue

The ad group to which this criterion belongs.

This field must not be used in WHERE clauses.

criterion_id

Int64Value

The ID of the criterion to bid modify.

This field is ignored for mutates.

bid_modifier

DoubleValue

The modifier for the bid when the criterion matches.

base_ad_group

StringValue

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_source

BidModifierSource

Bid modifier source.

Union field criterion. The criterion of this ad group bid modifier. criterion can be only one of the following:
hotel_date_selection_type

HotelDateSelectionTypeInfo

Criterion for hotel date selection (default dates vs. user selected).

hotel_advance_booking_window

HotelAdvanceBookingWindowInfo

Criterion for number of days prior to the stay the booking is being made.

hotel_length_of_stay

HotelLengthOfStayInfo

Criterion for length of hotel stay in nights.

hotel_check_in_day

HotelCheckInDayInfo

Criterion for day of the week the booking is for.

device

DeviceInfo

A device criterion.

AdGroupCriterion

An ad group criterion.

Fields
resource_name

string

The resource name of the ad group criterion. Ad group criterion resource names have the form:

customers/{customer_id}/adGroupCriteria/{ad_group_id}_{criterion_id}

criterion_id

Int64Value

The ID of the criterion.

This field is ignored for mutates.

status

AdGroupCriterionStatus

The status of the criterion.

quality_info

QualityInfo

Information regarding the quality of the criterion.

ad_group

StringValue

The ad group to which the criterion belongs.

This field must not be used in WHERE clauses.

type

CriterionType

The type of the criterion.

negative

BoolValue

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.

cpc_bid_micros

Int64Value

The CPC (cost-per-click) bid.

cpm_bid_micros

Int64Value

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

cpv_bid_micros

Int64Value

The CPV (cost-per-view) bid.

percent_cpc_bid_micros

Int64Value

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

effective_cpc_bid_micros

Int64Value

The effective CPC (cost-per-click) bid.

effective_cpm_bid_micros

Int64Value

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

effective_cpv_bid_micros

Int64Value

The effective CPV (cost-per-view) bid.

effective_percent_cpc_bid_micros

Int64Value

The effective Percent CPC bid amount.

effective_cpc_bid_source

BiddingSource

Source of the effective CPC bid.

effective_cpm_bid_source

BiddingSource

Source of the effective CPM bid.

effective_cpv_bid_source

BiddingSource

Source of the effective CPV bid.

effective_percent_cpc_bid_source

BiddingSource

Source of the effective Percent CPC bid.

position_estimates

PositionEstimates

Estimates for criterion bids at various positions.

final_urls[]

StringValue

The list of possible final URLs after all cross-domain redirects for the ad.

tracking_url_template

StringValue

The URL template for constructing a tracking URL.

url_custom_parameters[]

CustomParameter

The list of mappings used to substitute custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls.

Union field criterion. The ad group criterion.

Exactly one must be set. criterion can be only one of the following:

keyword

KeywordInfo

Keyword.

listing_group

ListingGroupInfo

Listing group.

PositionEstimates

Estimates for criterion bids at various positions.

Fields
first_page_cpc_micros

Int64Value

The estimate of the CPC bid required for ad to be shown on first page of search results.

first_position_cpc_micros

Int64Value

The estimate of the CPC bid required for ad to be displayed in first position, at the top of the first page of search results.

top_of_page_cpc_micros

Int64Value

The estimate of the CPC bid required for ad to be displayed at the top of the first page of search results.

QualityInfo

A container for ad group criterion quality information.

Fields
quality_score

Int32Value

The quality score.

This field may not be populated if Google does not have enough information to determine a value.

creative_quality_score

QualityScoreBucket

The performance of the ad compared to other advertisers.

post_click_quality_score

QualityScoreBucket

The quality score of the landing page.

search_predicted_ctr

QualityScoreBucket

The click-through rate compared to that of other advertisers.

BiddingStrategy

A bidding strategy.

Fields
resource_name

string

The resource name of the bidding strategy. Bidding strategy resource names have the form:

customers/{customer_id}/biddingStrategies/{bidding_strategy_id}

id

Int64Value

The ID of the bidding strategy.

name

StringValue

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

type

BiddingStrategyType

The type of the bidding strategy. Create a bidding strategy by setting the bidding scheme.

This field is read-only.

Union field scheme. The bidding scheme.

Only one can be set. scheme can be only one of the following:

enhanced_cpc

EnhancedCpc

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.

page_one_promoted

PageOnePromoted

A bidding strategy that sets max CPC bids to target impressions on page one or page one promoted slots on google.com.

target_cpa

TargetCpa

A bidding strategy that sets bids to help get as many conversions as possible at the target cost-per-acquisition (CPA) you set.

target_outrank_share

TargetOutrankShare

A bidding strategy that sets bids based on the target fraction of auctions where the advertiser should outrank a specific competitor.

target_roas

TargetRoas

A bidding strategy that helps you maximize revenue while averaging a specific target Return On Ad Spend (ROAS).

target_spend

TargetSpend

A bid strategy that sets your bids to help get as many clicks as possible within your budget.

BillingSetup

A billing setup across Ads and Payments systems; an association between a Payments account and an advertiser. A billing setup is specific to one advertiser.

Fields
resource_name

string

The resource name of the billing setup. BillingSetup resource names have the form:

customers/{customer_id}/billingSetups/{billing_setup_id}

id

Int64Value

The ID of the billing setup.

status

BillingSetupStatus

The status of the billing setup.

payments_account_id

StringValue

A 16 digit id used to identify the Payments account associated with the billing setup.

This must be passed as a string with dashes, e.g. "1234-5678-9012-3456".

payments_account_name

StringValue

The name of the Payments account associated with the billing setup.

This enables the user to specify a meaningful name for a Payments account to aid in reconciling monthly invoices.

This name will be printed in the monthly invoices.

payments_profile_id

StringValue

A 12 digit id used to identify the Payments profile associated with the billing setup.

This must be passed in as a string with dashes, e.g. "1234-5678-9012".

payments_profile_name

StringValue

The name of the Payments profile associated with the billing setup.

secondary_payments_profile_id

StringValue

A secondary payments profile id present in uncommon situations, e.g. when a sequential liability agreement has been arranged.

Campaign

A campaign.

Fields
resource_name

string

The resource name of the campaign. Campaign resource names have the form:

customers/{customer_id}/campaigns/{campaign_id}

id

Int64Value

The ID of the campaign.

name

StringValue

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.

status

CampaignStatus

The status of the campaign.

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

serving_status

CampaignServingStatus

The ad serving status of the campaign.

ad_serving_optimization_status

AdServingOptimizationStatus

The ad serving optimization status of the campaign.

advertising_channel_type

AdvertisingChannelType

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.

advertising_channel_sub_type

AdvertisingChannelSubType

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.

tracking_url_template

StringValue

The URL template for constructing a tracking URL.

url_custom_parameters[]

CustomParameter

The list of mappings used to substitute custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls.

network_settings

NetworkSettings

The network settings for the campaign.

hotel_setting

HotelSettingInfo

The hotel setting for the campaign.

dynamic_search_ads_setting

DynamicSearchAdsSetting

The setting for controlling Dynamic Search Ads (DSA).

shopping_setting

ShoppingSetting

The setting for controlling Shopping campaigns.

campaign_budget

StringValue

The budget of the campaign.

This field must not be used in WHERE clauses.

bidding_strategy_type

BiddingStrategyType

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.

start_date

StringValue

The date when campaign started.

This field must not be used in WHERE clauses.

campaign_group

StringValue

The campaign group this campaign belongs to.

end_date

StringValue

The date when campaign ended.

This field must not be used in WHERE clauses.

Union field campaign_bidding_strategy. The bidding strategy for the campaign.

Must be either portfolio (created via BiddingStrategy service) or standard, that is embedded into the campaign. campaign_bidding_strategy can be only one of the following:

bidding_strategy

StringValue

Portfolio bidding strategy used by campaign.

This field must not be used in WHERE clauses.

manual_cpc

ManualCpc

Standard Manual CPC bidding strategy. Manual click-based bidding where user pays per click.

manual_cpm

ManualCpm

Standard Manual CPM bidding strategy. Manual impression-based bidding where user pays per thousand impressions.

manual_cpv

ManualCpv

A bidding strategy that pays a configurable amount per video view.

maximize_conversions

MaximizeConversions

Standard Maximize Conversions bidding strategy that automatically maximizes number of conversions given a daily budget.

maximize_conversion_value

MaximizeConversionValue

Standard Maximize Conversion Value bidding strategy that automatically sets bids to maximize revenue while spending your budget.

target_cpa

TargetCpa

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.

target_roas

TargetRoas

Standard Target ROAS bidding strategy that automatically maximizes revenue while averaging a specific target return on ad spend (ROAS).

target_spend

TargetSpend

Standard Target Spend bidding strategy that automatically sets your bids to help get as many clicks as possible within your budget.

percent_cpc

PercentCpc

Standard Percent Cpc bidding strategy where bids are a fraction of the advertised price for some good or service.

DynamicSearchAdsSetting

The setting for controlling Dynamic Search Ads (DSA).

Fields
domain_name

StringValue

The Internet domain name that this setting represents, e.g., "google.com" or "www.google.com".

language_code

StringValue

The language code specifying the language of the domain, e.g., "en".

use_supplied_urls_only

BoolValue

Whether the campaign uses advertiser supplied URLs exclusively.

feed_ids[]

Int64Value

The list of page feeds associated with the campaign.

HotelSettingInfo

Campaign-level settings for hotel ads.

Fields
hotel_center_id

Int64Value

The linked Hotel Center account.

NetworkSettings

The network settings for the campaign.

Fields
target_search_network

BoolValue

Whether ads will be served on partner sites in the Google Search Network (requires target_google_search to also be true).

target_content_network

BoolValue

Whether ads will be served on specified placements in the Google Display Network. Placements are specified using the Placement criterion.

target_partner_search_network

BoolValue

Whether ads will be served on the Google Partner Network. This is available only to some select Google partner accounts.

ShoppingSetting

The setting for Shopping campaigns. Defines the universe of products that can be advertised by the campaign, and how this campaign interacts with other Shopping campaigns.

Fields
merchant_id

Int64Value

ID of the Merchant Center account. This field is required for create operations. This field is immutable for Shopping campaigns.

sales_country

StringValue

Sales country of products to include in the campaign. This field is required for Shopping campaigns. This field is immutable. This field is optional for non-Shopping campaigns, but it must be equal to 'ZZ' if set.

campaign_priority

Int32Value

Priority of the campaign. Campaigns with numerically higher priorities take precedence over those with lower priorities. This field is required for Shopping campaigns, with values between 0 and 2, inclusive. This field is optional for Smart Shopping campaigns, but must be equal to 3 if set.

enable_local

BoolValue

Enable local inventory ads.

CampaignBidModifier

Represents a bid-modifiable only criterion at the campaign level.

Fields
resource_name

string

The resource name of the campaign bid modifier. Campaign bid modifier resource names have the form:

customers/{customer_id}/campaignBidModifiers/{campaign_id}_{criterion_id}

campaign

StringValue

The campaign to which this criterion belongs.

criterion_id

Int64Value

The ID of the criterion to bid modify.

This field is ignored for mutates.

bid_modifier

DoubleValue

The modifier for the bid when the criterion matches.

interaction_type

InteractionTypeInfo

Criterion for interaction type. Only supported for search campaigns.

CampaignBudget

A campaign budget.

Fields
resource_name

string

The resource name of the campaign budget. Campaign budget resource names have the form:

customers/{customer_id}/campaignBudgets/{budget_id}

id

Int64Value

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

StringValue

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

amount_micros

Int64Value

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.

status

BudgetStatus

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

delivery_method

BudgetDeliveryMethod

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

BoolValue

Whether the budget is explicitly shared. This field is set to false by default.

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.

reference_count

Int64Value

The number of campaigns actively using the budget.

This field is read-only.

CampaignCriterion

A campaign criterion.

Fields
resource_name

string

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

customers/{customer_id}/campaignCriteria/{campaign_id}_{criterion_id}

campaign

StringValue

The campaign to which the criterion belongs.

This field must not be used in WHERE clauses.

criterion_id

Int64Value

The ID of the criterion.

This field is ignored during mutate.

bid_modifier

FloatValue

The modifier for the bids when the criterion matches. Allowable modifier values depend on the criterion: - 0.1 - 10.0: Location - 0.1 - 4.0: Device (mobile). Use 0 to opt out of mobile.

negative

BoolValue

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

type

CriterionType

The type of the criterion.

Union field criterion. The campaign criterion.

Exactly one must be set. criterion can be only one of the following:

keyword

KeywordInfo

Keyword.

location

LocationInfo

Location.

device

DeviceInfo

Device.

ad_schedule

AdScheduleInfo

Ad Schedule.

CampaignGroup

A campaign group.

Fields
resource_name

string

The resource name of the campaign group. Campaign group resource names have the form:

customers/{customer_id}/campaignGroups/{campaign_group_id}

id

Int64Value

The ID of the campaign group.

name

StringValue

The name of the campaign group.

This field is required and should not be empty when creating new campaign groups.

It must not contain any null (code point 0x0), NL line feed (code point 0xA) or carriage return (code point 0xD) characters.

status

CampaignGroupStatus

The status of the campaign group.

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

CampaignSharedSet

CampaignSharedSets are used for managing the shared sets associated with a campaign.

Fields
resource_name

string

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}

campaign

StringValue

The campaign to which the campaign shared set belongs.

shared_set

StringValue

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

CampaignSharedSetStatus

The status of this campaign shared set. Read only.

ChangeStatus

Describes the status of returned resource.

Fields
resource_name

string

The resource name of the change status. Change status resource names have the form:

customers/{customer_id}/changeStatus/{change_status_id}

last_change_date_time

StringValue

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

resource_type

ResourceType

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.

campaign

StringValue

The Campaign affected by this change.

ad_group

StringValue

The AdGroup affected by this change.

resource_status

ChangeStatusOperation

Represents the status of the changed resource.

ad_group_ad

StringValue

The AdGroupAd affected by this change.

ad_group_criterion

StringValue

The AdGroupCriterion affected by this change.

campaign_criterion

StringValue

The CampaignCriterion affected by this change.

ConversionAction

A conversion action.

Fields
resource_name

string

The resource name of the conversion action. Conversion action resource names have the form:

customers/{customer_id}/conversionActions/{conversion_action_id}

id

Int64Value

The ID of the conversion action.

name

StringValue

The name of the conversion action.

This field is required and should not be empty when creating new conversion actions.

status

ConversionActionStatus

The status of this conversion action for conversion event accrual.

type

ConversionActionType

The type of this conversion action.

category

ConversionActionCategory

The category of conversions reported for this conversion action.

owner_customer

StringValue

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

include_in_conversions_metric

BoolValue

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

click_through_lookback_window_days

Int64Value

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

view_through_lookback_window_days

Int64Value

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

value_settings

ValueSettings

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

counting_type

ConversionActionCountingType

How to count conversion events for the conversion action.

attribution_model_settings

AttributionModelSettings

Settings related to this conversion action's attribution model.

tag_snippets[]

TagSnippet

The snippets used for tracking conversions.

phone_call_duration_seconds

Int64Value

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.

app_id

StringValue

App ID for an app conversion action.

AttributionModelSettings

Settings related to this conversion action's attribution model.

Fields
attribution_model

AttributionModel

The attribution model type of this conversion action.

data_driven_model_status

DataDrivenModelStatus

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

TagSnippet

The site tag and event snippet pair for a TrackingCodeType.

Fields
type

TrackingCodeType

The type of the generated tag snippets for tracking conversions.

page_format

TrackingCodePageFormat

The format of the web page where the tracking tag and snippet will be installed, e.g. HTML.

global_site_tag

StringValue

The site tag that adds visitors to your basic remarketing lists and sets new cookies on your domain.

event_snippet

StringValue

The event snippet that works with the site tag to track actions that should be counted as conversions.

ValueSettings

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

Fields
default_value

DoubleValue

The value to use when conversion events for this conversion action are sent with an invalid, disallowed or missing value, or when this conversion action is configured to always use the default value.

default_currency_code

StringValue

The currency code to use when conversion events for this conversion action are sent with an invalid or missing currency code, or when this conversion action is configured to always use the default value.

always_use_default_value

BoolValue

Controls whether the default value and default currency code are used in place of the value and currency code specified in conversion events for this conversion action.

Customer

A customer.

Fields
resource_name

string

The resource name of the customer. Customer resource names have the form:

customers/{customer_id}

id

Int64Value

The ID of the customer.

descriptive_name

StringValue

Optional, non-unique descriptive name of the customer.

currency_code

StringValue

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

time_zone

StringValue

The local timezone ID of the customer.

tracking_url_template

StringValue

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

auto_tagging_enabled

BoolValue

Whether auto-tagging is enabled for the customer.

has_partners_badge

BoolValue

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

GeoTargetConstant

A geo target constant.

Fields
resource_name

string

The resource name of the geo target constant. Geo target constant resource names have the form:

geoTargetConstants/{geo_target_constant_id}

id

Int64Value

The ID of the geo target constant.

name

StringValue

Geo target constant English name.

country_code

StringValue

The ISO-3166-1 alpha-2 country code that is associated with the target.

target_type

StringValue

Geo target constant target type.

GoogleAdsField

A field or resource (artifact) used by GoogleAdsService.

Fields
resource_name

string

The resource name of the artifact. Artifact resource names have the form:

googleAdsFields/{name}

name

StringValue

The name of the artifact.

category

GoogleAdsFieldCategory

The category of the artifact.

selectable

BoolValue

Whether the artifact can be used in a SELECT clause in search queries.

filterable

BoolValue

Whether the artifact can be used in a WHERE clause in search queries.

sortable

BoolValue

Whether the artifact can be used in a ORDER BY clause in search queries.

selectable_with[]

StringValue

The names of all resources, segments, and metrics that are selectable with the described artifact.

attribute_resources[]

StringValue

The names of all resources that are selectable with the described artifact. Fields from these resources do not segment metrics when included in search queries.

This field is only set for artifacts whose category is RESOURCE.

metrics[]

StringValue

The names of all metrics that are selectable with the described artifact.

This field is only set for artifacts whose category is either RESOURCE or SEGMENT.

segments[]

StringValue

The names of all artifacts, whether a segment or another resource, that segment metrics when included in search queries.

This field is only set for artifacts of category RESOURCE, SEGMENT or METRIC.

enum_values[]

StringValue

Values the artifact can assume if it is a field of type ENUM.

This field is only set for artifacts of category SEGMENT or ATTRIBUTE.

data_type

GoogleAdsFieldDataType

This field determines the operators that can be used with the artifact in WHERE clauses.

type_url

StringValue

The URL of proto describing the artifact's data type.

is_repeated

BoolValue

Whether the field artifact is repeated.

KeywordView

A keyword view.

Fields
resource_name

string

The resource name of the keyword view. Keyword view resource names have the form:

customers/{customer_id}/keywordViews/{ad_group_id}_{criterion_id}

Recommendation

A recommendation.

Fields
resource_name

string

The resource name of the recommendation.

customers/{customer_id}/recommendations/{recommendation_id}

type

RecommendationType

The type of recommendation.

impact

RecommendationImpact

The impact on account performance as a result of applying the recommendation.

campaign_budget

StringValue

The budget targeted by this recommendation. This will be set only when the recommendation affects a single campaign budget.

This field must not be used in WHERE clauses.

This field will be set for the following recommendation types: CAMPAIGN_BUDGET

campaign

StringValue

The campaign targeted by this recommendation. This will be set only when the recommendation affects a single campaign.

This field must not be used in WHERE clauses.

This field will be set for the following recommendation types: ENHANCED_CPC_OPT_IN, KEYWORD, MAXIMIZE_CLICKS_OPT_IN, MAXIMIZE_CONVERSIONS_OPT_IN, OPTIMIZE_AD_ROTATION, SEARCH_PARTNERS_OPT_IN, TARGET_CPA_OPT_IN, TEXT_AD

ad_group

StringValue

The ad group targeted by this recommendation. This will be set only when the recommendation affects a single ad group.

This field must not be used in WHERE clauses.

This field will be set for the following recommendation types: KEYWORD, OPTIMIZE_AD_ROTATION, TEXT_AD

dismissed

BoolValue

Whether the recommendation is dismissed or not.

Union field recommendation. The details of recommendation. recommendation can be only one of the following:
campaign_budget_recommendation

CampaignBudgetRecommendation

The campaign budget recommendation.

keyword_recommendation

KeywordRecommendation

The keyword recommendation.

text_ad_recommendation

TextAdRecommendation

Add expanded text ad recommendation.

target_cpa_opt_in_recommendation

TargetCpaOptInRecommendation

The TargetCPA opt-in recommendation.

maximize_conversions_opt_in_recommendation

MaximizeConversionsOptInRecommendation

The MaximizeConversions Opt-In recommendation.

enhanced_cpc_opt_in_recommendation

EnhancedCpcOptInRecommendation

The Enhanced Cost-Per-Click Opt-In recommendation.

search_partners_opt_in_recommendation

SearchPartnersOptInRecommendation

The Search Partners Opt-In recommendation.

maximize_clicks_opt_in_recommendation

MaximizeClicksOptInRecommendation

The MaximizeClicks Opt-In recommendation.

optimize_ad_rotation_recommendation

OptimizeAdRotationRecommendation

The Optimize Ad Rotation recommendation.

CampaignBudgetRecommendation

The budget recommendation for budget constrained campaigns.

Fields
current_budget_amount_micros

Int64Value

The current budget amount in micros.

recommended_budget_amount_micros

Int64Value

The recommended budget amount in micros.

budget_options[]

CampaignBudgetRecommendationOption

The budget amounts and associated impact estimates for some values of possible budget amounts.

CampaignBudgetRecommendationOption

The impact estimates for a given budget amount.

Fields
budget_amount_micros

Int64Value

The budget amount for this option.

impact

RecommendationImpact

The impact estimate if budget is changed to amount specified in this option.

EnhancedCpcOptInRecommendation

The Enhanced Cost-Per-Click Opt-In recommendation.

KeywordRecommendation

The keyword recommendation.

Fields
keyword

KeywordInfo

The recommended keyword.

recommended_cpc_bid_micros

Int64Value

The recommended CPC (cost-per-click) bid.

MaximizeClicksOptInRecommendation

The Maximize Clicks opt-in recommendation.

Fields
recommended_budget_amount_micros

Int64Value

The recommended new budget amount. Only set if the current budget is too high.

MaximizeConversionsOptInRecommendation

The Maximize Conversions Opt-In recommendation.

Fields
recommended_budget_amount_micros

Int64Value

The recommended new budget amount.

OptimizeAdRotationRecommendation

The Optimize Ad Rotation recommendation.

RecommendationImpact

The impact of making the change as described in the recommendation. Some types of recommendations may not have impact information.

Fields
base_metrics

RecommendationMetrics

Base metrics at the time the recommendation was generated.

potential_metrics

RecommendationMetrics

Estimated metrics if the recommendation is applied.

RecommendationMetrics

Weekly account performance metrics. For some recommendation types, these are averaged over the past 90-day period and hence can be fractional.

Fields
impressions

DoubleValue

Number of ad impressions.

clicks

DoubleValue

Number of ad clicks.

cost_micros

Int64Value

Cost (in micros) for advertising, in the local currency for the account.

conversions

DoubleValue

Number of conversions.

video_views

DoubleValue

Number of video views for a video ad campaign.

SearchPartnersOptInRecommendation

The Search Partners Opt-In recommendation.

TargetCpaOptInRecommendation

The Target CPA opt-in recommendation.

Fields
options[]

TargetCpaOptInRecommendationOption

The available goals and corresponding options for Target CPA strategy.

recommended_target_cpa_micros

Int64Value

The recommended average CPA target. See required budget amount and impact of using this recommendation in options list.

TargetCpaOptInRecommendationOption

The Target CPA opt-in option with impact estimate.

Fields
goal

TargetCpaOptInRecommendationGoal

The goal achieved by this option.

target_cpa_micros

Int64Value

Average CPA target.

required_campaign_budget_amount_micros

Int64Value

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.

impact

RecommendationImpact

The impact estimate if this option is selected.

TextAdRecommendation

The text ad recommendation.

Fields
ad

Ad

Recommended ad.

creation_date

StringValue

Creation date of the recommended ad. YYYY-MM-DD format, e.g., 2018-04-17.

auto_apply_date

StringValue

Date, if present, is the earliest when the recommendation will be auto applied. YYYY-MM-DD format, e.g., 2018-04-17.

SharedCriterion

A criterion belonging to a shared set.

Fields
resource_name

string

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

StringValue

The shared set to which the shared criterion belongs.

criterion_id

Int64Value

The ID of the criterion.

This field is ignored for mutates.

type

CriterionType

The type of the criterion.

keyword

KeywordInfo

Keyword.

SharedSet

SharedSets are used for sharing criterion exclusions across multiple campaigns.

Fields
resource_name

string

The resource name of the shared set. Shared set resource names have the form:

customers/{customer_id}/sharedSets/{shared_set_id}

id

Int64Value

The ID of this shared set. Read only.

type

SharedSetType

The type of this shared set: each shared set holds only a single kind of entity. Required. Immutable.

name

StringValue

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.

status

SharedSetStatus

The status of this shared set. Read only.

member_count

Int64Value

The number of shared criteria within this shared set. Read only.

reference_count

Int64Value

The number of campaigns associated with this shared set. Read only.

Video

A video.

Fields
resource_name

string

The resource name of the video. Video resource names have the form:

customers/{customer_id}/videos/{video_id}

id

StringValue

The ID of the video.

channel_id

StringValue

The owner channel id of the video.

duration_millis

Int64Value

The duration of the video in milliseconds.

title

StringValue

The title of the video.

Send feedback about...

Google Ads API Beta
Google Ads API Beta
Need help? Visit our support page.