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](https://developers.google.com/google-ads/api/docs/client-libs/perl/configuration.md.txt). A common approach is to
use a `googleads.properties` file:

```perl
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:

```perl
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 (`V26` in the latest release;
minor releases such as `v26.1` use their major version module,
`V26`). To target
a specific supported API version, pass
`version => "V26"` to `Client->new({...})` or call
`$api_client->set_version("V26")`.

## 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.

```perl
use strict;
use warnings;
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V26::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::V26::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`](https://github.com/googleads/google-ads-perl/blob/HEAD/lib/Google/Ads/GoogleAds/GoogleAdsException.pm) 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 ($@)`).

```perl
use strict;
use warnings;
use Scalar::Util qw(blessed);
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V26::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::V26::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](https://github.com/googleads/google-ads-perl/tree/HEAD/examples). 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.

```bash
perl examples/basic_operations/get_campaigns.pl -help
```