use Google::Ads::GoogleAds::Client;

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

  my $customer_id = "1234567890";

  my $query = "SELECT, FROM campaign";

  my $response = $api_client->GoogleAdsService()->search({
    customer_id => $customer_id,
    query       => $query,
    pageSize    => PAGE_SIZE

  foreach my $row (@{$response->{results}}) {
    # Do something with the results


Google::Ads::GoogleAds::Client is the main interface to the Google Ads API. It takes care of handling your API credentials, and exposes all of the underlying services that make up the Google Ads API.

The Google::Ads::GoogleAds::Client module should be loaded before other Google::Ads:: modules. A warning will occur if modules are loaded in the wrong order.


Each of these attributes can be set via Google::Ads::GoogleAds::Client->new().

Alternatively, there is a get_ and set_ method associated with each attribute for retrieving or setting them dynamically. For example, the set_login_customer_id() allows you to change the value of the "login_customer_id" attribute and get_login_customer_id() returns the current value of the attribute.


A string used to tie usage of the Google Ads API to a specific Google Ads manager account.

The value should be a character string assigned to you by Google. You can apply for a Developer Token by following the instructions at


This is the customer ID of the authorized customer to use in the request, without hyphens. If your access to the customer account is through a manager account, this attribute is required and must be set to the customer ID of the manager account.


The Google Ads API service address.


The user-agent request header used to identify this application.


The proxy server URL to be used for internet connectivity.


The HTTP timeout value in seconds.


The version of the Google Ads API to use. The latest is the default.


By default the client returns a Google::Ads::GoogleAds::GoogleAdsException object if an error has occurred at the server side. However if this flag is set to true, the client will issue a die() command on received API faults.

The default is "false".


The path of the configuration file. The default value is file in the home directory.


The last HTTP request sent by this client.


The last HTTP response received by this client.



Initializes a new Google::Ads::GoogleAds::Client object.


The new() method takes parameters as a hash reference. The attributes of this object can be populated in a number of ways:

  • If the "properties_file" parameter is given, then properties are read from that file and the corresponding attributes are populated.

  • If no "properties_file" parameter is given, then the code checks to see if there is a file named in the home directory of the current user. If there is, then properties are read from there.

  • Any of the "ATTRIBUTES" can be passed in as keys in the parameters hash reference. If any attribute is explicitly passed in then it will override the value for that attribute that might be in the properties file.


A new Google::Ads::GoogleAds::Client object with the appropriate attributes set.


If a "properties_file" is passed in but the file cannot be read, the code will die() with an error message describing the failure.


  # Basic use case. Attributes will be read from ~/ file.
  my $api_client = Google::Ads::GoogleAds::Client->new();

  # Most attributes from a custom properties file, but override login_customer_id.
  eval {
    my $api_client = Google::Ads::GoogleAds::Client->new({
      properties_file   => "/path/to/",
      login_customer_id => "1234567890"
  if ($@) {
    # The properties file couldn't be read; handle error as appropriate.

  # Specify all attributes explicitly. The properties file will not override.
  my $api_client = Google::Ads::GoogleAds::Client->new({
    developer_token   => "123xyzabc...",
    login_customer_id => "1234567890"



This module supports two approaches for handling API faults (i.e. errors returned by the underlying REST API service).

One approach is to issue a die() with a description of the error when an API fault occurs. This die() would ideally be contained within an eval { }; block, thereby emulating try { } / catch { } exception functionality in other languages.

A different approach is to require developers to explicitly check for API faults being returned after each Google Ads API request. This approach requires a bit more work, but has the advantage of exposing the full details of the API fault, like the fault code.

Refer to the object Google::Ads::GoogleAds::GoogleAdsException for more details on how faults get returned.

The default value is false, i.e. you must explicitly check for faults.


A true value will cause this module to die() when an API fault occurs.

A false value will suppress this die(). This is the default behavior.


The input parameter is returned.


  # $api_client is a Google::Ads::GoogleAds::Client.

  # Enable die()ing on faults.
  eval { my $response = $api_client->AdGroupAdService()->mutate($mutate_request); };
  if ($@) {
    # Do something with the error information in $@.

  # Default behavior.
  my $response = $api_client->AdGroupAdService()->mutate($mutate_request);
  if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
    # Do something with this GoogleAdsException object.



A true or false value indicating whether the Google::Ads::GoogleAds::Client instance is set to die() on API faults.


The client object contains a method for each service provided by the Google Ads API. For example it can be invoked as $api_client->AdGroupService() and it will return an object of type Google::Ads::GoogleAds::V3::Services::AdGroupService when using version V3 of the API.

For a list of all the available services please refer to and for code samples on how to invoke the services please refer to scripts in the examples folder.


Returns the OAuth2 authorization handler for Web/Installed applications attached to the client, for programmatically setting/overriding its properties.


Refer to Google::Ads::GoogleAds::OAuth2ApplicationsHandler for more details.

__parse_properties_file (Private)


The path to a properties file on disk. The data in the file should be in the following format:



A hash corresponding to the keys and values in the properties file.


Issues a die() with an error message if the properties file could not be read.

_auth_handler (Protected)

Retrieves the active auth handler. All handlers are checked in the order.


An implementation of Google::Ads::GoogleAds::Common::AuthHandlerInterface.


Copyright 2019 Google LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


 $Rev: $
 $LastChangedBy: $
 $Id: $