AdWords API

FAQ

General Questions

Signup

Pricing and Compliance

API Versioning

Technical Questions


General Questions

What is the AdWords API?

The AdWords API allows developers to use applications that interact directly with the AdWords server. With these applications, advertisers can more efficiently manage large AdWords accounts and campaigns. Please review the AdWords API rate sheet for details about API pricing.

How can I use the AdWords API?

You can use the AdWords API to employ or develop programs that help you or your clients more efficiently interact with related AdWords accounts. Some possibilities might include:

  • Generating automatic keyword, ad text, URL, and custom reports
  • Integrating AdWords data with other databases, such as inventory systems
  • Developing additional tools and applications to help you better manage AdWords accounts

All you need to get started writing programs is a Developer Token, which you'll receive upon signup. After your token is approved, you'll be able to access the API.

Who should sign up for the AdWords API?

The AdWords API is designed for developers representing large, tech-savvy advertisers and third parties. This includes SEMs (search engine marketers), agencies, and other online marketing professionals who manage multiple client accounts and/or large campaigns. Because implementing the AdWords API takes technical know-how and programming skills, advertisers who employ developers can achieve the best results.

What if I don't have a My Client Center account?

You need to have a My Client Center (MCC) account to apply for access to the API. If you do not already have an MCC account, you will have to create one. For more information about My Client Center, please visit our FAQ.

If you create a new MCC account in order to apply for the API token, link all of your existing accounts or the accounts of your clients to the new MCC. This will ensure that your application is processed as swiftly as possible. See this link for instructions.

Why do I need a My Client Center account in order to access the AdWords API?

Developer tokens are granted only to My Client Center (MCC) accounts. Typical users of the AdWords API—advertisers and agencies which manage many accounts—will already have an MCC account.

Is there a difference between managing my AdWords account through the AdWords API and the AdWords interface?

The AdWords API offers much of the same AdWords functionality that is available through our online interface. Any changes you make through your AdWords API will affect your AdWords account. The difference is that the AdWords API gives developers and users more flexibility to create additional applications and tools to manage their AdWords accounts. This depends on the client software being used and programs created.

Are changes I make through the AdWords API reflected in my live AdWords account?

Yes. Any changes you make via the AdWords API will impact your live AdWords account. We recommend that you test your applications on test accounts before deploying them in production.

What applications can I develop?

This all depends on your programming talents and advertising needs. Some possibilities might include:

  • Automatically creating ads, ad groups, and campaigns
  • Automatically downloading reports to monitor performance
  • Integrating AdWords data with other databases, such as inventory systems
  • Developing additional tools and applications to help you better manage your AdWords accounts

See more use cases.

What is a Developer Token?

A Developer Token is a unique combination of letters, numbers, and characters that identifies your AdWords API activity. It is your key to talking to the AdWords server and your clients' AdWords accounts. In order for us to identify your activity, you should include the Developer Token in the header of all your API requests.

To protect yourself from fraud, do not share your Developer Token with others. You can find your Developer Token through your AdWords API Center—accessible from your My Client Center's My Account tab.

How do I use the Developer Token?

You should include your Developer Token in the header of all your API requests so we can authenticate and properly identify your AdWords account activity. You may not have to manipulate the header directly if you take advantage of one of our client libraries.

I need to hire someone to create a program for me. Where do I look?

Start by searching our Developer's Forum. You can find past postings or post your own request here. You can also visit Webmaster World for help. When in doubt, perform a Google search on 'AdWords API developer.' Please note that these developers are not employed, endorsed, or approved by Google.

When searching for a developer, it's important that you do your research and hire a developer who you can trust. Google does not officiate over partnerships you may build with developers. Therefore, we suggest you conduct a comprehensive screening process and unearth as much information as possible before hiring a developer.

How may I use the Google AdWords logo?

Below are some restrictions on using the AdWords logo with your API Client. Your permission to use the logo is granted in the AdWords API Terms and is subject to these restrictions.

The AdWords API Terms are written to permit you to resize the logo to fit your AdWords API client application as long as you maintain the aspect ratio of the logo. If you are using the logo on a webpage, there must exist a minimum spacing that is no less than 1/2 the height of the logo between each side of the logo and other graphic or textual elements on your webpage. Also, the logo must appear by itself in a manner that does not in any way indicate to viewers of the webpage that Google endorses any non-Google products, services, or information provided on that webpage.

You can't (and agree not to) do any of the following:

  • Change the aspect ratio or colors of the logo in any way
  • Display the logo as the most prominent element on your webpage
  • Display the logo in any manner that implies a relationship or affiliation with Google or sponsorship or endorsement by Google. It can't be used in a way that can be reasonably interpreted to suggest editorial content or data analysis has been authored by or represents the views or opinions of Google or Google personnel
  • Display the logo on your website other than as permitted by Google Permissions
  • Display the logo on any product, book, or other material (other than what was specified as OK in the guidelines above)
  • Display the logo on any website that contains or displays adult content, promotes gambling, involves the sale of tobacco or alcohol to persons under 21 years of age, or otherwise violates applicable law or stated Google editorial policies
  • Display the logo in a manner that is in Google's sole opinion misleading, defamatory, infringing, libelous, disparaging, obscene, or otherwise objectionable to Google
  • Display the logo on a site that violates any law or regulation
  • Frame or mirror any Google page (including the page that appears in response to a click on the Google logo or Google search box)
  • Remove, distort, or alter any element of the logo
  • Display the logo so it appears larger or more prominent than your name, product, or service name, trademark or service mark, logo, or trade or company name
  • Include the logo in your trade or business name, domain name, product or service name, logo, trade dress, design, slogan, or other trademarks
  • Translate the logo or otherwise localized into any other language. Any translated versions of the logo must be provided by Google
  • Display the logo as a design feature on any of your materials
  • Imitate the logo in any manner in your materials

You may not use the logo in any way other than as specified in these guidelines. Failure to comply with these instructions is a breach of the Google AdWords API Agreement.

Can I sign up if I have an AdSense or other Google account?

Yes. AdSense, Gmail, or other Google service users can sign up for the Google AdWords API program. We only require that you have a current AdWords account. If you would like to sign up for AdWords, please visit https://adwords.google.com.

I already have a My Client Center account. What happens to it when I sign up?

After you enroll in the Google AdWords API program, your My Client Center account will be automatically updated, unchanged. Your personal information and client accounts linked to your account will not be affected. The only difference is you'll now have a new sub-tab, named AdWords API Center, available from your My Account tab. Click on this sub-tab to access your Developer Token and API usage information.

What is SOAP?

SOAP is the Simple Object Access Protocol. It's used for information exchange and RPC, usually (but not necessarily) over HTTP. More information can be found in the specifications. The AdWords API uses the SOAP architecture.

What is the WSDL?

WSDL is the Web Service Description Language. It provides a formal description of a web service, much like CORBA's IDL. The WSDL file is all you need to know how to call the web service; toolkits can generate proxy code from a WSDL file directly.

What is the AdWords API mailing list?

The AdWords API mailing list provides product updates and announcements, sent directly to your email inbox. Our mailing list is powered by Google Groups, so you can sign up in three easy steps:

  1. Enter your email address on the AdWords API home page.
  2. Wait for a confirmation email to arrive in your inbox.
  3. Click the verification link contained in the email to activate your subscription to the mailing list.

That's it! You don't need to click the 'Join' or 'Sign in' links from the Google Groups confirmation page.

We'll send email to the mailing list when there are product feature announcements that you'll be interested in, but we won't send you anything unrelated to the API—your email address is protected by our privacy policy.

Find instructions on how to unsubscribe to the API mailing list.

How do I opt-out of the AdWords API Announcements Mailing List?

You can opt out of the AdWords API Announcements mailing list by unsubscribing through Google Groups. Here’s how:

If you’re a registered Google Groups user (or you think you might be):

  1. Go to the Announcements mailing list membership page.
  2. Click the 'unsubscribe' button to remove your email address from the AdWords API Announcements mailing list.

If you’re not a registered Google Groups user, you must first sign up for Google Groups before you can opt out of the mailing list. To do this:

  1. Sign up for a Google Groups account. (Be sure to use the same email address you used to sign up for the AdWords API Announcements mailing list.)
  2. Go to the Announcements mailing list membership page.
  3. Click the 'unsubscribe' button to remove your email address from the AdWords API Announcements mailing list.

Find instructions on how to subscribe to the API mailing list.

When is the API down for scheduled maintenance?

We currently do not have a maintenance schedule. Any expected service interruptions will be announced in the AdWords API Announcement Forum.

How do I authorize AdWords tools after signing up for 2-step verification in my AdWords account?

We strongly recommend you use OAuth2 authorization instead of ClientLogin, which is now deprecated and will be removed in the future.

If you still use ClientLogin and you've opted to use 2-step verification, and your Google Account is associated with other Google products (like the AdWords API or AdWords Editor), you'll need to enter an application-specific password instead of your regular account password when you log in using these tools. Learn how to generate an application-specific password. (For instructions on using the application-specific password in AdWords Editor, see this article.)

If you no longer want to use 2-step verification, you can follow these instructions to disable 2-step verification for your Google Account.

Who should I contact for help?

We suggest that you browse through the AdWords API developer site. Here, you'll find helpful guides, sample code, and reference documentation. Also, you can join our Developer's Forum to get help from other AdWords API developers, as well as follow our Google+ page for the latest scoop about the API.

Back to top


Signup

What's my "company type"?
When you apply for access to the AdWords API, you'll be asked for your company type. Here are your options:
  • Advertiser - You manage AdWords campaigns only for your company's website(s), products, or services. You do not manage AdWords campaigns for any other companies.
  • Agency/SEM - You manage AdWords campaigns for clients, and may offer additional services related to online marketing, web hosting, SEO, etc.
  • Affiliate - You participate in other companies' affiliate programs. You use AdWords to help advertise their products online.
  • Independent AdWords Developer - You intend to use the AdWords API to develop and license software related to AdWords. You do not manage AdWords campaigns for clients.
What happened to the Integration Service company type?

The Integration Service company type has been combined with Agency/SEM. This will not affect your access to the API in any way.

What do I need to get started using the AdWords API after signup?

All you need to get started is an approved Developer Token. You can acquire it after you register for the AdWords API.

After you sign up, your Developer Token will be sent to your account email address. Once approved, this token will be activated and you'll be able to access the API by including it in your request headers. Your token will be shown on your AdWords API Center—accessible through your My Client Center's My Account tab.

Read our FAQ to learn more about Developer Tokens.

How do I update my Developer Contact Email?

To change/update your contact email, follow these instructions:

  1. Log in to your AdWords My Client Center Account and click the gear icon in the top-right.
  2. From the drop-down, click Account Settings.
  3. Click the AdWords API Center from the navigation tab on the left.
  4. In the section containing your Developer Details, click Edit.
Can I start using the API as soon as I sign up?

After you provide your developer and billing information, you'll be assigned a Developer Token, but you'll need to wait until your token has been approved before accessing the API. The AdWords API Review team will contact you within one week of your application. In the meantime, you may apply for a Test Account in order to begin developing and testing your application.

What information do you need about my application and its users?

We want to know what your application will do (e.g. custom reports, account management, bid optimization, etc.) and who'll be using it (e.g. colleagues in your company, your clients, advertisers or agencies to whom you will sell the application, etc.). Please be thorough in your description. The more you tell us about your application and users, the faster you will be approved and the better we can understand your needs in order to continue developing the best operations, resources, and support for our users. We will not share any of the information you provide to us with outside parties.

What are common reasons why a Developer Token would not be approved?

The AdWords API Terms & Conditions include detailed guidelines for appropriate use of the AdWords API. You must agree to these terms during the billing set-up step. If you have used, or intend to use, the API in ways inconsistent with these terms, your tokens will not be approved. If you are developing an external tool—one in which your clients will access—your tool must implement our Required Minimum Functionality.

Read more about signing up for the AdWords API.

Back to top


Pricing and Compliance

Why is the AdWords API being offered for free?

We were charging a small fee for AdWords API usage to encourage developers to create applications that interact with the AdWords platform in an efficient and responsible manner. In 2010 we launched the preferred pricing program that offered free AdWords API units to eligible agencies and developers of search engine marketing (SEM) tools. We got positive feedback from this program and we now want to extend free usage to all developers to encourage innovation.

What are the different access levels for the AdWords API?

There are two levels of AdWords API access:

  1. Basic
  2. Standard

The access levels pertain to number of daily operations only; there are still token-level rate limits to prevent excessive stress on our systems and to guarantee good performance for all our API users. All users are still required to comply with AdWords terms, AdWords API terms, and the required minimum functionality, where applicable. There will be no charges for AdWords API usage for either basic or standard access.

Basic access: This is the default access level for all approved developer tokens. Basic access allows developers to execute up to 10,000 operations per day.

Standard access: This is the access level for those needing more usage capacity. Standard access requires developers to provide additional details and keep these details current with Google.

What are non-compliance fees and how are they determined?

In order to ensure optimal advertiser and user experience, we monitor AdWords API usage and application compliance to the AdWords API terms and conditions.

If your application is not in compliance, you'll be alerted and given a period of time to make appropriate corrections. At the end of this initial notice period, if the corrections aren't made, then you may be given an extension of up to 3 months. During this time you will be charged a monthly non-compliance fee ($10 for every 10,000 operations that were used in the month before you received your initial non-compliance notice). Continued non-compliance will result in API access being revoked.

Read more about how operations are counted.

As an example, let's say you executed 1 million operations in April, and we found that your application was not in compliance with the AdWords API terms and conditions. You would receive a 30-day notice on May 1 to bring your application into compliance. If the required changes were not made by May 31, you would be charged a flat non-compliance fee of $1,000/month (1,000,000/10,000 x $10) for a maximum of 3 months (June, July, and August) or until your application satisfies compliance requirements—whichever comes first.

We were getting free API units for advertising our own business. Do we still need to apply for standard access?

All developers requiring more than 10,000 operations per day need standard access. Allocation of free API units based on AdWords spend will be retired. Based on your history with the AdWords API and details you've shared with us, we may be able to pre-qualify you for standard access. However, in order to ensure that your API access is not affected, we encourage you to apply for standard access.

We have already been approved for preferred pricing and get free API units. Do we still need to apply for standard access?

You might or might not. The Preferred Pricing program which was offered to agencies and search engine marketing tool developers, will be retired. Starting March 1, 2013, all developers requiring more than 10,000 operations per day will need standard access. Based on your history with the AdWords API and details you've shared with us, we may be able to pre-qualify you for standard access. However, in order to ensure that your API access is not affected, we encourage you to apply for standard access if you have not heard from us OR if the details you had provided during your preferred pricing application has changed recently.

Can we continue to pay current AdWords API charges and not apply for standard access?

No. If you use or expect to use fewer than 10,000 operations per day, you are not required to apply for standard access.

How are AdWords API operations counted?

On March 1, 2013, API units will be deprecated and all operations will be counted equally. AdHoc report download requests and any requests by test accounts will not be counted towards the basic access limits or used for computing non-compliance charges. In a bulk mutate job, each operation is counted separately.

Each AdWords API operation such as a get or mutate is counted separately. For example, a get operation that generates 10 results objects will only be counted once. For mutates, each mutated item counts as one operation. The following table gives some examples on how the new accounting will work:

API request Operations counted towards Daily Limit
Operation: get
Count: 53 ad groups
Service: AdgroupAdService
1
Operation: mutate (ADD)
Count: 2 ad groups
Service: AdgroupAdService
2
Operation: get
Count: 100 targeting ideas
Service: TargetingIdeaService
1
Operation: HTTP POST
Count: 1 report
Service: AdHoc reports download
0
Operation: mutate (ADD)
Count: 10 campaigns
Service: MutateJobService
10
How can I find out what my API usage is, and whether I should apply for standard access?

AdWords API InfoService data will have only historical usage data, once API pricing is retired. So you will need to monitor API usage from your application logs on the client side to determine if you need basic or standard access.

When should I apply for standard access?

If you did not apply for standard access before February 28, 2013, you were defaulted to basic access. If you expect your usage to increase beyond this limit in the future, you should apply for standard access at a minimum 3 weeks ahead of time, and include as much details as possible in your application to ensure timely processing of your request.

How long does it take for standard access to be approved?

If all the details you provided on the standard access form are accurate and any follow-up clarification questions are responded to promptly, we expect to complete the review in about two weeks.

What are some of the common reasons standard access approval may be delayed or not granted?

Some of the common reasons for delayed approvals are:

  • Incomplete details provided on the standard access application
  • Inaccurate contact details in the MCC account that is associated with the AdWords API developer token
  • Not responding to follow-up questions and clarifications by the AdWords API support team
  • Using the API in ways inconsistent with the AdWords API terms and conditions
  • Not implementing the Required Minimum Functionality
  • Current AdWords API usage is very low and does not yet justify standard access

Do we need to re-apply for standard access at any time?

If the information you provided in the original standard access application changed or if the AdWords API support team requests you to do so, you need to update your details using the standard access application form.

For example, if you were an advertiser for a single website but would now like to advertise on behalf of multiple clients, or, if your tool had previously offered only reporting functionality and you would now like to implement creation and management of campaigns, then you will need to provide the updated details via the standard access form.

With API usage being free, do we still need to provide billing details when applying for the AdWords API token?

We are not making any changes to the API token application process so billing information, as well as other details like contact info, are still required for API token application. However, there will be no charge for API usage under either basic or standard access.

Back to top


API Versioning

How can I tell what the latest version number is?

The version number is part of the WSDL access URL. In the Developer's Guide documentation, the version number appears in the Release Notes and Reference pages.

How long will older versions of the AdWords API WSDL be available?

Once a version of the WSDL has been replaced by an updated version, the older version will be supported for four months to allow time for users to migrate to the newer version. During this period, AdWords API will continue to provide developer access to and support for any version dating back four months. Version-related documentation can be found in the Release Notes and Sunset Schedule.

How do I access older versions of the WSDL?

As long as a version is available, the WSDL version number will be included in the WSDL access URL.

What happens when newer releases eliminate functions still featured in supported earlier versions?

When new versions eliminate or alter functionality available in previous (still available) releases, the Release Notes will annotate changes and a blog post will explain updates to newly released versions. We also provide a migration guide to help you upgrade.

To allow developers time to migrate to new versions, old releases and documentation will remain available and updated for four months after a new release.

Back to top


Technical Questions

How do I debug and diagnose SOAP messages in my application?

We recommend you use one of our client libraries to build your application rather than roll your own SOAP.

Are the IDs returned via the API unique?

Keyword and creative IDs are unique only within their ad group, while ad group and campaign IDs are globally unique. For more details, see the Working with Objects guide.

Which web services technologies do you use / support?

We use SOAP 1.1 and WSDL 1.1. All messages are sent via SSL (https) to protect our user's privacy, and are authenticated via embedded passwords. We do not currently use any of the higher-level WS-* specifications.

Our goal is to be interoperable with SOAP toolkits in any customer development environment. Currently we offer client libraries in Java, PHP, Python, .NET, Perl, and Ruby.

What is an operation?

An operation is defined as an action taken upon your AdWords account.

A single get request counts as one operation, regardless of the number of ad groups (or other objects) it affects. For a mutate, each operation contained within is counted once. Similarly, in a bulk mutate job, each operation is counted separately.

Visit our API rate sheet for more information about API operations.

When should I reset my Developer Token?

Almost never. The only time you should reset your Developer Token is in rare cases when you believe that it's been stolen or is being compromised. You should treat your Developer Token with at least the same level of security that you treat your account log-in and password information.

What happens when I reset my Developer Token?

It will be deleted and removed from our database. You cannot refresh your Developer Token once you reset it, so you should be sure if you decide to do so.

Where do I report bugs?

You can email any suspected bugs via our support page. Please include as much information as possible, including a screenshot or example of the bug. Because support is somewhat limited for the AdWords API, please use this email address to report bugs only. You can send general developer comments through our Developer's Forum.

Back to top

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.