Sandbox
The AdWords API Sandbox is an environment that replicates the API of the live site, for developing, testing and debugging applications that use the AdWords API. When a developer logs in, AdWords accounts are automatically created in the Sandbox, then the developer can create and run campaigns, adgroups, creatives, and other operations on those accounts without incurring any quota. There is no quota on the Sandbox system — users are free to make all the calls they want. All account, campaign, adgroup, creative and criteria data that you submit can be read back as usual. However, the extra information based on usage and ad impressions such as traffic estimates, statistics, reports, and keyword suggestions, will be fake. The details on fake data are listed throughout this document. The Sandbox is not meant for load testing.
Developers can use this Sandbox to:
- Develop programs without expending their quota
- Test code that modifies mock AdWords campaigns without affecting live campaigns
- Develop against new or changed AdWords API methods before the changes go live on the real service
- Create client libraries without requiring a real AdWords account
Setup and Creating Accounts
To use the AdWords API Sandbox, you must first have a Google account. You can use an existing account or create a new one. Use this account's email and password in the Sandbox request header. When you first access the Sandbox, five client Sandbox accounts are automatically created. These client accounts are accessible by way of the clientEmail header.
You can then go right ahead and make a call to the Sandbox using the WSDL locations and request headers.
Notice the developerToken (or token) header is different for the Sandbox than it is in the standard request header, in that it takes a currency code.
The Sandbox starts out essentially empty, with no user data. You can set up campaigns, ad groups, creatives and so forth in the Sandbox that will be saved to the Sandbox accounts, but please do not rely on your Sandbox data for long periods of time, as it is periodically cleansed.
IMPORTANT - The Sandbox is cleared of user and account data on a periodic basis. Currently, we expect that to be about once a month, but it may occur more frequently.
Sandbox WSDL Locations
The Sandbox WSDL locations are identical to those of the AdWords API but with the domain sandbox.google.com instead. This URL must be used for all versions. or example, for CampaignService in v12:
https://sandbox.google.com/api/adwords/v12/CampaignService?wsdl (Sandbox)
https://adwords.google.com/api/adwords/v12/CampaignService?wsdl (Live site)
The AdWords API SOAP headers for the Sandbox are similar to the standard request header, and must be set with the following data:
|
Header |
Value |
Comment |
|---|
| email
|
login_id |
Email address for the account being accessed — must be for a valid Google account. Example email: johndoe@example.com |
| password
|
password |
Password for the Google account used in the email header |
| useragent
|
application_user_agent |
An arbitrary string that identifies the customer sending the request — should be the same value the application will use in the production environment |
| developerToken (or token)
|
login_id++currency_code |
A string that identifies you as an authorized user of the Sandbox. Must be the same login_id used in the email header, followed by ++ and a valid currency code. The currency code is the one used by the account; it cannot be changed at all — if you attempt to change it, the change is ignored.
Example token: johndoe@example.com++USD
Also see Note on Currency Code. |
| applicationToken
|
22_character_string |
NOTE - Always ignored in sandbox
A string that identifies an application as being authorized to call the AdWords API web services. If your application calls another application, use the application token for the one that actually sends the request. An example token string is ZYXwvu-TSR123_456ABCDE. Application tokens are 22 characters long. |
| clientEmail
|
client_#+login_id
|
Optional. A header element to be used when a My Client Center (MCC) account edits a client's account. If this header is present, it must be one of the following values:
client_1+login_id
client_2+login_id
client_3+login_id
client_4+login_id
client_5+login_id
where login_id is the same value used in the email header.
Example clientEmail: client_1+johndoe@example.com |
Note on Currency Code -
To simplify the use of the Sandbox, MCC and Client accounts are
created on the fly if they don't already exist in the system.
This means Sandbox users do not need to go through a registration
process. On the live site, the account currency information
is set at registration time. Thus, the Sandbox allows users to
specify the currency code for their acccounts, through the token.
In both the live site and Sandbox, it cannot be changed after
the account has been created.
Because Sandbox users do not have knowledge or control over
when their MCC and Client accounts are created, they must always
provide the currency code in the token. Then, if the accounts
are implicitly created during a particular request, that
currency code will be set for the accounts. If the accounts
are already created, then the currency code is ignored.
Note that if the token does not include the currency code,
the request will fail.
Sandbox Restrictions
Any method that normally requires special permission
(like createAdWordsAccount) does not work on the sandbox.
Policy Checks
The sandbox has mocked out the policy checks so that only words with repeated punctuation will trigger a creative violation, for example "Sale!!"
Traffic Estimator
The Traffic Estimator Service is replaced by a mock service that returns randomly generated stats as follows.
NOTE - In the following ranges, a square bracket means "including" and a parenthesis means "excluding". Thus, [0-20) means the range of integers including 0 but excluding 20.
- Position: random integer in range [0,20)
- CPC: random integer in range [MAX_CPC/2,MAX_CPC)
- Clicks per day: random integer in range (1 - (MAX_CPC - CPC) / MAX_CPC) * random [0,500)
The lower and upper values of the previous properties will be randomly calculated in the [0,100%) and [100%,200%) ranges.
Report Service
All Sandbox report jobs contain random data unrelated to any live accounts.
You can create a report job with a particular status that will not change, or a report job that "rolls" through the statuses. If a request job name literally contains one of the following strings (case doesn't matter), it will set the report to the corresponding status and keep it in that state. The strings are:
- "fixstatus=Pending"
- "fixstatus=InProgress"
- "fixstatus=Completed"
- "fixstatus=Failed"
If a request job name does not contain any of these strings, the job will have a rolling state based on minutes since the scheduling time: the first minute in "Pending", the second minute in "InProgress", the third minute in "Completed" and then the report is automatically deleted.
For example, if you schedule a DefinedReportJob with its name set to includes_fixstatus=Pending, that report job would be permanently set to Pending status.
The getAllJobs request returns an array of four DefinedReportJob objects (one for each of value of ReportJobStatus).
The getAllJobs request returns an array of eight sample reports, one of each type: KeyWordReportJob with "Pending" status, AdTextReportJob with "InProgress" status, CustomReportJob with "Completed" status, URLReportJob with "Failed" status, CampaignReportJob with "Completed" status, AccountReportJob with "InProgress" status, AdGroupReportJob with "Pending" status, and AdImageReportJob with "Failed" status.
The deleteReport request does nothing.
The following Keyword Tool services are mocked out:
Seed-based keyword suggestions: getKeywordVariations generates two suggestions per keyword: the first one is the original one with the word suggestion prepended to it, the second one is the word suggestion followed by the words in the original keyword in reverse order. If the keyword has only one word, then only one suggestion is made. For example, a seed of "bath towel" would generate keywords "suggestion bath towel" and "suggestion towel bath".
Content-based keyword suggestions: getKeywordsFromSite generates site-based keywords in random numbers of groups of suggestions: range of [1,10] groups with includeLinkedPages false, and a range of [1,20] groups with includeLinkedPages true. The number of keywords is [number_of_groups, number_of_groups*10], distributed randomly in the groups, which generates a list of more than 200 keywords.
SiteKeyword: uses the java.lang.String hash code of the keyword text to generate the searchVolumeScale (HASH % 6) and advertiserCompetitionScale (HASH/13 % 6) values.
Images
The Sandbox has a mock image service that discards any uploaded images and returns canned information including canned image URLs pointing to fixed images served by the Sandbox.
The returned canned information will be:
- type=image
- mimeType=image/jpeg
- width=468
- height=60
- imageUrl=sandbox.google.com/sandboximages/image.jpg
- thumbnailUrl=sandbox.google.com/sandboximages/thumbnail.jpg
Forcing Error Responses
As one of the objectives of the Sandbox is to help developers make more robust applications, we will provide a mechanism to simulate AdWords API error responses.
For all service calls, if the email header consists of the login_id++error_code, the response to service call will consist of the provided error code and a text message indicating the error has been forced by the request. The error code must be one of the AdWords API error codes.
API Reference
