Method: customers.recommendations.apply

Applies given recommendations with corresponding apply parameters.

List of thrown errors: AuthenticationError AuthorizationError DatabaseError FieldError HeaderError InternalError MutateError QuotaError RecommendationError RequestError UrlFieldError

HTTP request

POST https://googleads.googleapis.com/v16/customers/{customerId}/recommendations:apply

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
customerId

string

Required. The ID of the customer with the recommendation.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "operations": [
    {
      object (ApplyRecommendationOperation)
    }
  ],
  "partialFailure": boolean
}
Fields
operations[]

object (ApplyRecommendationOperation)

Required. The list of operations to apply recommendations. If partialFailure=false all recommendations should be of the same type There is a limit of 100 operations per request.
partialFailure

boolean

If true, successful operations will be carried out and invalid operations will return errors. If false, operations will be carried out as a transaction if and only if they are all valid. Default is false.

Response body

Response message for RecommendationService.ApplyRecommendation.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "results": [
    {
      object (ApplyRecommendationResult)
    }
  ],
  "partialFailureError": {
    object (Status)
  }
}
Fields
results[]

object (ApplyRecommendationResult)

Results of operations to apply recommendations.
partialFailureError

object (Status)

Errors that pertain to operation failures in the partial failure mode. Returned only when partialFailure = true and all errors occur inside the operations. If any errors occur outside the operations (for example, auth errors) we return the RPC level error.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/adwords

For more information, see the OAuth 2.0 Overview.

ApplyRecommendationOperation

Information about the operation to apply a recommendation and any parameters to customize it.

JSON representation 
{
  "resourceName": string,

  // Union field apply_parameters can be only one of the following:
  "campaignBudget": {
    object (CampaignBudgetParameters)
  },
  "textAd": {
    object (TextAdParameters)
  },
  "keyword": {
    object (KeywordParameters)
  },
  "targetCpaOptIn": {
    object (TargetCpaOptInParameters)
  },
  "targetRoasOptIn": {
    object (TargetRoasOptInParameters)
  },
  "calloutExtension": {
    object (CalloutExtensionParameters)
  },
  "callExtension": {
    object (CallExtensionParameters)
  },
  "sitelinkExtension": {
    object (SitelinkExtensionParameters)
  },
  "moveUnusedBudget": {
    object (MoveUnusedBudgetParameters)
  },
  "responsiveSearchAd": {
    object (ResponsiveSearchAdParameters)
  },
  "useBroadMatchKeyword": {
    object (UseBroadMatchKeywordParameters)
  },
  "responsiveSearchAdAsset": {
    object (ResponsiveSearchAdAssetParameters)
  },
  "responsiveSearchAdImproveAdStrength": {
    object (ResponsiveSearchAdImproveAdStrengthParameters)
  },
  "raiseTargetCpaBidTooLow": {
    object (RaiseTargetCpaBidTooLowParameters)
  },
  "forecastingSetTargetRoas": {
    object (ForecastingSetTargetRoasParameters)
  },
  "calloutAsset": {
    object (CalloutAssetParameters)
  },
  "callAsset": {
    object (CallAssetParameters)
  },
  "sitelinkAsset": {
    object (SitelinkAssetParameters)
  },
  "raiseTargetCpa": {
    object (RaiseTargetCpaParameters)
  },
  "lowerTargetRoas": {
    object (LowerTargetRoasParameters)
  },
  "forecastingSetTargetCpa": {
    object (ForecastingSetTargetCpaParameters)
  },
  "setTargetCpa": {
    object (ForecastingSetTargetCpaParameters)
  },
  "setTargetRoas": {
    object (ForecastingSetTargetRoasParameters)
  },
  "leadFormAsset": {
    object (LeadFormAssetParameters)
  }
  // End of list of possible types for union field apply_parameters.
}
Fields
resourceName

string

The resource name of the recommendation to apply.
Union field apply_parameters. Parameters to use when applying the recommendation. apply_parameters can be only one of the following:
campaignBudget

object (CampaignBudgetParameters)

Optional parameters to use when applying a campaign budget recommendation.
textAd

object (TextAdParameters)

Optional parameters to use when applying a text ad recommendation.
keyword

object (KeywordParameters)

Optional parameters to use when applying keyword recommendation.
targetCpaOptIn

object (TargetCpaOptInParameters)

Optional parameters to use when applying target CPA opt-in recommendation.
targetRoasOptIn

object (TargetRoasOptInParameters)

Optional parameters to use when applying target ROAS opt-in recommendation.
calloutExtension

object (CalloutExtensionParameters)

Parameters to use when applying callout extension recommendation.
callExtension

object (CallExtensionParameters)

Parameters to use when applying call extension recommendation.
moveUnusedBudget

object (MoveUnusedBudgetParameters)

Parameters to use when applying move unused budget recommendation.
responsiveSearchAd

object (ResponsiveSearchAdParameters)

Parameters to use when applying a responsive search ad recommendation.
useBroadMatchKeyword

object (UseBroadMatchKeywordParameters)

Parameters to use when applying a use broad match keyword recommendation.
responsiveSearchAdAsset

object (ResponsiveSearchAdAssetParameters)

Parameters to use when applying a responsive search ad asset recommendation.
responsiveSearchAdImproveAdStrength

object (ResponsiveSearchAdImproveAdStrengthParameters)

Parameters to use when applying a responsive search ad improve ad strength recommendation.
raiseTargetCpaBidTooLow

object (RaiseTargetCpaBidTooLowParameters)

Parameters to use when applying a raise target CPA bid too low recommendation. The apply is asynchronous and can take minutes depending on the number of ad groups there is in the related campaign.
forecastingSetTargetRoas

object (ForecastingSetTargetRoasParameters)

Parameters to use when applying a forecasting set target ROAS recommendation.
calloutAsset

object (CalloutAssetParameters)

Parameters to use when applying callout asset recommendation.
callAsset

object (CallAssetParameters)

Parameters to use when applying call asset recommendation.
raiseTargetCpa

object (RaiseTargetCpaParameters)

Parameters to use when applying raise Target CPA recommendation.
lowerTargetRoas

object (LowerTargetRoasParameters)

Parameters to use when applying lower Target ROAS recommendation.
forecastingSetTargetCpa

object (ForecastingSetTargetCpaParameters)

Parameters to use when applying forecasting set target CPA recommendation.
setTargetCpa

object (ForecastingSetTargetCpaParameters)

Parameters to use when applying set target CPA recommendation.
setTargetRoas

object (ForecastingSetTargetRoasParameters)

Parameters to use when applying set target ROAS recommendation.
leadFormAsset

object (LeadFormAssetParameters)

Parameters to use when applying lead form asset recommendation.

CampaignBudgetParameters

Parameters to use when applying a campaign budget recommendation.

JSON representation 
{
  "newBudgetAmountMicros": string
}
Fields
newBudgetAmountMicros

string (int64 format)

New budget amount to set for target budget resource. This is a required field.

TextAdParameters

Parameters to use when applying a text ad recommendation.

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

object (Ad)

New ad to add to recommended ad group. All necessary fields need to be set in this message. This is a required field.

KeywordParameters

Parameters to use when applying keyword recommendation.

JSON representation 
{
  "matchType": enum (KeywordMatchType),
  "adGroup": string,
  "cpcBidMicros": string
}
Fields
matchType

enum (KeywordMatchType)

The match type of the keyword. This is a required field.
adGroup

string

The ad group resource to add keyword to. This is a required field.
cpcBidMicros

string (int64 format)

Optional, CPC bid to set for the keyword. If not set, keyword will use bid based on bidding strategy used by target ad group.

TargetCpaOptInParameters

Parameters to use when applying Target CPA recommendation.

JSON representation 
{
  "targetCpaMicros": string,
  "newCampaignBudgetAmountMicros": string
}
Fields
targetCpaMicros

string (int64 format)

Average CPA to use for Target CPA bidding strategy. This is a required field.
newCampaignBudgetAmountMicros

string (int64 format)

Optional, budget amount to set for the campaign.

TargetRoasOptInParameters

Parameters to use when applying a Target ROAS opt-in recommendation.

JSON representation 
{
  "targetRoas": number,
  "newCampaignBudgetAmountMicros": string
}
Fields
targetRoas

number

Average ROAS (revenue per unit of spend) to use for Target ROAS bidding strategy. The value is between 0.01 and 1000.0, inclusive. This is a required field, unless newCampaignBudgetAmountMicros is set.
newCampaignBudgetAmountMicros

string (int64 format)

Optional, budget amount to set for the campaign.

CalloutExtensionParameters

Parameters to use when applying callout extension recommendation.

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

object (CalloutFeedItem)

Callout extensions to be added. This is a required field.

CallExtensionParameters

Parameters to use when applying call extension recommendation.

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

object (CallFeedItem)

Call extensions to be added. This is a required field.

SitelinkExtensionParameters

Parameters to use when applying sitelink recommendation.

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

MoveUnusedBudgetParameters

Parameters to use when applying move unused budget recommendation.

JSON representation 
{
  "budgetMicrosToMove": string
}
Fields
budgetMicrosToMove

string (int64 format)

Budget amount to move from excess budget to constrained budget. This is a required field.

ResponsiveSearchAdParameters

Parameters to use when applying a responsive search ad recommendation.

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

object (Ad)

Required. New ad to add to recommended ad group.

UseBroadMatchKeywordParameters

Parameters to use when applying a use broad match keyword recommendation.

JSON representation 
{
  "newBudgetAmountMicros": string
}
Fields
newBudgetAmountMicros

string (int64 format)

New budget amount to set for target budget resource.

ResponsiveSearchAdAssetParameters

Parameters to use when applying a responsive search ad asset recommendation.

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

object (Ad)

Updated ad. The current ad's content will be replaced.

ResponsiveSearchAdImproveAdStrengthParameters

Parameters to use when applying a responsive search ad improve ad strength recommendation.

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

object (Ad)

Updated ad. The current ad's content will be replaced.

RaiseTargetCpaBidTooLowParameters

Parameters to use when applying a raise target CPA bid too low recommendation. The apply is asynchronous and can take minutes depending on the number of ad groups there is in the related campaign..

JSON representation 
{
  "targetMultiplier": number
}
Fields
targetMultiplier

number

Required. A number greater than 1.0 indicating the factor by which to increase the target CPA. This is a required field.

ForecastingSetTargetRoasParameters

Parameters to use when applying a forecasting set target roas recommendation.

JSON representation 
{
  "targetRoas": number,
  "campaignBudgetAmountMicros": string
}
Fields
targetRoas

number

New target ROAS (revenue per unit of spend) to set for a campaign resource. The value is between 0.01 and 1000.0, inclusive.
campaignBudgetAmountMicros

string (int64 format)

New campaign budget amount to set for a campaign resource.

CalloutAssetParameters

Parameters to use when applying callout asset recommendations.

JSON representation 
{
  "adAssetApplyParameters": {
    object (AdAssetApplyParameters)
  }
}
Fields
adAssetApplyParameters

object (AdAssetApplyParameters)

Required. Callout assets to be added. This is a required field.

AdAssetApplyParameters

Common parameters used when applying ad asset recommendations.

JSON representation 
{
  "newAssets": [
    {
      object (Asset)
    }
  ],
  "existingAssets": [
    string
  ],
  "scope": enum (ApplyScope)
}
Fields
newAssets[]

object (Asset)

The assets to create and attach to a scope. This may be combined with existingAssets in the same call.
existingAssets[]

string

The resource names of existing assets to attach to a scope. This may be combined with newAssets in the same call.
scope

enum (ApplyScope)

Required. The scope at which to apply the assets. Assets at the campaign scope level will be applied to the campaign associated with the recommendation. Assets at the customer scope will apply to the entire account. Assets at the campaign scope will override any attached at the customer scope.

ApplyScope

Scope to apply the assets to.

Enums
UNSPECIFIED The apply scope has not been specified.
UNKNOWN Unknown.
CUSTOMER Apply at the customer scope.
CAMPAIGN Apply at the campaign scope.

CallAssetParameters

Parameters to use when applying call asset recommendations.

JSON representation 
{
  "adAssetApplyParameters": {
    object (AdAssetApplyParameters)
  }
}
Fields
adAssetApplyParameters

object (AdAssetApplyParameters)

Required. Call assets to be added. This is a required field.

SitelinkAssetParameters

Parameters to use when applying sitelink asset recommendations.

JSON representation 
{
  "adAssetApplyParameters": {
    object (AdAssetApplyParameters)
  }
}
Fields
adAssetApplyParameters

object (AdAssetApplyParameters)

Required. Sitelink assets to be added. This is a required field.

RaiseTargetCpaParameters

Parameters to use when applying raise Target CPA recommendations.

JSON representation 
{
  "targetCpaMultiplier": number
}
Fields
targetCpaMultiplier

number

Required. Target to set CPA multiplier to. This is a required field.

LowerTargetRoasParameters

Parameters to use when applying lower Target ROAS recommendations.

JSON representation 
{
  "targetRoasMultiplier": number
}
Fields
targetRoasMultiplier

number

Required. Target to set ROAS multiplier to. This is a required field.

ForecastingSetTargetCpaParameters

Parameters to use when applying a set target CPA recommendation.

JSON representation 
{
  "targetCpaMicros": string,
  "campaignBudgetAmountMicros": string
}
Fields
targetCpaMicros

string (int64 format)

Average CPA to use for Target CPA bidding strategy.
campaignBudgetAmountMicros

string (int64 format)

New campaign budget amount to set for a campaign resource.

LeadFormAssetParameters

Parameters to use when applying a lead form asset recommendation.

JSON representation 
{
  "adAssetApplyParameters": {
    object (AdAssetApplyParameters)
  },
  "setSubmitLeadFormAssetCampaignGoal": boolean
}
Fields
adAssetApplyParameters

object (AdAssetApplyParameters)

Required. Lead form assets to be added. This is a required field.
setSubmitLeadFormAssetCampaignGoal

boolean

If true, the "Submit Lead Form" goal will be set on the target campaign. As a result, ads will be shown as lead form creative ads. If false, the "Submit Lead Form" goal will not be set on the campaign and ads will contain lead form assets.

ApplyRecommendationResult

The result of applying a recommendation.

JSON representation 
{
  "resourceName": string
}
Fields
resourceName

string

Returned for successful applies.