Register for one of our AdWords API workshops (30 August - 16 September).

Make Your First API Call

In this guide we’re going to get you to your first API call, breaking it down step by step. This will open the door to take full advantage of the AdWords API.

The video uses Java and Eclipse, but you can use the language and client library of your choice - the concepts are similar, and instructions are provided below for all supported languages.

Overview of the process

You set up API access by obtaining a few required authentication credentials, creating some test accounts, and adding the authentication and account details to a configuration file for your client library.

Once the config file is set up, you're ready to make calls against the API.

There are six main steps to get going:

  1. Request a developer token.
  2. Create test accounts.
  3. Get a client library.
  4. Set up authentication via OAuth2.
  5. Get an OAuth2 refresh token and configure your client.
  6. Make your first API call.

Each step is described in the sections below.

Request a developer token

A developer token from Google allows your app to connect to the AdWords API. To request a developer token, perform the steps in the Sign Up guide (if you haven't already). After signing up, you'll receive a developer token that is pending approval.

Your pending developer token must be approved before using it with production AdWords accounts.

Create test accounts

Perform the following steps to create a test manager account, a test client account, and a few campaigns to populate the test client account.

  1. Go to the AdWords manager accounts page and create a test manager account.
  2. Use the AdWords web interface to create a test client account under the test manager account you created above. While logged in to AdWords as your test manager account, any client accounts you create will automatically be test accounts.
  3. Create a few test campaigns under the test client account in the AdWords web interface.
  4. Take note of the client customer ID for the new test client account, and save it: You'll add this to your config file later. The client customer ID is shown below.

Use the developer token of your production manager account when making requests against the test manager account. Even if it’s not approved yet, the token will still work on test accounts, including the ones you just created.

Get a client library

The client libraries handle all the backend API calls for you, and expose friendly objects to work with, including code samples for practically every common API task.

If you're an experienced developer, you probably already have your development environment set up the way you want it. If not, we'll walk through the recommended setup for the client libraries now.

Click the tab below for the language you're using, and follow the instructions.

Java

  1. Refer to the Getting Started section of the Java client library README file in GitHub to download and install the AdWords API client library for Java.
  2. Return to this page prior to performing the OAuth2 steps: We'll set up the OAuth2 credentials in the next step below.

.NET

  1. Refer to the Getting Started section of the .NET client library README file to download and install the AdWords API client library for either CSharp or Visual Basic.
  2. Return to this page prior to performing the OAuth2 steps: We'll set up the OAuth2 credentials in the next step below.

Python

  1. Refer to the Getting Started section of the Python client library README file to download and install the AdWords API client library for Python.
  2. Return to this page prior to performing the OAuth2 steps: We'll set up the OAuth2 credentials in the next step below.

PHP

  1. Refer to the Getting Started section of the PHP client library README file to download and install the AdWords API client library for PHP.
  2. Return to this page prior to performing the OAuth2 steps: We'll set up the OAuth2 credentials in the next step below.

Perl

  1. Refer to the Getting Started section of the Perl client library README file to download and install the AdWords API client library for Perl.
  2. Return to this page prior to performing the OAuth2 steps: We'll set up the OAuth2 credentials in the next step below.

Ruby

  1. Refer to the Getting Started section of the Ruby client library README file to download and install the AdWords API client library for Ruby.
  2. Return to this page prior to performing the OAuth2 steps: We'll set up the OAuth2 credentials in the next step below.

Set up OAuth2 authentication

Your app will need to access user data and contact other Google services on your behalf. Authentication via OAuth2 allows your app to operate on behalf of your account.

To enable your app to access the API, you need an OAuth2 client ID and client secret.

  1. While logged in with your manager account credentials, open the Google API Console Credentials page.
  2. From the project drop-down, choose Create a new project, enter a name for the project, and click Create.
  3. Select Create credentials and choose OAuth client ID.
  4. You may be prompted to set a product name on the Consent screen; if so, click Configure Consent Screen, supply the requested information, and click Save to return to the Credentials screen.
  5. Under Application type, choose Other for this tutorial. Enter a name in the space provided.
  6. Click Create. The OAuth2 client ID and client secret appear. Copy and save these items. You will add them to your configuration file in the next step.

Get an OAuth2 refresh token and configure your client

Because OAuth2 access expires after a limited time, an OAuth2 refresh token is used to automatically renew OAuth2 access.

Click the tab for the programming language you're using, and follow the instructions to generate an OAuth2 refresh token, and set up the configuration file for your client.

Java

  1. Follow these instructions in GitHub to get an OAuth2 refresh token and configure the client library.
  2. Return to this page when you're done. After completing the steps, your ads.properties file should have all you need to make test API calls, and should contain values similar to the following:
[...]
api.adwords.developerToken=123axxxxxxxxxxxxxxxxxx
api.adwords.clientId=xxxxxxxxxx.apps.googleusercontent.com
api.adwords.clientSecret=zZxxxxxTxxxxxxxxxxx
api.adwords.clientCustomerId=123-456-7890
api.adwords.refreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
api.adwords.userAgent=Company_Name
[...]

.NET

  1. Follow these instructions in GitHub to get an OAuth2 refresh token and configure the client library.
  2. Return to this page when you're done. After completing the steps, your app.config file should have all you need to make test API calls, and should contain values similar to the following:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="AdWordsApi"
        type="System.Configuration.DictionarySectionHandler"/>
  </configSections>
  <AdWordsApi>
    <!-- Settings specific to AdWords API.-->
    <add key="UserAgent" value="My AdWords API application"/>
    <add key="DeveloperToken" value="xxxxxxxxxxxxxxxxxxxxxx"/>
    <add key="ClientCustomerId" value="123-456-7890"/>

    <!-- OAuth2 configuration -->
    <add key="AuthorizationMethod" value="OAuth2" />
    <add key="OAuth2ClientId" value="xxxxxxxxxx.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="zZxxxxxTxxxxxxxxxxx" />
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2RefreshToken" value="1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxx" />
  </AdWordsApi>
</configuration>

Python

  1. Follow these instructions in GitHub to get an OAuth2 refresh token and configure the client library.
  2. Return to this page when you're done. After completing the steps, your googleads.yaml config file should have all you need to make test API calls, and should contain values similar to the following:
adwords:
  developer_token: 123axxxxxxxxxxxxxxxxxx
  user_agent: Company_Name
  client_customer_id: 123-456-7890
  client_id: xxxxxxxxxx.apps.googleusercontent.com
  client_secret: zZxxxxxTxxxxxxxxxxx
  refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

PHP

  1. Follow these instructions in GitHub to get an OAuth2 refresh token and configure the client library.
  2. Return to this page when you're done. After completing the steps, your auth.ini config file should have all you need to make test API calls, and should contain values similar to the following:
[...]
developerToken = 123axxxxxxxxxxxxxxxxxx
userAgent = Company_Name
clientCustomerId = 123-456-7890
client_id = xxxxxxxxxx.apps.googleusercontent.com
client_secret = zZxxxxxTxxxxxxxxxxx
refresh_token = 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Perl

  1. Follow these instructions in GitHub to get an OAuth2 refresh token and configure the client library.
  2. Return to this page when you're done. After completing the steps, your adwords.properties config file should have all you need to make test API calls, and should contain values similar to the following:
[...]
userAgent = Company_Name
developerToken=123axxxxxxxxxxxxxxxxxx
clientId=123-456-7890
oAuth2ClientId=xxxxxxxxxx.apps.googleusercontent.com
oAuth2ClientSecret=zZxxxxxTxxxxxxxxxxx
oAuth2RefreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Ruby

  1. Follow these instructions in GitHub to get an OAuth2 refresh token and configure the client library.
  2. Return to this page when you're done. After completing the steps, your adwords_api.yml config file should have all you need to make test API calls, and should contain values similar to the following:
[...]
:oauth2_client_id: xxxxxxxxxx.apps.googleusercontent.com
:oauth2_client_secret: zZxxxxxTxxxxxxxxxxx
:refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
:developer_token: 123axxxxxxxxxxxxxxxxxx
:client_customer_id: 123-456-7890
:user_agent: Company_Name
[...]

Make your first API call

Now that your environment and config file are all set up, it's time to make your first API call:

Java

  1. In your IDE, open GetCampaigns.java and execute it.
  2. The console should print a listing of the test campaigns you added to your test account above.

.NET

  1. In your IDE, open GetCampaigns.cs, or GetCampaigns.vb, and execute it.
  2. The console should print a listing of the test campaigns you added to your test account above.

Python

  1. In your IDE, open get_campaigns.py and execute it.
  2. The console should print a listing of the test campaigns you added to your test account above.

PHP

  1. In your IDE, open GetCampaigns.php and execute it.
  2. The console should print a listing of the test campaigns you added to your test account above.

Perl

  1. In your IDE, open get_campaigns.pl and execute it.
  2. The console should print a listing of the test campaigns you added to your test account above.

Ruby

  1. On the command line, execute get_campaigns.rb by typing:
    ruby get_campaigns.rb
  2. The console should print a listing of the test campaigns you added to your test account above.

Congratulations, you've now made your first AdWords API call.

We've covered a lot of ground in this section. In the next section, we'll review and look in more detail at some of the configuration ingredients we worked with in this part.

Reviewing the configuration ingredients

In the previous section, we got you all set up to make your first API call.

In this section, we'll recap and look in more detail at the application configuration ingredients we used to make a call against the AdWords API.

Test vs. production accounts

In the previous section you created a test manager account, and a test client account.

Test accounts are a useful way to experiment with the API, because they won’t affect your live ads, or charge your account. They're also great for playing with the AdWords web interface without consequences.

When signed in to the AdWords web interface, the bright red test account label reminds you that you're in a test account:

Because test accounts don't serve any actual ads, impressions or cost data will often be zeroed out in reports or API calls.

For more information on test accounts, production accounts, and setting up an account hierarchy, see Managing Accounts.

Configuration ingredients

Because we’re using a client library, we won’t go into the back-end details about how API calls are made. But if you want to know more about SOAP, OAuth2, and the other plumbing that makes these calls work, see API Call Structure

Even when using the client libraries, there are some ingredients you'll always need: We set them up together above, but let's review and explain them a bit more now.

Developer token

The developer token identifies your app to the AdWords API. Only approved tokens can connect to the API for production AdWords accounts; pending tokens can connect only to test accounts. Once your token is approved, you can use the same token for requests against all your AdWords accounts, even if they're not linked to the manager account associated with the developer token.

See Managing Accounts for more details.

OAuth2 client ID and client secret

These map your client application to a project in the Google Developers Console, and are used for OAuth2 authentication, which allows your app to operate on behalf of your account.

See OAuth2 Authentication for more details.

OAuth2 access and refresh tokens

Before your application can access private data using the API, it must obtain an OAuth2 access token that grants access to the API.

If you're using the client libraries, the OAuth2 access token is automatically taken care of for you. Otherwise, see the API call example in the API Call Structure guide for details on how to generate an access token.

OAuth2 access tokens expire after a limited time. For this reason, the client libraries use the OAuth2 refresh token to automatically regenerate the OAuth2 access token.

You created the refresh token in the steps above by means of a utility in the client library.

For more information on using OAuth2 with Google APIs see OAuth2 Authentication and the OAuth2 Identity Platform documentation.

Client customer ID

The client customer ID is the account number of the AdWords client account you want to manage via the API, usually in the form 123-456-7890.

Optionally, the client customer ID can be left out of the config file and set programatically. Once your developer token is approved, you can use a client customer ID from a production account, instead of a test account.

See Code Samples and Use Cases for more information.

Next steps

Now you understand all the ingredients needed for your first API app. In the next guide, Code Samples and Use Cases, we'll look at how the client libraries and code samples can get you started with custom reporting and automation.

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.