AdWords API sandbox – Best practices
March 20th, 2009 | Published in Google Adwords API
The API sandbox is open to anyone who wants to test code during development, and it's completely free. We recommend using the sandbox as much as possible to catch your bugs during development so they won't hit your production account later. Here are some tips on using the sandbox effectively:
The sandbox database is usually refreshed once every month, wiping out all client accounts. Making getClientAccounts() as your application's first API call ensures that all your calls happen against a properly initialized sandbox account.
Simulate error responses
Because a good application needs to gracefully handle errors thrown by the AdWords API, the sandbox provides a mechanism for simulating error messages. If you use [email protected]++errorCode as the email for a call to the sandbox, the sandbox will return an error response with error code set as the desired errorCode, and a text message indicating that an error response has been forced by the sandbox.
If the name doesn't contain any of the above codes, the sandbox will create a report whose status changes as follows:
Also, a call to getAllJobs will return four reports, one for each value of ReportJobStatus. Sandbox reports do not return any data related to any live accounts. So if you want to test your report parsing logic against some live data, you can generate a report of the desired type in the Reports Center of your production account, download it in xml format, and use it to develop and test your code.
Both TrafficEstimatorService and KeywordToolService are available for use in AdWords API sandbox. However, both these services return fake data. TrafficEstimatorService will give you fake data for Position, CPC, and Clicks per day. KeywordToolService can give you fake Seed-based keyword suggestions when using getKeywordVariations. It can also give you content-based keyword suggestions and SiteKeyword statistics when using getKeywordsFromSite.
The AdWords API sandbox can greatly help you with your development by preventing bugs from hitting production account during early stages of development. You can find more information on AdWords API sandbox at http://code.google.com/apis/adwords/docs/developer/adwords_api_sandbox.html.
-Anash P. Oommen, AdWords API Team
Initialize your sandbox account
Make sure that the first call to the sandbox is a get() call from AccountService, preferably AccountService's getClientAccounts(). Assuming you use [email protected] as the login email, this call will initialize the sandbox and create 5 test client accounts, namely [email protected] to [email protected] for your sandbox account. While making this call you should not provide the clientEmail or clientCustomerId headers, since this call expects an MCC account to succeed.
Make sure that the first call to the sandbox is a get() call from AccountService, preferably AccountService's getClientAccounts(). Assuming you use [email protected] as the login email, this call will initialize the sandbox and create 5 test client accounts, namely [email protected] to [email protected] for your sandbox account. While making this call you should not provide the clientEmail or clientCustomerId headers, since this call expects an MCC account to succeed.
While making a getClientAccounts() call to the sandbox, set the SOAP headers as follows:
email: address of any google account, such as a Gmail account
password: password of the account
useragent: set to any identifying string
developerToken: set to the value for email, with the string '++USD' (or the currency code of your choice) appended
applicationToken: ignored, and could be set to anything or left out
clientEmail: should be either set to the empty string or left out
email: address of any google account, such as a Gmail account
password: password of the account
useragent: set to any identifying string
developerToken: set to the value for email, with the string '++USD' (or the currency code of your choice) appended
applicationToken: ignored, and could be set to anything or left out
clientEmail: should be either set to the empty string or left out
clientCustomerId: should be either set to the empty string or left out
The sandbox database is usually refreshed once every month, wiping out all client accounts. Making getClientAccounts() as your application's first API call ensures that all your calls happen against a properly initialized sandbox account.
Simulate error responses
Because a good application needs to gracefully handle errors thrown by the AdWords API, the sandbox provides a mechanism for simulating error messages. If you use [email protected]++errorCode as the email for a call to the sandbox, the sandbox will return an error response with error code set as the desired errorCode, and a text message indicating that an error response has been forced by the sandbox.
The error code should be set to one of the valid error codes. For instance, by providing login email as [email protected]++17, I can simulate error code 17 (account exceeded maximum number of allowed campaigns).
The SOAP response looks as follows:
soapenv:Server.userException
Error forced by the request (Sandbox)
Error forced by the request (Sandbox)
[email protected]++17
Similarly, you can also test for some policy violations in ads and keywords. For instance, providing repeated punctuation in the ad or keyword text, such as "Hello World!!" as the ad title, should trigger a policy violation error. However, the sandbox doesn't have all of the policy checks in place, so you can't test your application against every possible policy violation, e.g. trademark-related violations.
17Similarly, you can also test for some policy violations in ads and keywords. For instance, providing repeated punctuation in the ad or keyword text, such as "Hello World!!" as the ad title, should trigger a policy violation error. However, the sandbox doesn't have all of the policy checks in place, so you can't test your application against every possible policy violation, e.g. trademark-related violations.
Generate reports
Since generating reports is one of the most common calls in the AdWords API, the sandbox provides features to test each stage of your report generation logic. In the sandbox, you can create either a report whose status does not change, or a report whose status changes from pending to deleted. If you include any one of the following strings in the report name field while creating it, it will create a report with the specified status.
Since generating reports is one of the most common calls in the AdWords API, the sandbox provides features to test each stage of your report generation logic. In the sandbox, you can create either a report whose status does not change, or a report whose status changes from pending to deleted. If you include any one of the following strings in the report name field while creating it, it will create a report with the specified status.
- fixstatus=Pending
- fixstatus=InProgress
- fixstatus=Completed
- fixstatus=Failed
If the name doesn't contain any of the above codes, the sandbox will create a report whose status changes as follows:
- During the first minute since the report job was scheduled, the status is Pending.
- During the second minute, the status is InProgress.
- During the third minute, the status is Completed.
- After the third minute, the report is deleted.
Also, a call to getAllJobs will return four reports, one for each value of ReportJobStatus. Sandbox reports do not return any data related to any live accounts. So if you want to test your report parsing logic against some live data, you can generate a report of the desired type in the Reports Center of your production account, download it in xml format, and use it to develop and test your code.
Handling account limits
As with a live account, an AdWords sandbox account can hold a maximum of 25 active campaigns, with up to 100 active ad groups per campaign. If your program runs into these limits, then you can change the status of some campaigns or ad groups to "deleted."
As with a live account, an AdWords sandbox account can hold a maximum of 25 active campaigns, with up to 100 active ad groups per campaign. If your program runs into these limits, then you can change the status of some campaigns or ad groups to "deleted."
TrafficEstimatorService and KeywordToolService behavior
Both TrafficEstimatorService and KeywordToolService are available for use in AdWords API sandbox. However, both these services return fake data. TrafficEstimatorService will give you fake data for Position, CPC, and Clicks per day. KeywordToolService can give you fake Seed-based keyword suggestions when using getKeywordVariations. It can also give you content-based keyword suggestions and SiteKeyword statistics when using getKeywordsFromSite.
The AdWords API sandbox can greatly help you with your development by preventing bugs from hitting production account during early stages of development. You can find more information on AdWords API sandbox at http://code.google.com/apis/adwords/docs/developer/adwords_api_sandbox.html.
-Anash P. Oommen, AdWords API Team