Make an API call

This guide requires several prerequisite settings that were configured in previous steps. Start with Introduction if you haven't done so.

This guide also uses refresh tokens, a workflow where a user with sufficient access to the Google Ads account can authorize your app, in a one-time setup, to make offline API calls to the account without any further user intervention. You can use refresh tokens to build both offline workflows, such as cron jobs or data pipelines, and interactive workflows, such as web or mobile apps.

Fetch a refresh token

The Google Ads API uses OAuth 2.0 as the authorization mechanism. By default, OAuth 2.0 authentication issues an access token that expires after a limited time. To renew the access token automatically, issue a refresh token instead.

oauth2l

Generate the refresh token by running the oauth2l tool:

oauth2l fetch --credentials credentials.json --scope adwords \
    --output_format refresh_token

The credentials.json file is from a previous step.

The oauth2l command opens a Google Account login window in a new browser window and takes you through the OAuth 2.0 authentication steps.

Make sure you sign in using the email address from the step where you identified your login customer ID.

If your app is unverified, you might see a warning screen. In such cases, it's safe to click the Show Advanced link and click the Go to PROJECT_NAME (unverified) option.

After you verify the scopes, grant the permission by clicking the Continue button.

A prompt is displayed in the browser with the following text:

Authorization code granted. Close this tab.

The oauth2l command outputs the following JSON snippet:

{
  "client_id": "******.apps.googleusercontent.com",
  "client_secret": "******",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "refresh_token": "******",
  "type": "authorized_user"
}

gcloud CLI

Generate the refresh token by running the gcloud CLI tool:

gcloud auth application-default \
  login --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=<path_to_credentials.json>

The credentials.json file is from a previous step.

The gcloud command opens a Google Account login window in a new browser window and takes you through the OAuth 2.0 authentication steps.

Make sure you sign in using the email address from the step where you identified your login customer ID.

If your app is unverified, you might see a warning screen. In such cases, it's safe to click the Show Advanced link and click the Go to PROJECT_NAME (unverified) option.

After you verify the scopes, click the Continue button to grant permission.

The browser navigates to https://cloud.google.com/sdk/auth_success, indicating that the authentication was successful.

Authorization code granted. Close this tab.

The gcloud command prints an output like follows:

Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]

Now open the application_default_credentials.json file. Its contents should be similar to follows:

{
  "account": "",
  "client_id": "******.apps.googleusercontent.com",
  "client_secret": "******",
  "refresh_token": "******",
  "type": "authorized_user",
  "universe_domain": "googleapis.com"
}

Others

If you prefer to use curl or your own HTTP client instead, refer to the OAuth 2.0 for Mobile and Desktop Apps guide for an example.

Make an API call

Select your client of choice for instructions on how to make an API call:

Java

The client library artifacts are published to the Maven central repository. Add the client library as a dependency to your project as follows:

The Maven dependency is:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>34.0.0</version>
</dependency>

The Gradle dependency is:

implementation 'com.google.api-ads:google-ads:34.0.0'

Create a file ~/ads.properties with the following content:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Create a GoogleAdsClient object as follows:

GoogleAdsClient googleAdsClient = null;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
  System.err.printf(
      "Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
      fnfe);
  System.exit(1);
} catch (IOException ioe) {
  System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
  System.exit(1);
}

Next, run a campaign report using the GoogleAdsService.SearchStream method to retrieve the campaigns in your account. This guide doesn't cover the details of reporting.

    private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(query)
            .build();

    // Creates and issues a search Google Ads stream request that will retrieve all campaigns.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates through and prints all of the results in the stream response.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        System.out.printf(
            "Campaign with ID %d and name '%s' was found.%n",
            googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
      }
    }
  }
}GetCampaigns.java

C#

The client library packages are published to the Nuget.org repository. Start by adding a nuget reference to Google.Ads.GoogleAds package.

dotnet add package Google.Ads.GoogleAds --version 18.1.0

Create a GoogleAdsConfig object with the relevant settings, and use it to create a GoogleAdsClient object.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = "APPLICATION",
    OAuth2ClientId = "******.apps.googleusercontent.com",
    OAuth2ClientSecret = "******",
    OAuth2RefreshToken = "******",
    LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);

Next, run a campaign report using the GoogleAdsService.SearchStream method to retrieve the campaigns in your account. This guide doesn't cover the details of reporting.

    public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V18.GoogleAdsService);

    // Create a query that will retrieve all campaigns.
    string query = @"SELECT
                    campaign.id,
                    campaign.name,
                    campaign.network_settings.target_content_network
                FROM campaign
                ORDER BY campaign.id";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}GetCampaigns.cs

PHP

The client library packages are published to the Packagist repository. Change into the root directory of your project and run the following command to install the library and all its dependencies in the vendor/ directory of your project's root directory.

composer require googleads/google-ads-php:25.0.0

Make a copy of the google_ads_php.ini file from the GitHub repository and modify it to include your credentials.

[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

Create an instance of GoogleAdsClient object.

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Next, run a campaign report using the GoogleAdsService.SearchStream method to retrieve the campaigns in your account. This guide doesn't cover the details of reporting.

    public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all campaigns.
    $query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream(
        SearchGoogleAdsStreamRequest::build($customerId, $query)
    );

    // Iterates over all rows in all messages and prints the requested field values for
    // the campaign in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        printf(
            "Campaign with ID %d and name '%s' was found.%s",
            $googleAdsRow->getCampaign()->getId(),
            $googleAdsRow->getCampaign()->getName(),
            PHP_EOL
        );
    }
}GetCampaigns.php

Python

The client library is distributed on PyPI can be installed using the pip command as follows:

python -m pip install google-ads==21.3.0

Make a copy of the google-ads.yaml file from the GitHub repository and modify it to include your credentials.

client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE
developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

Create a GoogleAdsClient instance by calling the GoogleAdsClient.load_from_storage method. Pass the path to your google-ads.yaml as a string to the method when calling it:

from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Next, run a campaign report using the GoogleAdsService.SearchStream method to retrieve the campaigns in your account. This guide doesn't cover the details of reporting.

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")

    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream = ga_service.search_stream(customer_id=customer_id, query=query)

    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )get_campaigns.py

Ruby

The Ruby gems for the client library are published to the Rubygems gem hosting site. The recommended way to install is using bundler. Add a line to your Gemfile:

gem 'google-ads-googleads', '~> 30.0.0'

Then run:

bundle install

Make a copy of the google_ads_config.rb file from the GitHub repository and modify it to include your credentials.

Google::Ads::GoogleAds::Config.new do |c|
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Create a GoogleAdsClient instance by passing the path to where you keep this file.

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

Next, run a campaign report using the GoogleAdsService.SearchStream method to retrieve the campaigns in your account. This guide doesn't cover the details of reporting.

    def get_campaigns(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
  )

  responses.each do |response|
    response.results.each do |row|
      puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
    end
  end
endget_campaigns.rb

Perl

The library is distributed on CPAN. Start by cloning the google-ads-perl repository in the directory of your choice.

git clone https://github.com/googleads/google-ads-perl.git

Change into the google-ads-perl directory and run the following command at the command prompt to install all dependencies needed for using the library.

cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps

Make a copy of the googleads.properties file from the GitHub repository and modify it to include your credentials.

clientId=INSERT_OAUTH2_CLIENT_ID_HERE
clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Create a Client instance by passing the path to where you keep this file.

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file
});

Next, run a campaign report using the GoogleAdsService.SearchStream method to retrieve the campaigns in your account. This guide doesn't cover the details of reporting.

    sub get_campaigns {
  my ($api_client, $customer_id) = @_;

  # Create a search Google Ads stream request that will retrieve all campaigns.
  my $search_stream_request =
    Google::Ads::GoogleAds::V18::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      =>
        "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $google_ads_service,
      request => $search_stream_request
    });

  # Issue a search request and process the stream response to print the requested
  # field values for the campaign in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf "Campaign with ID %d and name '%s' was found.\n",
        $google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
    });

  return 1;
}get_campaigns.pl

REST

Start by using an HTTP client to fetch an OAuth 2.0 access token. This guide uses the curl command.

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://www.googleapis.com/oauth2/v3/token

Next, run a campaign report using the GoogleAdsService.SearchStream method to retrieve the campaigns in your account. This guide doesn't cover the details of reporting.

curl -i -X POST https://googleads.googleapis.com/v18/customers/CUSTOMER_ID/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "developer-token: DEVELOPER_TOKEN" \
   -H "login-customer-id: LOGIN_CUSTOMER_ID" \
   --data-binary "@query.json"

The contents of query.json are as follows:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}

Download tools and libraries

Common errors