Anash P. Oommen, AdWords API Team
Originally Published March, 2009

Contents

1. Introduction
2. Initialize your sandbox account
3. Simulate error responses
4. Generate reports
5. Handling account limits
6. TrafficEstimatorService and KeywordToolService behavior

Introduction

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:

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 user@domain.com as the login email, this call will initialize the sandbox and create 5 test client accounts, namely client_1+user@domain.com to client_5+user@domain.com 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:

Header name	Description
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.
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 user@domain.com++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 user@domain.com++17, I can simulate error code 17 (account exceeded maximum number of allowed campaigns).

The SOAP response looks as follows:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <soapenv:Fault>
      <faultcode>soapenv:Server.userException</faultcode>
      <faultstring>Error forced by the request (Sandbox)</faultstring>
      <detail>
        <ns1:fault xmlns:ns1="https://adwords.google.com/api/adwords/v13">
          <ns1:code>17</ns1:code>
          <ns1:message>Error forced by the request (Sandbox)</ns1:message>
          <ns1:trigger>user@domain.com++17</ns1:trigger>
        </ns1:fault>
      </detail>
    </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>

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.

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.

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

Handling account limits

As with a live account, an AdWords sandbox account can hold a maximum of 25 active campaigns, with up to 2000 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.