Package google.ads.googleads.v0.common

Index

AdScheduleInfo

Represents an AdSchedule criterion.

AdSchedule is specified as the day of the week and a time interval within which ads will be shown.

No more than six AdSchedules can be added for the same day.

Fields
start_minute

MinuteOfHour

Minutes after the start hour at which this schedule starts.

This field is required for CREATE operations and is prohibited on UPDATE operations.

end_minute

MinuteOfHour

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.

start_hour

Int32Value

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.

end_hour

Int32Value

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.

day_of_week

DayOfWeek

Day of the week the schedule applies to.

This field is required for CREATE operations and is prohibited on UPDATE operations.

CallOnlyAdInfo

A call-only ad.

Fields
country_code

StringValue

The country code in the ad.

phone_number

StringValue

The phone number in the ad.

business_name

StringValue

The business name in the ad.

description1

StringValue

The first line of the ad's description.

description2

StringValue

The second line of the ad's description.

call_tracked

BoolValue

Whether to enable call tracking for the creative. Enabling call tracking also enables call conversions.

disable_call_conversion

BoolValue

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.

phone_number_verification_url

StringValue

The URL to be used for phone number verification.

CustomParameter

A mapping that can be used by custom parameter tags in a tracking_url_template, final_urls, or mobile_final_urls.

Fields
key

StringValue

The key matching the parameter tag name.

value

StringValue

The value to be substituted.

DeviceInfo

A device criterion.

Fields
type

Device

Type of the device.

DynamicSearchAdInfo

A dynamic search ad.

Fields
description1

StringValue

The first line of the ad's description.

description2

StringValue

The second line of the ad's description.

EnhancedCpc

An automated 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.

ExpandedDynamicSearchAdInfo

An expanded dynamic search ad.

Fields
description

StringValue

The description of the ad.

ExpandedTextAdInfo

An expanded text ad.

Fields
headline_part1

StringValue

The first part of the ad's headline.

headline_part2

StringValue

The second part of the ad's headline.

description

StringValue

The description of the ad.

path1

StringValue

The text that can appear alongside the ad's displayed URL.

path2

StringValue

Additional text that can appear alongside the ad's displayed URL.

HotelAdInfo

A hotel ad.

HotelAdvanceBookingWindowInfo

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

Fields
min_days

Int64Value

Low end of the number of days prior to the stay.

max_days

Int64Value

High end of the number of days prior to the stay.

HotelCheckInDayInfo

Criterion for day of the week the booking is for.

Fields
day_of_week

DayOfWeek

The day of the week.

HotelCityInfo

City the hotel is located in.

Fields
city_criterion

StringValue

The Geo Target Constant resource name.

HotelClassInfo

Class of the hotel as a number of stars 1 to 5.

Fields
value

Int64Value

Long value of the hotel class.

HotelCountryRegionInfo

Country or Region the hotel is located in.

Fields
country_region_criterion

StringValue

The Geo Target Constant resource name.

HotelDateSelectionTypeInfo

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

Fields
type

HotelDateSelectionType

Type of the hotel date selection

HotelIdInfo

Advertiser-specific hotel ID.

Fields
value

StringValue

String value of the hotel ID.

HotelLengthOfStayInfo

Criterion for length of hotel stay in nights.

Fields
min_nights

Int64Value

Low end of the number of nights in the stay.

max_nights

Int64Value

High end of the number of nights in the stay.

HotelStateInfo

State the hotel is located in.

Fields
state_criterion

StringValue

The Geo Target Constant resource name.

InteractionTypeInfo

Criterion for Interaction Type.

Fields
type

InteractionType

The interaction type.

KeywordInfo

A keyword criterion.

Fields
text

StringValue

The text of the keyword (at most 80 characters and 10 words).

match_type

KeywordMatchType

The match type of the keyword.

ListingBrandInfo

Brand of the listing.

Fields
value

StringValue

String value of the listing brand.

ListingCustomAttributeInfo

Listing custom attribute.

Fields
value

StringValue

String value of the listing custom attribute.

index

ListingCustomAttributeIndex

Indicates the index of the custom attribute.

ListingDimensionInfo

Listing dimensions for listing group criterion.

Fields
Union field dimension. Dimension of one of the types below is always present. dimension can be only one of the following:
listing_brand

ListingBrandInfo

Brand of the listing.

hotel_id

HotelIdInfo

Advertiser-specific hotel ID.

hotel_class

HotelClassInfo

Class of the hotel as a number of stars 1 to 5.

hotel_country_region

HotelCountryRegionInfo

Country or Region the hotel is located in.

hotel_state

HotelStateInfo

State the hotel is located in.

hotel_city

HotelCityInfo

City the hotel is located in.

listing_custom_attribute

ListingCustomAttributeInfo

Listing custom attribute.

product_condition

ProductConditionInfo

Condition of a product offer.

product_type

ProductTypeInfo

Type of a product offer.

ListingGroupInfo

A listing group criterion.

Fields
type

ListingGroupType

Type of the listing group.

case_value

ListingDimensionInfo

Dimension value with which this listing group is refining its parent. Undefined for the root group.

parent_ad_group_criterion

StringValue

Resource name of ad group criterion which is the parent listing group subdivision. Null for the root group.

LocationInfo

A location criterion.

Fields
geo_target_constant

StringValue

The geo target constant resource name.

ManualCpc

Manual click-based bidding where user pays per click.

Fields
enhanced_cpc_enabled

BoolValue

Whether bids are to be enhanced based on conversion optimizer data.

ManualCpm

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

MaximizeConversionValue

An automated bidding strategy which tries to maximize conversion value given a daily budget.

Fields
target_roas

DoubleValue

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.

MaximizeConversions

An automated bidding strategy that sets bids to help get the most conversions for your campaign while spending your budget.

Metrics

Metrics data.

Fields
all_conversions_from_interactions_rate

DoubleValue

All conversions from interactions (as oppose to view through conversions) divided by the number of ad interactions.

all_conversions_value

DoubleValue

The total value of all conversions.

all_conversions

DoubleValue

The total number of conversions. This includes "Conversions" plus conversions that have their "Include in Conversions" setting unchecked.

all_conversions_value_per_cost

DoubleValue

The value of all conversions divided by the total cost of ad interactions (such as clicks for text ads or views for video ads).

all_conversions_from_interactions_value_per_interaction

DoubleValue

The value of all conversions from interactions divided by the total number of interactions.

average_cost

DoubleValue

The average amount you pay per interaction. This amount is the total cost of your ads divided by the total number of interactions.

average_cpc

DoubleValue

The total cost of all clicks divided by the total number of clicks received.

average_cpm

DoubleValue

Average cost-per-thousand impressions (CPM).

average_position

DoubleValue

Your ad's position relative to those of other advertisers.

bounce_rate

DoubleValue

Percentage of clicks where the user only visited a single page on your site. Imported from Google Analytics.

clicks

Int64Value

The number of clicks.

content_budget_lost_impression_share

DoubleValue

The estimated percent of times that your ad was eligible to show on the Display Network but didn't because your budget was too low. Note: Content budget lost impression share is reported in the range of 0 to 0.9. Any value above 0.9 is reported as 0.9001.

content_impression_share

DoubleValue

The impressions you've received on the Display Network divided by the estimated number of impressions you were eligible to receive. Note: Content impression share is reported in the range of 0.1 to 1. Any value below 0.1 is reported as 0.0999.

content_rank_lost_impression_share

DoubleValue

The estimated percentage of impressions on the Display Network that your ads didn't receive due to poor Ad Rank. Note: Content rank lost impression share is reported in the range of 0 to 0.9. Any value above 0.9 is reported as 0.9001.

conversions_from_interactions_rate

DoubleValue

Conversions from interactions divided by the number of ad interactions (such as clicks for text ads or views for video ads).

conversions_value

DoubleValue

The total value of conversions.

conversions_value_per_cost

DoubleValue

The value of conversions divided by the cost of ad interactions.

conversions_from_interactions_value_per_interaction

DoubleValue

The value of conversions from interactions divided by the number of ad interactions.

conversions

DoubleValue

The number of conversions. This only includes conversion actions which have "Include in Conversions" checked.

cost_micros

Int64Value

The sum of your cost-per-click (CPC) and cost-per-thousand impressions (CPM) costs during this period.

cost_per_all_conversions

DoubleValue

The cost of ad interactions divided by all conversions.

cost_per_conversion

DoubleValue

The cost of ad interactions divided by conversions.

cross_device_conversions

DoubleValue

Conversions from when a customer clicks on a Google Ads ad on one device, then converts on a different device or browser. Cross-device conversions are already included in all_conversions.

ctr

DoubleValue

The number of clicks your ad receives (Clicks) divided by the number of times your ad is shown (Impressions).

engagement_rate

DoubleValue

How often people engage with your ad after it's shown to them. This is the number of ad expansions divided by the number of times your ad is shown.

engagements

Int64Value

The number of engagements. An engagement occurs when a viewer expands your Lightbox ad. Also, in the future, other ad types may support engagement metrics.

impressions

Int64Value

Count of how often your ad has appeared on a search results page or website on the Google Network.

interaction_rate

DoubleValue

How often people interact with your ad after it is shown to them. This is the number of interactions divided by the number of times your ad is shown.

interactions

Int64Value

The number of interactions. An interaction is the main user action associated with an ad format-clicks for text and shopping ads, views for video ads, and so on.

invalid_click_rate

DoubleValue

The percentage of clicks filtered out of your total number of clicks (filtered + non-filtered clicks) during the reporting period.

invalid_clicks

Int64Value

Number of clicks Google considers illegitimate and doesn't charge you for.

percent_new_visitors

DoubleValue

Percentage of first-time sessions (from people who had never visited your site before). Imported from Google Analytics.

phone_calls

Int64Value

Number of offline phone calls.

phone_impressions

Int64Value

Number of offline phone impressions.

phone_through_rate

DoubleValue

Number of phone calls received (phone_calls) divided by the number of times your phone number is shown (phone_impressions).

relative_ctr

DoubleValue

Your clickthrough rate (Ctr) divided by the average clickthrough rate of all advertisers on the websites that show your ads. Measures how your ads perform on Display Network sites compared to other ads on the same sites.

search_budget_lost_impression_share

DoubleValue

The estimated percent of times that your ad was eligible to show on the Search Network but didn't because your budget was too low. Note: Search budget lost impression share is reported in the range of 0 to 0.9. Any value above 0.9 is reported as 0.9001.

search_exact_match_impression_share

DoubleValue

The impressions you've received divided by the estimated number of impressions you were eligible to receive on the Search Network for search terms that matched your keywords exactly (or were close variants of your keyword), regardless of your keyword match types. Note: Search exact match impression share is reported in the range of 0.1 to 1. Any value below 0.1 is reported as 0.0999.

search_impression_share

DoubleValue

The impressions you've received on the Search Network divided by the estimated number of impressions you were eligible to receive. Note: Search impression share is reported in the range of 0.1 to 1. Any value below 0.1 is reported as 0.0999.

search_rank_lost_impression_share

DoubleValue

The estimated percentage of impressions on the Search Network that your ads didn't receive due to poor Ad Rank. Note: Search rank lost impression share is reported in the range of 0 to 0.9. Any value above 0.9 is reported as 0.9001.

value_per_all_conversions

DoubleValue

The value of all conversions divided by the number of all conversions.

value_per_conversion

DoubleValue

The value of conversions divided by the number of conversions.

view_through_conversions

Int64Value

The total number of view-through conversions. These happen when a customer sees an image or rich media ad, then later completes a conversion on your site without interacting with (e.g., clicking on) another ad.

PageOnePromoted

An automated bidding strategy which sets CPC bids to target impressions on page one, or page one promoted slots on google.com.

Fields
strategy_goal

PageOnePromotedStrategyGoal

The strategy goal of where impressions are desired to be shown on search result pages.

cpc_bid_ceiling_micros

Int64Value

Maximum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.

bid_modifier

DoubleValue

Bid multiplier to be applied to the relevant bid estimate (depending on the strategy_goal) in determining a keyword's new CPC bid.

only_raise_cpc_bids

BoolValue

Whether the strategy should always follow bid estimate changes, or only increase. If false, always sets a keyword's new bid to the current bid estimate. If true, only updates a keyword's bid if the current bid estimate is greater than the current bid.

raise_cpc_bid_when_budget_constrained

BoolValue

Whether the strategy is allowed to raise bids when the throttling rate of the budget it is serving out of rises above a threshold.

raise_cpc_bid_when_quality_score_is_low

BoolValue

Whether the strategy is allowed to raise bids on keywords with lower-range quality scores.

PercentCpc

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

Fields
cpc_bid_ceiling_micros

Int64Value

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

BoolValue

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.

PolicyTopicConstraint

Describes the effect on serving that a policy topic entry will have.

Next Id: 5

Fields
Union field value. Specific information about the constraint. value can be only one of the following:
country_constraint_list

CountryConstraintList

Countries where the resource cannot serve.

reseller_constraint

ResellerConstraint

Reseller constraint.

certificate_missing_in_country_list

CountryConstraintList

Countries where a certificate is required for serving.

certificate_domain_mismatch_in_country_list

CountryConstraintList

Countries where the resource's domain is not covered by the certificates associated with it.

CountryConstraint

Indicates that a resource's ability to serve in a particular country is constrained.

Next Id: 2

Fields
country_criterion

StringValue

Geo target constant resource name of the country in which serving is constrained.

CountryConstraintList

A list of countries where a resource's serving is constrained.

Next Id: 3

Fields
total_targeted_countries

Int32Value

Total number of countries targeted by the resource.

countries[]

CountryConstraint

Countries in which serving is restricted.

ResellerConstraint

Indicates that a policy topic was constrained due to disapproval of the website for reseller purposes.

Next Id: 1

PolicyTopicEntry

Policy finding attached to a resource (e.g. alcohol policy associated with a site that sells alcohol).

Each PolicyTopicEntry has a topic that indicates the specific ads policy the entry is about and a type to indicate the effect that the entry will have on serving. It may optionally have one or more evidences that indicate the reason for the finding. It may also optionally have one or more constraints that provide details about how serving may be restricted.

Next tag: 5

Fields
topic

StringValue

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

PolicyTopicEntryType

Describes the negative or positive effect this policy will have on serving.

evidences[]

PolicyTopicEvidence

Additional information that explains policy finding (e.g. the brand name for a trademark finding).

constraints[]

PolicyTopicConstraint

Indicates how serving of this resource may be affected (e.g. not serving in a country).

PolicyTopicEvidence

Additional information that explains a policy finding.

Next Id: 8

Fields
Union field value. Specific evidence information depending on the evidence type. value can be only one of the following:
http_code

Int32Value

HTTP code returned when the final URL was crawled.

website_list

WebsiteList

List of websites linked with this resource.

text_list

TextList

List of evidence found in the text of a resource.

language_code

StringValue

The language the resource was detected to be written in. This is an IETF language tag such as "en-US".

destination_text_list

DestinationTextList

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

destination_mismatch

DestinationMismatch

Mismatch between the destinations of a resource's URLs.

DestinationMismatch

Evidence of mismatches between the URLs of a resource.

Next Id: 2

Fields
url_types[]

PolicyTopicEvidenceDestinationMismatchUrlType

The set of URLs that did not match each other.

DestinationTextList

A list of strings found in a destination page that caused a policy finding.

Next Id: 2

Fields
destination_texts[]

StringValue

List of text found in the resource's destination page.

TextList

A list of fragments of text that violated a policy.

Next Id: 2

Fields
texts[]

StringValue

The fragments of text from the resource that caused the policy finding.

WebsiteList

A list of websites that caused a policy finding. Used for ONE_WEBSITE_PER_AD_GROUP policy topic, for example. In case there are more than five websites, only the top five (those that appear in resources the most) will be listed here.

Next Id: 2

Fields
websites[]

StringValue

Websites that caused the policy finding.

PolicyViolationKey

Key of the violation. The key is used for referring to a violation when filing an exemption request.

Fields
policy_name

StringValue

Unique ID of the violated policy.

violating_text

StringValue

The text that violates the policy if specified. Otherwise, refers to the policy in general (e.g., when requesting to be exempt from the whole policy). If not specified for criterion exemptions, the whole policy is implied. Must be specified for ad exemptions.

ProductConditionInfo

Condition of a product offer.

Fields
condition

ProductCondition

Value of the condition.

ProductTypeInfo

Type of a product offer.

Fields
value

StringValue

Value of the type.

level

ProductTypeLevel

Level of the type.

ResponsiveDisplayAdInfo

A responsive display ad.

Fields
short_headline

StringValue

The short version of the ad's headline.

long_headline

StringValue

The long version of the ad's headline.

description

StringValue

The description of the ad.

business_name

StringValue

The business name in the ad.

ShoppingSmartAdInfo

A Smart Shopping ad.

TargetCpa

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

Fields
target_cpa_micros

Int64Value

Average CPA target. This target should be greater than or equal to minimum billable unit based on the currency for the account.

cpc_bid_ceiling_micros

Int64Value

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

Int64Value

Minimum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.

TargetOutrankShare

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

Fields
target_outrank_share_micros

Int32Value

The target fraction of auctions where the advertiser should outrank the competitor. The advertiser outranks the competitor in an auction if either the advertiser appears above the competitor in the search results, or appears in the search results when the competitor does not. Value must be between 1 and 1000000, inclusive.

competitor_domain

StringValue

Competitor's visible domain URL.

cpc_bid_ceiling_micros

Int64Value

Maximum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.

only_raise_cpc_bids

BoolValue

Whether the strategy should always follow bid estimate changes, or only increase. If false, always set a keyword's new bid to the current bid estimate. If true, only updates a keyword's bid if the current bid estimate is greater than the current bid.

raise_cpc_bid_when_quality_score_is_low

BoolValue

Whether the strategy is allowed to raise bids on keywords with lower-range quality scores.

TargetRoas

An automated bidding strategy that helps you maximize revenue while averaging a specific target return on ad spend (ROAS).

Fields
target_roas

DoubleValue

Required. The desired revenue (based on conversion data) per unit of spend. Value must be between 0.01 and 1000.0, inclusive.

cpc_bid_ceiling_micros

Int64Value

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

Int64Value

Minimum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.

TargetSpend

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

Fields
target_spend_micros

Int64Value

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.

cpc_bid_ceiling_micros

Int64Value

Maximum bid limit that can be set by the bid strategy. The limit applies to all keywords managed by the strategy.

TextAdInfo

A text ad.

Fields
headline

StringValue

The headline of the ad.

description1

StringValue

The first line of the ad's description.

description2

StringValue

The second line of the ad's description.

Value

A generic data container.

Fields
Union field value. A value. value can be only one of the following:
boolean_value

bool

A boolean.

int64_value

int64

An int64.

float_value

float

A float.

double_value

double

A double.

string_value

string

A string.

Send feedback about...

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