Register for one of our Google Ads API Migration Workshops (October 5, 2021 - October 14, 2021)

Client Libraries

Our client libraries provide high-level views and basic building blocks of Google Ads API functionality, making it easier to develop apps quickly. We recommend starting out with one if you're new to the API.

Client library Source Distribution Code examples
Java google-ads-java Maven, tar.gz View on GitHub
.NET google-ads-dotnet tar.gz, zip View on GitHub
PHP google-ads-php tar.gz View on GitHub
Python google-ads-python tar.gz, zip View on GitHub
Ruby google-ads-ruby gem, tar.gz, zip View on GitHub
Perl google-ads-perl tar.gz, zip View on GitHub

Configuration

Each Ads API Client library provides different configuration settings and loading methods that you can use to customize its behavior.

Here are the environment variables that are common to all client libraries and that can be loaded to set configuration settings:

  • Client library
    • GOOGLE_ADS_CONFIGURATION_FILE_PATH: Path to the configuration file.
  • OAuth2
    • Application Mode
      • GOOGLE_ADS_CLIENT_ID : Set this value to your OAuth2 client ID.
      • GOOGLE_ADS_CLIENT_SECRET : Set this value to your OAuth2 client secret.
      • GOOGLE_ADS_REFRESH_TOKEN : Set this value to a pre-generated OAuth2 refresh token if you want to reuse OAuth2 tokens. This setting is optional.
    • Service Account Mode
      • GOOGLE_ADS_JSON_KEY_FILE_PATH : Set this value to the OAuth2 JSON configuration file path.
      • GOOGLE_ADS_IMPERSONATED_EMAIL : Set this value to the email address of the account you are impersonating.
  • Google Ads API
    • GOOGLE_ADS_DEVELOPER_TOKEN : Set this to your developer token.
    • GOOGLE_ADS_LOGIN_CUSTOMER_ID : This is the customer ID of the authorized customer to use in the request, without hyphens (-).
    • GOOGLE_ADS_LINKED_CUSTOMER_ID : This header is only required for methods that update the resources of an entity when permissioned through Linked Accounts in the Google Ads UI (AccountLink resource in the Google Ads API). Set this value to the customer ID of the data provider that updates the resources of the specified customer ID. It should be set without hyphens (-). To learn more about Linked Accounts, visit the Help Center.

Environment variables are commonly defined in a bash configuration file such as a .bashrc or .bash_profile file located in the $HOME directory. They can also be defined using the command line.

Here are some basic steps to define an environment variable using a .bashrc file using a terminal:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc

# Update your bash environment to use the most recently updated
# version of your .bashrc file.
src ~/.bashrc

Environment variables can also be set in your terminal instance directly from the command line:

export GOOGLE_ADS_CLIENT_ID=1234567890

Another alternative is to set environment variables when calling the command that uses them:

GOOGLE_ADS_CLIENT_ID=1234567890 php /path/to/script/that/uses/envvar.php

Diagnostic tool

Google Ads Doctor analyzes your client library environment by

  • verifying your OAuth2 credentials with Google Ads API.
  • guiding you through fixing any OAuth2 problems in your configuration file.

Follow these steps to download the command-line tool for diagnosing your issues immediately:

Linux (64-bit)

    git clone https://github.com/googleads/google-ads-doctor.git
    cd google-ads-doctor/oauthdoctor/bin/linux/amd64
    ./oauthdoctor -language [java|dotnet|php|python|ruby] \
      -oauthtype [web|installed_app|service_account] \
      -configpath [/my/config/file/path] \
      -verbose

Windows (64-bit)

    git clone https://github.com/googleads/google-ads-doctor.git
    cd google-ads-doctor/oauthdoctor/bin/windows/amd64
    ./oauthdoctor.exe -language [java|dotnet|php|python|ruby] \
      -oauthtype [web|installed_app|service_account] \
      -configpath [/my/config/file/path] \
      -verbose

Mac OS X (64-bit)

    git clone https://github.com/googleads/google-ads-doctor.git
    cd google-ads-doctor/oauthdoctor/bin/darwin/amd64
    ./oauthdoctor -language [java|dotnet|php|python|ruby] \
      -oauthtype [web|installed_app|service_account] \
      -configpath [/my/config/file/path] \
      -verbose

Linux (32-bit)

    git clone https://github.com/googleads/google-ads-doctor.git
    cd google-ads-doctor/oauthdoctor/bin/linux/386
    ./oauthdoctor -language [java|dotnet|php|python|ruby] \
      -oauthtype [web|installed_app|service_account] \
      -configpath [/my/config/file/path] \
      -verbose

Windows (32-bit)

    git clone https://github.com/googleads/google-ads-doctor.git
    cd google-ads-doctor/oauthdoctor/bin/windows/386
    ./oauthdoctor.exe -language [java|dotnet|php|python|ruby] \
      -oauthtype [web|installed_app|service_account] \
      -configpath [/my/config/file/path] \
      -verbose

Mac OS X (32-bit)

    git clone https://github.com/googleads/google-ads-doctor.git
    cd google-ads-doctor/oauthdoctor/bin/darwin/386
    ./oauthdoctor -language [java|dotnet|php|python|ruby] \
      -oauthtype [web|installed_app|service_account] \
      -configpath [/my/config/file/path] \
      -verbose

To get additional options with the tool, you either read the README or run this command:

Linux / Mac OS X

    ./oauthdoctor -help

Windows

    ./oauthdoctor.exe -help

Code examples

Check out our code examples of some common functions in the Google Ads API.