New to the AdWords API? There're a lot of documents to go through, and it's not always clear what steps you need to take, or what step you missed if something's not working. This guide covers everything you need to know to go from a novice to successfully making your first API request, including explanations of commonly confusing API concepts.
If all you want to do is get the API set up as fast as possible, here are the steps you need to follow:
- Create a test manager (formerly known as "MCC") account and a linked AdWords test account. Follow these instructions on how to set up the link.
- Create a manager account.
- Sign up for a Developer Token.
- Set up a client ID and client secret for an installed application.
- Select the client library in your preferred language, and follow its installation instructions.
- Generate a refresh token. Instructions can also be found in each of our supported languages: Java, DotNet, PHP, Python, Ruby, Perl.
- Run the Add Campaigns example, and then the Get Campaigns example from the Basic Operations folder of your client library's examples. This will add some campaigns to your account and then fetch some basic information from the API to confirm that it worked. You can also verify the results of the add operation with the web interface.
Now we'll cover each step in more detail. Let's start by introducing some terms and concepts.
In order to use the AdWords API, you're going to need multiple AdWords accounts. Here, we're going to set up a minimal set of accounts you'll need to complete this guide and get started.
Manager vs. client account
Before creating any accounts, it's important to understand the different types of accounts and how they are related.
- There are two types of AdWords accounts: client accounts and manager accounts.
- Client accounts are what you would typically think of as an AdWords account. They can include campaigns, budgets, ad groups, ads, etc.
- Manager accounts are organizational accounts. They are used to manage groupings of client accounts but cannot themselves contain campaigns, budgets, ad groups or ads.
AdWords accounts exist in a hierarchy:
Only manager accounts may have children, which could either be client accounts or other manager accounts. Manager accounts exist to add a logical grouping to other accounts. Manager accounts themselves cannot include actual data like campaigns or ads--that's what client accounts are for. Client accounts, which appear in the diagram as leaf nodes, are able to include campaigns, ads, etc.
Someone with access to a higher level account is able to manage all accounts underneath it. In the above diagram, a user authenticated as Manager 1 would be able to access all accounts. However, someone authenticated as Manager 2 would only have access to Client Account 2 and Client Account 3.
When using the API, the simplest approach is to authenticate as a manager account. This has to be done using OAuth 2.0, which is detailed below. Once you're authenticated, you are granted access to all accounts under that manager account.
The first step of setting up API access is to make sure you have all the necessary accounts, and that they're linked properly. For this tutorial, you need at least one client account, one manager account, and a link between them so that authentication as the manager grants access to the client account.
Manager and client accounts are useful for organizing, but what about testing experimental changes or testing API calls while you are developing? That's what test accounts are for. Test accounts still exist in a hierarchy like manager accounts, and can be organized the same way, but also have extra benefits for use during active development.
- Test accounts can be used as you develop and debug your application without affecting your real campaign or ads. They can't serve ads or interact with your production accounts.
- Test accounts can be used to develop your application even before you're approved to use the API.
- Test accounts are fully available on the web interface as well, just like normal accounts.
While the accounts you set up in the previous step are going to be useful when you get up and running with your full software, you may not want to use your real production accounts for testing your software as you're building it.
Test accounts allow you to set up an AdWords account structure and individual accounts just like regular, production AdWords accounts. The main difference is that ads in test accounts are not going to be served no matter what API calls you make. The advantage here is that you can make any changes you like with no risk; you can try out a new API implementation or account configuration, making changes until you get it the way you want, and then do it the right way the first time on your production account.
Test accounts and production accounts cannot interact in any way. You cannot create a test account under your existing production manager; you will need an entirely new hierarchy in order to make use of test accounts.
Additionally, you can start using the AdWords API with test accounts right away. Using the AdWords API with your production account will require you to go through an approval process, which will be detailed below.
Now that we have all the accounts we need, it's time to start getting into the API-specific steps. The first thing you should do is apply for your developer token.
- Developer tokens indicate that your company is approved to use the AdWords API.
- Developer tokens can be used with any AdWords account, regardless of which manager account was used to apply for it.
- A developer token is a sensitive credential, so make sure to store it securely, and do not share it on public forums or any third parties.
The developer token is requested via your production manager account, not your test manager account. However, using that developer token does not imply that you are acting on behalf of that manager account, nor is that developer token restricted for usage only with that manager account. The manager account is simply the means by which you get the developer token.
Having an approved developer token indicates that you are allowed to use the AdWords API. In order to authenticate as a specific manager account, you will still need to set up OAuth 2.0 credentials.
You can use your developer token to make API calls for test accounts right away, as soon as you've requested it. However, you will need to wait until the token is fully approved before you can use it on your production accounts.
The AdWords API uses OAuth 2.0 for authorization. There are quite a few steps to getting this set up the first time, but after the initial setup, everything will be automatic. In the first step, you will need to set up a client ID and client secret. Later, you will use these to let a user of an AdWords account grant access to your application in the form of a refresh token. That refresh token will allow you to authenticate as that AdWords account when making API calls.
Google Developers Console
In order to authenticate as a specific account and use the API, there's some initial setup you need to do so that account owners know what application they're allowing to access their account.
- Your client ID and client secret identify your specific application.
- You only need one client ID and secret for your application. You can use the same client ID and secret to obtain OAuth credentials for multiple AdWords users.
Before you can authenticate as a specific account, you have to register your application on the Google Developers Console. To authenticate using OAuth 2.0, you need a user of the account you want to authenticate as to grant access to your application. This step will help you configure your application, and then in a later step, we will be granting your application access to a specific manager account.
In order to allow the user of the AdWords account to grant access to your application, you need two pieces of information: the client ID and the client secret. The client ID identifies your application, and is public information. The client secret is private information, shared only between you and the Google server. Providing it indicates that you are actually the owner of that application, like using a password.
When setting up your client ID and client secret, you should be logged into a developer Google account. This account should be owned by the person maintaining the application, and is not necessarily related to any of your AdWords accounts. This process is completely separate from obtaining a developer token. Multiple different applications can use the same developer token, as long as they belong to the same developer. You generally want to set up a new client ID and client secret for each application you develop.
Note that this guide assumes that you will be using an installed application flow. However, the differences between the two options are detailed below.
Installed vs. web application
One of the main points of potential confusion comes in determining whether you want to choose an installed application (sometimes called a native application) or a web application when generating your client ID and client secret.
- Web application flow allows for callback URLs; installed application flow does not.
- The installed application flow is recommended because it is simpler to implement.
- Web application flow lets you easily generate multiple authorization credentials, which can be useful for situations like managing third party accounts.
In order to authenticate as an AdWords account, you need a valid refresh token, which is generated using all the OAuth 2.0 pieces you're setting up now. The decision between installed application and web application determines how you will go about getting the refresh token so that you can authenticate as the account you need.
Just because your application may be running in a web server does not necessarily mean that you will be using a web application flow for OAuth 2.0. The main difference is whether or not you require a callback to your website after issuing the token. In either case, the user who is granting permission for your application is going to have to visit a Google webpage and click on a button indicating that he agrees that your application can have access to their account.
An installed application flow is used when the application manages the same set of AdWords accounts, with multiple users. You can generate a refresh token once, during development, and never have to grant permissions again.
Conversely, a web application flow is used when you have a generic web application that can access any account, based on its user. When the user logs in, it's a better user experience to have your web application automatically authenticate, rather than having the user copy and paste their authentication code into your application.
It's generally more common for applications using the AdWords API to have an installed application flow; however, your specific implementation details may vary. The steps later in this guide will assume that you are using the installed application flow when setting up the client libraries.
At this point, you're not quite done setting up your OAuth 2.0 authentication yet; you still need a refresh token. However, the client library will make generating the refresh token easier, so we'll take the time to set that up now.
The AdWords client libraries are provided for your convenience, to save you the time and development effort.
- The AdWords client libraries handle the SOAP and OAuth 2.0 protocols for you, allowing you to focus on business logic.
- Client libraries also provide additional utilities like reporting interfaces and shopping partitioning tools.
The AdWords API uses SOAP as the protocol for transferring information. SOAP can be difficult to integrate with, so in order to make it easier to use the API, we have built and maintain client libraries in some popular languages that will handle all of the SOAP aspects for you. This way, you can write code in your language of choice using the library, using idiomatic code for that language.
This comes with other benefits as well. Many client libraries come with additional utilities to make certain tasks easier, like running reports or interacting with shopping campaigns. The client library also handles the details of authenticating with OAuth 2.0, and we release newly updated versions of the libraries with each major AdWords release to account for new features and changes to the API.
Part of setting up your client library includes putting important information into a configuration file. The name and format of the file change depending on the specific library you choose, but the information you put into the file is the same.
The information you need to include in the configuration file is:
- Developer token
- Client ID
- Client secret
- Client customer ID (this is a 10-digit ID in the form of 123-456-7890; for this tutorial, make sure that this is your test client account's ID)
- Refresh token (if you do not have this piece of information yet, it will be generated in the next step)
Remember, if your developer token is not approved, you will only be able to make API calls against test accounts. This means that you should put your test client account's ID in the client customer ID field in the configuration file. If you're managing more than one account, you can leave this out of the configuration file and specify it at runtime using your client library, but this guide will assume that you're only making calls against one account.
Now that the client library is set up, we can generate the last piece required to authenticate as the manager account: the refresh token.
- The refresh token authenticates you as a specific AdWords account user.
- The client library can handle generating your refresh token and access tokens.
The refresh token is the last piece of the OAuth 2.0 setup. The refresh token represents the fact that a user of an account authorized a specific application to perform specific kinds of actions on that account. In this case, the user of a manager account is going to authorize that your application (which you set up in the Google Developer Console in previous steps) is allowed to make changes to and see the status of all of the accounts in that manager account's hierarchy.
You could grant this access on any AdWords account, either a manager account or a client account. Generally, it's most useful to grant the refresh token at the highest level manager account, so that you can have access to all accounts underneath it. If you grant access at a lower level, you may need to generate multiple refresh tokens for different accounts. The process of generating a refresh token doesn't use the Customer ID you set up in your configuration file. Instead, the user generating the token must visit a specific web link in a browser while logged into the account where they want to grant access.
The generated refresh token doesn't expire as long as you continue to use it. Additionally, refresh tokens can be manually revoked at any time, immediately cutting off access by anyone who was using that refresh token. See the support site for information on what this access means. That page includes a link to see all apps that have access to your account, including the ability to revoke access.
In order to make a request against the API, however, an access token is needed. The access token can be generated by providing a refresh token, and will expire after one hour. Each of our client libraries automatically handles the process of fetching access tokens and refreshing them once they expire. This idea is described here for completeness, but you shouldn't have to worry about it under normal circumstances.
Each client library includes a piece of code that, when run, will be able to take the information you set up in your configuration file or passed in via the command line and use that to guide you through the process of generating a refresh token.
Client library examples
Now, everything is set up, and the last step is to run some code to see the API in action.
- The examples in the client library are fully functional and can be run with minimal modifications.
- Use examples as a reference when writing new code.
Each client library comes complete with code examples that show how to perform various tasks in that library. These examples cover many of the features of the API, but are not exhaustive. They are meant to serve as references when writing your own code, but they are also able to execute on their own to perform these basic tasks.
In order to get an idea of how the API works, it can be advantageous to run a few examples and inspect the results on the web interface. API updates will be reflected on the web interface immediately after a refresh, if such a feature is available on the web interface.
You can find a link to the examples for your library from the client
The best place to start is in the basic operations folder. As long as the
configuration file for your client library is set up properly, there should be
no additional configuration needed to run the two most simple examples:
GetCampaigns. Make sure that you're using your test client
account's customer ID for now.
For many other examples, you will need to provide IDs of existing entities in
your account. For example, to run the
AddAdGroups example, you will need to
modify the file to specify the ID of the campaign in which you want the new ad
groups to reside.
From here, you may want to try running some of the more complicated examples, or maybe you want to dive right into writing your own custom app for integrating with the API.
Here are some guides that cover some of the basics of how the API works:
- Basic Concepts - Technical concepts about how to use the API in detail.
- AdWords API Objects - How the API is set up: what a service is, what the various methods mean, how data is represented, etc.
- Services & Use Cases - Information on every available service and its purpose.
- Reporting Basics - You can also see an example of how to run a report request in your client library in the "reporting" folder.