Basic usage

This guide explains the basics of using the Perl client library for the Google Ads API.

Initialize the client

To start using the library, create an instance of Google::Ads::GoogleAds::Client. The client can be configured in several ways, as detailed in the Configuration guide. A common approach is to use a googleads.properties file:

use strict;
use warnings;
use Google::Ads::GoogleAds::Client;

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

Create a service

Once the client is initialized, you can create instances of the various API services. For example, to interact with campaigns, you would create a CampaignService instance:

use strict;
use warnings;

my $campaign_service = $api_client->CampaignService();

By default, $api_client loads services for the DEFAULT_API_VERSION of your installed library release (V25 in the latest release; minor releases such as v25.1 use their major version module, V25). To target a specific supported API version, pass version => "V25" to Client->new({...}) or call $api_client->set_version("V25").

Make an API call

Here's an example of how to make an API call to get campaigns. This snippet demonstrates initializing the client, creating a service, and calling a method.

use strict;
use warnings;
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest;

# Initialize the Google Ads client. See the Configuration guide for options.
my $api_client = Google::Ads::GoogleAds::Client->new();

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

# Specify the customer ID and query.
my $customer_id = "INSERT_CUSTOMER_ID_HERE";
my $query = "SELECT campaign.name, campaign.status FROM campaign";

# Create a search request.
my $search_request =
  Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest
  ->new({
    customerId => $customer_id,
    query      => $query,
  });

# Execute the search request.
my $search_response = $google_ads_service->search($search_request);

# Iterate over the results and print campaign names.
foreach my $google_ads_row (@{$search_response->{results} || []}) {
  printf "Campaign with resource name '%s' and name '%s'.\n",
    $google_ads_row->{campaign}->{resourceName},
    $google_ads_row->{campaign}->{name};
}

Handle errors

API calls can result in errors. By default, die_on_faults is 0 (false), which causes service methods to emit a warning and return a Google::Ads::GoogleAds::GoogleAdsException object when an API error occurs. You can check whether the returned response is a GoogleAdsException and call get_google_ads_failure() to inspect the individual GoogleAdsError entries.

Alternatively, if you set die_on_faults => 1 on Client->new({...}) (or call $api_client->set_die_on_faults(1)), service methods call die() with the raw JSON error response when an API fault occurs, which you can catch in an eval block (if ($@)).

use strict;
use warnings;
use Scalar::Util qw(blessed);
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest;

my $api_client = Google::Ads::GoogleAds::Client->new();
my $google_ads_service = $api_client->GoogleAdsService();
my $customer_id = "INSERT_CUSTOMER_ID_HERE";
my $query = "SELECT campaign.name, campaign.status FROM campaign";
my $search_request =
  Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest
  ->new({
    customerId => $customer_id,
    query      => $query,
  });

my $search_response = $google_ads_service->search($search_request);

if (blessed($search_response)
  && $search_response->isa("Google::Ads::GoogleAds::GoogleAdsException"))
{
  printf "An API exception occurred (HTTP %s, status '%s'): %s\n",
    $search_response->get_code(),
    $search_response->get_status(),
    $search_response->get_message();

  my $google_ads_failure = $search_response->get_google_ads_failure();
  if ($google_ads_failure) {
    foreach my $error (@{$google_ads_failure->{errors} || []}) {
      my ($error_type, $error_value) = %{$error->{errorCode} || {}};
      printf "  Error code (%s): %s\n",
        $error_type  || "unknown",
        $error_value || "UNKNOWN";
      printf "  Message: %s\n", $error->{message};
    }
  }
} else {
  foreach my $google_ads_row (@{$search_response->{results} || []}) {
    printf "Campaign name: %s\n", $google_ads_row->{campaign}->{name};
  }
}

Explore other examples

You can find several useful code samples in the examples directory. Most of the examples require parameters. You can either pass the parameters as arguments (recommended) or edit the INSERT_XXXXX_HERE values in the source code. To see a usage statement for an example, pass -help as a command-line argument.

perl examples/basic_operations/get_campaigns.pl -help