Google Ads

Make Your First API Call  |  AdWords API  |  Google Developers

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.
Here are the 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.

Request a developer token

A developer token from Google allows your app to connect to the AdWords
API. If you haven’t already, perform the steps in the Sign Up
guide
to obtain a developer token. 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
Google Ads 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 Google Ads manager accounts
    page
    and
    create a test manager account.
  2. Use the Google Ads UI to create a test client account under the
    test manager account you created above. While logged in to Google Ads 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 Google Ads UI.
  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.

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.

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. Click Select a project, then NEW PROJECT, and 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:

    
    
      
        

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 adsapi_php.ini
    config file should have all you need to make test API calls, for example:

    developerToken = "123axxxxxxxxxxxxxxxxxx"
    clientCustomerId = "123-456-7890"
    
    userAgent = "Company_Name"
    
    clientId = "xxxxxxxxxx.apps.googleusercontent.com"
    clientSecret = "zZxxxxxTxxxxxxxxxxx"
    refreshToken = "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:

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 Google Ads UI without consequences.

When signed in to the Google Ads UI, 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 Google Ads 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 Google Ads accounts, even if they’re
not linked to the manager account associated with the developer token.

You can retrieve your developer token by
signing in to your manager account then going to the
AdWords API Center page (Tool icon > SETUP > API Center).

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 Google Ads client account you
want to manage via the API, usually in the form 123-456-7890.

Previous

New

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

Next steps

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

3 Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button
Close