Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

REST Resource: customers.recommendations

Resource: Recommendation

A recommendation.

JSON representation
{
  "resourceName": string,
  "type": enum (RecommendationType),
  "impact": {
    object (RecommendationImpact)
  },
  "campaignBudget": string,
  "campaign": string,
  "adGroup": string,
  "dismissed": boolean,

  // Union field recommendation can be only one of the following:
  "campaignBudgetRecommendation": {
    object (CampaignBudgetRecommendation)
  },
  "forecastingCampaignBudgetRecommendation": {
    object (CampaignBudgetRecommendation)
  },
  "keywordRecommendation": {
    object (KeywordRecommendation)
  },
  "textAdRecommendation": {
    object (TextAdRecommendation)
  },
  "targetCpaOptInRecommendation": {
    object (TargetCpaOptInRecommendation)
  },
  "maximizeConversionsOptInRecommendation": {
    object (MaximizeConversionsOptInRecommendation)
  },
  "enhancedCpcOptInRecommendation": {
    object (EnhancedCpcOptInRecommendation)
  },
  "searchPartnersOptInRecommendation": {
    object (SearchPartnersOptInRecommendation)
  },
  "maximizeClicksOptInRecommendation": {
    object (MaximizeClicksOptInRecommendation)
  },
  "optimizeAdRotationRecommendation": {
    object (OptimizeAdRotationRecommendation)
  },
  "calloutExtensionRecommendation": {
    object (CalloutExtensionRecommendation)
  },
  "sitelinkExtensionRecommendation": {
    object (SitelinkExtensionRecommendation)
  },
  "callExtensionRecommendation": {
    object (CallExtensionRecommendation)
  },
  "keywordMatchTypeRecommendation": {
    object (KeywordMatchTypeRecommendation)
  },
  "moveUnusedBudgetRecommendation": {
    object (MoveUnusedBudgetRecommendation)
  },
  "targetRoasOptInRecommendation": {
    object (TargetRoasOptInRecommendation)
  },
  "responsiveSearchAdRecommendation": {
    object (ResponsiveSearchAdRecommendation)
  },
  "marginalRoiCampaignBudgetRecommendation": {
    object (CampaignBudgetRecommendation)
  }
  // End of list of possible types for union field recommendation.
}
Fields
resourceName

string

Immutable. The resource name of the recommendation.

customers/{customerId}/recommendations/{recommendation_id}

type

enum (RecommendationType)

Output only. The type of recommendation.

impact

object (RecommendationImpact)

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

campaignBudget

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, MARGINAL_ROI_CAMPAIGN_BUDGET, MOVE_UNUSED_BUDGET

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, RESPONSIVE_SEARCH_AD, SEARCH_PARTNERS_OPT_IN, SITELINK_EXTENSION, TARGET_CPA_OPT_IN, TARGET_ROAS_OPT_IN, TEXT_AD

adGroup

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, RESPONSIVE_SEARCH_AD, TEXT_AD

dismissed

boolean

Output only. Whether the recommendation is dismissed or not.

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

object (CampaignBudgetRecommendation)

Output only. The campaign budget recommendation.

forecastingCampaignBudgetRecommendation

object (CampaignBudgetRecommendation)

Output only. The forecasting campaign budget recommendation.

keywordRecommendation

object (KeywordRecommendation)

Output only. The keyword recommendation.

textAdRecommendation

object (TextAdRecommendation)

Output only. Add expanded text ad recommendation.

targetCpaOptInRecommendation

object (TargetCpaOptInRecommendation)

Output only. The TargetCPA opt-in recommendation.

maximizeConversionsOptInRecommendation

object (MaximizeConversionsOptInRecommendation)

Output only. The MaximizeConversions Opt-In recommendation.

enhancedCpcOptInRecommendation

object (EnhancedCpcOptInRecommendation)

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

searchPartnersOptInRecommendation

object (SearchPartnersOptInRecommendation)

Output only. The googleAds.search Partners Opt-In recommendation.

maximizeClicksOptInRecommendation

object (MaximizeClicksOptInRecommendation)

Output only. The MaximizeClicks Opt-In recommendation.

optimizeAdRotationRecommendation

object (OptimizeAdRotationRecommendation)

Output only. The Optimize Ad Rotation recommendation.

calloutExtensionRecommendation

object (CalloutExtensionRecommendation)

Output only. The Callout extension recommendation.

callExtensionRecommendation

object (CallExtensionRecommendation)

Output only. The Call extension recommendation.

keywordMatchTypeRecommendation

object (KeywordMatchTypeRecommendation)

Output only. The keyword match type recommendation.

moveUnusedBudgetRecommendation

object (MoveUnusedBudgetRecommendation)

Output only. The move unused budget recommendation.

targetRoasOptInRecommendation

object (TargetRoasOptInRecommendation)

Output only. The Target ROAS opt-in recommendation.

responsiveSearchAdRecommendation

object (ResponsiveSearchAdRecommendation)

Output only. The add responsive search ad recommendation.

marginalRoiCampaignBudgetRecommendation

object (CampaignBudgetRecommendation)

Output only. The marginal ROI campaign budget recommendation.

RecommendationType

Types of recommendations.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
CAMPAIGN_BUDGET Budget recommendation for campaigns that are currently budget-constrained (as opposed to the FORECASTING_CAMPAIGN_BUDGET recommendation, which applies to campaigns that are expected to become budget-constrained in the future).
KEYWORD Keyword recommendation.
TEXT_AD Recommendation to add a new text ad.
TARGET_CPA_OPT_IN Recommendation to update a campaign to use a Target CPA bidding strategy.
MAXIMIZE_CONVERSIONS_OPT_IN Recommendation to update a campaign to use the Maximize Conversions bidding strategy.
ENHANCED_CPC_OPT_IN Recommendation to enable Enhanced Cost Per Click for a campaign.
SEARCH_PARTNERS_OPT_IN Recommendation to start showing your campaign's ads on Google googleAds.search Partners Websites.
MAXIMIZE_CLICKS_OPT_IN Recommendation to update a campaign to use a Maximize Clicks bidding strategy.
OPTIMIZE_AD_ROTATION Recommendation to start using the "Optimize" ad rotation setting for the given ad group.
CALLOUT_EXTENSION Recommendation to add callout extensions to a campaign.
CALL_EXTENSION Recommendation to add call extensions to a campaign.
KEYWORD_MATCH_TYPE Recommendation to change an existing keyword from one match type to a broader match type.
MOVE_UNUSED_BUDGET Recommendation to move unused budget from one budget to a constrained budget.
FORECASTING_CAMPAIGN_BUDGET Budget recommendation for campaigns that are expected to become budget-constrained in the future (as opposed to the CAMPAIGN_BUDGET recommendation, which applies to campaigns that are currently budget-constrained).
TARGET_ROAS_OPT_IN Recommendation to update a campaign to use a Target ROAS bidding strategy.
RESPONSIVE_SEARCH_AD Recommendation to add a new responsive search ad.
MARGINAL_ROI_CAMPAIGN_BUDGET Budget recommendation for campaigns whose ROI is predicted to increase with a budget adjustment.

RecommendationImpact

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

JSON representation
{
  "baseMetrics": {
    object (RecommendationMetrics)
  },
  "potentialMetrics": {
    object (RecommendationMetrics)
  }
}
Fields
baseMetrics

object (RecommendationMetrics)

Output only. Base metrics at the time the recommendation was generated.

potentialMetrics

object (RecommendationMetrics)

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

JSON representation
{
  "impressions": number,
  "clicks": number,
  "costMicros": string,
  "conversions": number,
  "videoViews": number
}
Fields
impressions

number

Output only. Number of ad impressions.

clicks

number

Output only. Number of ad clicks.

costMicros

string (int64 format)

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

conversions

number

Output only. Number of conversions.

videoViews

number

Output only. Number of video views for a video ad campaign.

CampaignBudgetRecommendation

The budget recommendation for budget constrained campaigns.

JSON representation
{
  "budgetOptions": [
    {
      object (CampaignBudgetRecommendationOption)
    }
  ],
  "currentBudgetAmountMicros": string,
  "recommendedBudgetAmountMicros": string
}
Fields
budgetOptions[]

object (CampaignBudgetRecommendationOption)

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

currentBudgetAmountMicros

string (int64 format)

Output only. The current budget amount in micros.

recommendedBudgetAmountMicros

string (int64 format)

Output only. The recommended budget amount in micros.

CampaignBudgetRecommendationOption

The impact estimates for a given budget amount.

JSON representation
{
  "impact": {
    object (RecommendationImpact)
  },
  "budgetAmountMicros": string
}
Fields
impact

object (RecommendationImpact)

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

budgetAmountMicros

string (int64 format)

Output only. The budget amount for this option.

KeywordRecommendation

The keyword recommendation.

JSON representation
{
  "keyword": {
    object (KeywordInfo)
  },
  "recommendedCpcBidMicros": string
}
Fields
keyword

object (KeywordInfo)

Output only. The recommended keyword.

recommendedCpcBidMicros

string (int64 format)

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

TextAdRecommendation

The text ad recommendation.

JSON representation
{
  "ad": {
    object (Ad)
  },
  "creationDate": string,
  "autoApplyDate": string
}
Fields
ad

object (Ad)

Output only. Recommended ad.

creationDate

string

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

autoApplyDate

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.

TargetCpaOptInRecommendation

The Target CPA opt-in recommendation.

JSON representation
{
  "options": [
    {
      object (TargetCpaOptInRecommendationOption)
    }
  ],
  "recommendedTargetCpaMicros": string
}
Fields
options[]

object (TargetCpaOptInRecommendationOption)

Output only. The available goals and corresponding options for Target CPA strategy.

recommendedTargetCpaMicros

string (int64 format)

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

JSON representation
{
  "goal": enum (TargetCpaOptInRecommendationGoal),
  "impact": {
    object (RecommendationImpact)
  },
  "targetCpaMicros": string,
  "requiredCampaignBudgetAmountMicros": string
}
Fields
goal

enum (TargetCpaOptInRecommendationGoal)

Output only. The goal achieved by this option.

impact

object (RecommendationImpact)

Output only. The impact estimate if this option is selected.

targetCpaMicros

string (int64 format)

Output only. Average CPA target.

requiredCampaignBudgetAmountMicros

string (int64 format)

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.

TargetCpaOptInRecommendationGoal

Goal of TargetCpaOptIn recommendation.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
SAME_COST Recommendation to set Target CPA to maintain the same cost.
SAME_CONVERSIONS Recommendation to set Target CPA to maintain the same conversions.
SAME_CPA Recommendation to set Target CPA to maintain the same CPA.
CLOSEST_CPA 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).

MaximizeConversionsOptInRecommendation

The Maximize Conversions Opt-In recommendation.

JSON representation
{
  "recommendedBudgetAmountMicros": string
}
Fields
recommendedBudgetAmountMicros

string (int64 format)

Output only. The recommended new budget amount.

EnhancedCpcOptInRecommendation

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

SearchPartnersOptInRecommendation

The googleAds.search Partners Opt-In recommendation.

MaximizeClicksOptInRecommendation

The Maximize Clicks opt-in recommendation.

JSON representation
{
  "recommendedBudgetAmountMicros": string
}
Fields
recommendedBudgetAmountMicros

string (int64 format)

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

OptimizeAdRotationRecommendation

The Optimize Ad Rotation recommendation.

CalloutExtensionRecommendation

The Callout extension recommendation.

JSON representation
{
  "recommendedExtensions": [
    {
      object (CalloutFeedItem)
    }
  ]
}
Fields
recommendedExtensions[]

object (CalloutFeedItem)

Output only. Callout extensions recommended to be added.

SitelinkExtensionRecommendation

The Sitelink extension recommendation.

JSON representation
{
  "recommendedExtensions": [
    {
      object (SitelinkFeedItem)
    }
  ]
}
Fields
recommendedExtensions[]

object (SitelinkFeedItem)

Output only. Sitelink extensions recommended to be added.

CallExtensionRecommendation

The Call extension recommendation.

JSON representation
{
  "recommendedExtensions": [
    {
      object (CallFeedItem)
    }
  ]
}
Fields
recommendedExtensions[]

object (CallFeedItem)

Output only. Call extensions recommended to be added.

KeywordMatchTypeRecommendation

The keyword match type recommendation.

JSON representation
{
  "keyword": {
    object (KeywordInfo)
  },
  "recommendedMatchType": enum (KeywordMatchType)
}
Fields
keyword

object (KeywordInfo)

Output only. The existing keyword where the match type should be more broad.

recommendedMatchType

enum (KeywordMatchType)

Output only. The recommended new match type.

MoveUnusedBudgetRecommendation

The move unused budget recommendation.

JSON representation
{
  "budgetRecommendation": {
    object (CampaignBudgetRecommendation)
  },
  "excessCampaignBudget": string
}
Fields
budgetRecommendation

object (CampaignBudgetRecommendation)

Output only. The recommendation for the constrained budget to increase.

excessCampaignBudget

string

Output only. The excess budget's resourceName.

TargetRoasOptInRecommendation

The Target ROAS opt-in recommendation.

JSON representation
{
  "recommendedTargetRoas": number,
  "requiredCampaignBudgetAmountMicros": string
}
Fields
recommendedTargetRoas

number

Output only. The recommended target ROAS (revenue per unit of spend). The value is between 0.01 and 1000.0, inclusive.

requiredCampaignBudgetAmountMicros

string (int64 format)

Output only. The minimum campaign budget, in local currency for the account, required to achieve the target ROAS. Amount is specified in micros, where one million is equivalent to one currency unit.

ResponsiveSearchAdRecommendation

The add responsive search ad recommendation.

JSON representation
{
  "ad": {
    object (Ad)
  }
}
Fields
ad

object (Ad)

Output only. Recommended ad.

Methods

apply

Applies given recommendations with corresponding apply parameters.

dismiss

Dismisses given recommendations.

get

Returns the requested recommendation in full detail.