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.

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

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

Response message for RecommendationService.ApplyRecommendation.

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 (e.g. 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)
  }
  // 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.

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

ApplyRecommendationResult

The result of applying a recommendation.

JSON representation 
{
  "resourceName": string
}
Fields
resourceName

string

Returned for successful applies.