This page covers various best practices that should be considered when developing applications against the AdWords API.
-
General
- Reuse auth tokens across multiple requests
- Detect missing application-specific password when using 2-step authentication
- Batch operations together into fewer requests
- Group operations by target ad group or campaign
- Send sparse objects for updates
- Implement error handling and retries
- Use a test account for development
- Rename as you delete
- Compress SOAP messages
- Take advantage of the partial failure feature
- Targeting Ideas
General
Reuse auth tokens across multiple requests
Excessive calls to the ClientLogin service to obtain auth tokens can lead to CAPTCHA challenges, which require human intervention to solve. To prevent this from happening, auth tokens should be reused for multiple requests. The tokens are valid for up to two weeks, although they may expire early if the password is changed on the account. A request made with an expired auth token will return a GOOGLE_ACCOUNT_COOKIE_INVALID error.
For interactive applications, request an auth token when a user logs in to the system and reuse it for all requests during that session. For automated applications, request an auth token when the script starts and reuse it for all requests during that execution. Jobs that repeat may benefit from persisting auth tokens between executions, but care should be taken to store them securely.
Detect missing application-specific password when using 2-step authentication
Google allows an advanced opt-in 2-step verification process to help make your Google Accounts significantly more secure. If a 2-step verification user tries to login using their regular account password, then the ClientLogin API will return an error indicating that they need to use an application-specific password instead. When this happens the response will contain an extra field that indicates that the error was due to a missing 2-step verification code, and not incorrect credentials.
Error=BadAuthentication
Info=InvalidSecondFactor
APIs accessing this interface must instead use a special password called an application-specific password. Your application should detect this error and remind the user to use an application-specific password. To test your application for 2-step verification errors, you can use the following account:
LoginEmail = "[email protected]"
Password = "testaccount"
Batch operations together into fewer requests
Making a request to the API has certain fixed costs, such as network transfer, serialization and deserialization, calls to backend systems, etc. Batching multiple operations into a single request lessens the impact of these fixed costs and increases overall performance. The mutate() methods in the API are designed to accept an array of operations, so avoid making single-operation requests when possible.
Take the example of adding 5000 keywords to a campaign, across multiple ad groups. Instead of making 5000 requests with 1 keywords each, make 10 requests with 500 keywords each. There are limits on the number of operations allowed in a request, and you may need to adjust your batch size to achieve optimal performance.
Group operations by target ad group or campaign
Operations that all target the same ad group or campaign will process faster than the same number of operations targeting many different ad groups or campaigns. Grouping together operations that target the same ad group or campaign will limit the total number of ad groups or campaigns targeted in the request, improving overall performance.
Additionally, subsequent requests to the same ad group or campaign may conflict with backend processes, leading to CONCURRENT_MODIFICATION errors. Processing all operations against the same ad group or campaign in a single request will decrease the chances of such a conflict.
Take the example above of adding 5000 keywords to a campaign, across multiple ad groups. Before breaking the operations into batches of 500, sort the keywords by the ad group they target. This increases the chance that all the keywords within the same ad group will fall within the same request, and hence decreases the total number of ad groups targeted in a single request. Even further sophistication can be applied to ensure that operations are grouped together while still maintaining large batches.
Send sparse objects for updates
When objects are sent to the AdWords API, all the fields must be deserialized, validated, and stored in the database. Passing in full objects when you only want to update a few fields can result in extra processing time and decreased performance. The AdWords API supports sparse updates however, allowing you to populate only the fields in that object that you wish to change or that are required. Fields that are unpopulated or have null values are left unchanged, which can increase the performance of your requests.
An application that updates keyword-level bids can benefit from using sparse updates, as only the ad group ID, criterion ID, and bids field would need to be populated in the request. In a test using 150 keywords, a 20% performance increase was seen using sparse updates instead of passing the fully populated objects.
Implement error handling and retries
Careful coding and a good understanding of the API will greatly reduce the chances of encountering an error, but there are a variety of errors that are unavoidable and should be handled in your application. Some of the most common errors are documented in the Troubleshooting Guide, which includes tips on how to handle them when they occur.
For some errors a short pause and a retry will resolve the issue. This is usually the case with CONCURRENT_MODIFICATION or UNEXPECTED_INTERNAL_API_ERROR, although sometimes there are more complex causes at work. Implementing retry logic in your application allows you to better handle these temporary problems and create a more stable platform.
When an unexpected type of error does occur, it's important to log the request ID and details of the error. Additionally, logging the SOAP XML request and response can be instrumental in replicating and debugging the issue. The client libraries provide request and SOAP logging capabilities, as well as the ability to retrieve the requestId header.
Use a test account for development
Test accounts allow you to make API calls without incurring operation costs or affecting ad serving. You don't need an approved developer token to access a test account, so you can start developing with the AdWords API before your application is reviewed. Read Using AdWords Test Accounts to learn more about test accounts and how to get one.
Rename as you delete
Certain objects are required to have unique names within an account. These include AdGroup, Campaign, ConversionTracker, and UserList. Even deleted objects are taken into account when determining uniqueness, so a recommended best practice is to rename these objects as you delete them.
For example, let's say you delete a campaign called "Holiday Sales" after the holidays are over. If you try to create a new campaign with the same name a year later you would receive the error CampaignError.DUPLICATE_CAMPAIGN_NAME. Instead rename the campaign as you delete it, appending a timestamp to the original name, for example "Holiday Sales (Deleted 2011-04-18 18:20:01)". This would ensure that next year's campaign can be created without error.
Compress SOAP messages
The AdWords API supports compressed (gzip) SOAP messages in requests and responses. To enable gzip compression in responses, include these two HTTP headers:
User-Agent:containing the string "gzip".Accept-Encoding:with the valuegzip.
Example:
User-Agent: my program (gzip) Accept-Encoding: gzip
Take advantage of the partial failure feature
Most requests to the AdWords API are atomic: all changes succeed or all fail even if an error occured during just one operation. In some cases this is not desirable as the changes might be independent of one another, and only the failed ones need to be reviewed. For such cases you can utilize the partial failure feature.
You can request the API to commit all successful changes and return the list of those which failed by setting the 'partialFailure' header to true. All official client libraries support this flag.
Targeting Ideas
Batch keywords in STATS requests
Unlike IDEAS requests that generate new keyword ideas, STATS requests can be used to retrieve just the statistics of known keywords. One TargetingIdea is returned for each keyword in the RelatedToQuerySearchParameter, and the data for multiple keywords can be retrieved in a single request. For example, when fetching the stats for 100 keywords, it's more efficient to make one request with all 100 keywords than 100 requests, each with one keyword.