The Perl client library is hosted on [GitHub](https://github.com/googleads/google-ads-perl), and the
package is available on [CPAN](https://metacpan.org/release/Google-Ads-GoogleAds-Client).

The library supports Perl version 5.28.1 or greater.

## REST API protocol

> [!NOTE]
> **Note:** The Google Ads API exposes both standard JSON REST endpoints and a high-performance [gRPC](https://grpc.io) interface. Since Perl is not a [supported
> language](https://grpc.io/docs) in the gRPC stack, this client library is implemented on the JSON REST protocol over HTTP 1.1.

Class entities---such as service, resource, enum, and error---in the
Perl client library are generated by parsing the [protocol buffer
definitions](https://github.com/googleapis/googleapis/tree/master/google/ads/googleads). To learn more about how structured data is serialized,
refer to the [protocol buffer documentation](https://developers.google.com/protocol-buffers/docs/overview).

To connect with the Google Ads API, the client library creates an HTTP request in
[JSON](https://www.json.org/json-en.html), sends it to the REST endpoint over HTTP 1.1, deserializes the
response as a JSON object, and interprets the results.

## Install the library

The Perl client library is hosted on [GitHub](https://github.com/googleads/google-ads-perl) and distributed
using [CPAN](https://metacpan.org/release/Google-Ads-GoogleAds-Client).

### Install from CPAN

Install the [`Google::Ads::GoogleAds::Client`](https://metacpan.org/release/Google-Ads-GoogleAds-Client) distribution
directly from CPAN using `cpanm` (or `cpan`):

    cpanm Google::Ads::GoogleAds::Client

> [!NOTE]
> **Note:** Each `Google::Ads::GoogleAds::Client` release bundles specific Google Ads API version modules under `lib/Google/Ads/GoogleAds/` (where minor API releases such as `v25.1` are included under their major version module, `V25`). See the [supported API versions](https://developers.google.com/google-ads/api/docs/client-libs#supported-api-versions) table for version compatibility.

### Build from source and run examples

To run the bundled code examples or build the library from source:

1. Clone the library from GitHub:

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

2. Change into the `google-ads-perl` directory:

       cd google-ads-perl

   You'll see some files and subdirectories:
   - `Build.PL`: the Perl build file, which holds the dependencies and test types of this project.
   - `lib`: source code of the library.
   - `t`: test cases of the library code.
   - `examples`: many examples that demonstrate how to use the library to execute common use cases using the Google Ads API.
   - `googleads.properties`: the sample configuration file for the library.
   - `log4perl.conf`: the sample logging configuration file.
3. Install the required dependencies and build the library. The `Build.PL` file
   lists all the dependencies required for the library. You can install them by
   running the following commands:

       cpan install Module::Build
       perl Build.PL
       ./Build installdeps
       ./Build
       ./Build install

## Make your first API call

To use the Google Ads API, you need to perform several steps to get access to the API
and configure your Google Ads accounts. Follow the [quick start
guide](https://developers.google.com/google-ads/api/docs/get-started/make-first-call), which walks you through all the important steps including
setting up your Google Ads accounts.

## Basic usage

Initialize `Google::Ads::GoogleAds::Client` (which loads credentials from
`~/googleads.properties` or `GOOGLE_ADS_CONFIGURATION_FILE_PATH` by default) and
stream campaign rows using `SearchStreamHandler`:

    use strict;
    use warnings;
    use Google::Ads::GoogleAds::Client;
    use Google::Ads::GoogleAds::Utils::SearchStreamHandler;
    use Google::Ads::GoogleAds::V26::Services::GoogleAdsService::SearchGoogleAdsStreamRequest;

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

    my $search_stream_request =
      Google::Ads::GoogleAds::V26::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
      ->new({
        customerId => "INSERT_CUSTOMER_ID_HERE",
        query      =>
          "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
      });

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

    $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};
      });

Refer to the [basic usage guide](https://developers.google.com/google-ads/api/docs/client-libs/perl/basic-usage) to learn more about how to use the
Perl client library.

## Authentication and authorization

The Perl client library supports multiple approaches to authentication and
authorization. Refer to the [Authentication and authorization](https://developers.google.com/google-ads/api/docs/client-libs/perl/authentication)
guide to learn more.

## Configuration and logging

The Perl client library uses `googleads.properties` for configuration and
`log4perl.conf` for logging. You can modify these files to customize the
library's behavior. Refer to the [Configuration](https://developers.google.com/google-ads/api/docs/client-libs/perl/configuration) and
[Logging](https://developers.google.com/google-ads/api/docs/client-libs/perl/logging) guides to learn more.

## Utilities

The Perl client library includes utility classes to improve API usability. Refer
to the following guides to learn more:

- [Field masks](https://developers.google.com/google-ads/api/docs/client-libs/perl/field-masks)
- [Resource names](https://developers.google.com/google-ads/api/docs/client-libs/perl/resource-names)

## Fine-tune your application performance

Refer to the [Performance guide](https://developers.google.com/google-ads/api/docs/client-libs/perl/performance) for recommendations on how to
fine-tune your application's performance.