Make an API call

Note: The current step of this tutorial depends on the type of application you are building. We strongly recommend using service account to make API calls. However, the user authentication option is also provided as an alternative. The rest of this tutorial will be customized based on your choice.

Service accounts User authentication

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

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>40.0.0</version>
</dependency>

The Gradle dependency is:

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

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
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 = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    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.V21.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:31.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]
jsonKeyFilePath = "INSERT_ABSOLUTE_PATH_TO_OAUTH2_JSON_KEY_FILE_HERE"
scopes = "https://www.googleapis.com/auth/adwords"

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.

developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH_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")

Add a handler to the library's logger telling it where to print logs. The following will tell the library's logger to print to the console (stdout).

import logging
import sys

logger = logging.getLogger('google.ads.googleads.client')
logger.addHandler(logging.StreamHandler(sys.stdout))

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: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

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

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            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', '~> 35.2.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.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  c.keyfile = 'JSON_KEY_FILE_PATH'
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
end
get_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.

jsonKeyFilePath=JSON_KEY_FILE_PATH
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::V21::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 setting the service account as the active credentials in gcloud CLI.

gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSON

Next, fetch an OAuth 2.0 access token for the Google Ads API.

gcloud auth \
  print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'

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/v21/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"
}