The Google Ads API client libraries provide high-level views and basic building blocks of Google Ads API functionality, making it easier to develop apps quickly. Start with a client library if you're new to the API. The following table lists the official client libraries and links to their setup guides, source repositories, packages, and code examples: | Client library | Setup and usage guides | Source | Distribution | Code examples | |---|---|---|---|---| | [Java](https://developers.google.com/google-ads/api/docs/client-libs/java.md.txt) | [Basic usage](https://developers.google.com/google-ads/api/docs/client-libs/java/basic-usage.md.txt), [Configuration](https://developers.google.com/google-ads/api/docs/client-libs/java/config-file.md.txt), [Authentication](https://developers.google.com/google-ads/api/docs/client-libs/java/authentication.md.txt), [Logging](https://developers.google.com/google-ads/api/docs/client-libs/java/logging.md.txt), [Field masks](https://developers.google.com/google-ads/api/docs/client-libs/java/field-masks.md.txt), [Resource names](https://developers.google.com/google-ads/api/docs/client-libs/java/resource-names.md.txt) | [google-ads-java](https://github.com/googleads/google-ads-java) | [Maven](https://search.maven.org/artifact/com.google.api-ads/google-ads), [tar.gz, zip](https://github.com/googleads/google-ads-java/releases) | [View on GitHub](https://github.com/googleads/google-ads-java/blob/HEAD/google-ads-examples/src/main/java/com/google/ads/googleads/examples) | | [.NET](https://developers.google.com/google-ads/api/docs/client-libs/dotnet.md.txt) | [Basic usage](https://developers.google.com/google-ads/api/docs/client-libs/dotnet/basic-usage.md.txt), [Configuration](https://developers.google.com/google-ads/api/docs/client-libs/dotnet/configuration.md.txt), [Authentication](https://developers.google.com/google-ads/api/docs/client-libs/dotnet/authentication.md.txt), [Logging](https://developers.google.com/google-ads/api/docs/client-libs/dotnet/logging.md.txt), [Field masks](https://developers.google.com/google-ads/api/docs/client-libs/dotnet/field-masks.md.txt), [Resource names](https://developers.google.com/google-ads/api/docs/client-libs/dotnet/resource-names.md.txt) | [google-ads-dotnet](https://github.com/googleads/google-ads-dotnet) | [NuGet](https://www.nuget.org/packages/Google.Ads.GoogleAds), [tar.gz, zip](https://github.com/googleads/google-ads-dotnet/releases) | [View on GitHub](https://github.com/googleads/google-ads-dotnet/blob/HEAD/Google.Ads.GoogleAds/examples) | | [PHP](https://developers.google.com/google-ads/api/docs/client-libs/php.md.txt) | [Basic usage](https://developers.google.com/google-ads/api/docs/client-libs/php/basic-usage.md.txt), [Configuration](https://developers.google.com/google-ads/api/docs/client-libs/php/configuration.md.txt), [Authentication](https://developers.google.com/google-ads/api/docs/client-libs/php/authentication.md.txt), [Logging](https://developers.google.com/google-ads/api/docs/client-libs/php/logging.md.txt), [Field masks](https://developers.google.com/google-ads/api/docs/client-libs/php/fieldmasks.md.txt), [Resource names](https://developers.google.com/google-ads/api/docs/client-libs/php/resourcenames.md.txt) | [google-ads-php](https://github.com/googleads/google-ads-php) | [Composer](https://packagist.org/packages/googleads/google-ads-php), [tar.gz, zip](https://github.com/googleads/google-ads-php/releases) | [View on GitHub](https://github.com/googleads/google-ads-php/blob/HEAD/examples) | | [Python](https://developers.google.com/google-ads/api/docs/client-libs/python.md.txt) | [Installation](https://developers.google.com/google-ads/api/docs/client-libs/python/installation.md.txt), [Configuration](https://developers.google.com/google-ads/api/docs/client-libs/python/configuration.md.txt), [Authentication](https://developers.google.com/google-ads/api/docs/client-libs/python/authentication.md.txt), [Logging](https://developers.google.com/google-ads/api/docs/client-libs/python/logging.md.txt), [Field masks](https://developers.google.com/google-ads/api/docs/client-libs/python/field-masks.md.txt), [Resource names](https://developers.google.com/google-ads/api/docs/client-libs/python/resource-names.md.txt) | [google-ads-python](https://github.com/googleads/google-ads-python) | [PyPI](https://pypi.org/project/google-ads/), [tar.gz, zip](https://github.com/googleads/google-ads-python/releases) | [View on GitHub](https://github.com/googleads/google-ads-python/blob/HEAD/examples) | | [Ruby](https://developers.google.com/google-ads/api/docs/client-libs/ruby.md.txt) | [Basic usage](https://developers.google.com/google-ads/api/docs/client-libs/ruby/basic-usage.md.txt), [Configuration](https://developers.google.com/google-ads/api/docs/client-libs/ruby/configuration.md.txt), [Authentication](https://developers.google.com/google-ads/api/docs/client-libs/ruby/authentication.md.txt), [Logging](https://developers.google.com/google-ads/api/docs/client-libs/ruby/logging.md.txt), [Field masks](https://developers.google.com/google-ads/api/docs/client-libs/ruby/field-masks.md.txt), [Resource names](https://developers.google.com/google-ads/api/docs/client-libs/ruby/resource-names.md.txt) | [google-ads-ruby](https://github.com/googleads/google-ads-ruby) | [RubyGems](https://rubygems.org/gems/google-ads-googleads), [tar.gz, zip](https://github.com/googleads/google-ads-ruby/releases) | [View on GitHub](https://github.com/googleads/google-ads-ruby/blob/HEAD/examples) | | [Perl](https://developers.google.com/google-ads/api/docs/client-libs/perl.md.txt) | [Basic usage](https://developers.google.com/google-ads/api/docs/client-libs/perl/basic-usage.md.txt), [Configuration](https://developers.google.com/google-ads/api/docs/client-libs/perl/configuration.md.txt), [Authentication](https://developers.google.com/google-ads/api/docs/client-libs/perl/authentication.md.txt), [Logging](https://developers.google.com/google-ads/api/docs/client-libs/perl/logging.md.txt), [Field masks](https://developers.google.com/google-ads/api/docs/client-libs/perl/field-masks.md.txt), [Resource names](https://developers.google.com/google-ads/api/docs/client-libs/perl/resource-names.md.txt) | [google-ads-perl](https://github.com/googleads/google-ads-perl) | [CPAN](https://metacpan.org/release/Google-Ads-GoogleAds-Client), [tar.gz, zip](https://github.com/googleads/google-ads-perl/releases) | [View on GitHub](https://github.com/googleads/google-ads-perl/blob/HEAD/examples) | ## Community libraries We are aware of several libraries that are maintained by the open source community. We maintain this list to help interested developers find them. We don't test, contribute to, or maintain these libraries; use them at your own risk. Any questions you may have should be directed to the owners of the open source projects. If you are aware of a library that we have missed, click **Send feedback** at the top of the page and let us know. - Node.js: [`google-ads-api` on npm](https://www.npmjs.com/package/google-ads-api) - Go: [`google-ads-pb` on GitHub](https://github.com/shenzhencenter/google-ads-pb) ## Supported API versions The table shows which client libraries work with which API versions. The listed minimum client library version is sufficient for the major Google Ads API release (such as v26). To see the required client library version for minor releases, refer to the linked Changelog. ### Java [Changelog](https://github.com/googleads/google-ads-java/blob/main/CHANGELOG.md) |---|---| | ##### Google Ads API | ##### Client library for Java | | `v26` | Min: `48.0.0` Max: - | | `v25` | Min: `44.0.0` Max: - | | `v24` | Min: `43.0.0` Max: - | | `v23` | Min: `42.0.0` Max: - | ### C# [Changelog](https://github.com/googleads/google-ads-dotnet/blob/main/CHANGELOG.md) |---|---| | ##### Google Ads API | ##### Client library for .NET | | `v26` | Min: `27.5.0` Max: - | | `v25` | Min: `26.1.0` Max: - | | `v24` | Min: `25.3.0` Max: - | | `v23` | Min: `25.1.0` Max: - | ### PHP [Changelog](https://github.com/googleads/google-ads-php/blob/main/CHANGELOG.md) |---|---| | ##### Google Ads API | ##### Client library for PHP | | `v26` | Min: `35.2.0` Max: - | | `v25` | Min: `33.6.0` Max: - | | `v24` | Min: `33.3.0` Max: - | | `v23` | Min: `32.2.0` Max: - | ### Python [Changelog](https://github.com/googleads/google-ads-python/blob/main/ChangeLog) |---|---| | ##### Google Ads API | ##### Client library for Python | | `v26` | Min: `34.0.0` Max: - | | `v25` | Min: `31.2.0` Max: - | | `v24` | Min: `30.1.0` Max: - | | `v23` | Min: `29.2.0` Max: - | ### Ruby [Changelog](https://github.com/googleads/google-ads-ruby/blob/main/CHANGELOG.md) |---|---| | ##### Google Ads API | ##### Client library for Ruby | | `v26` | Min: `46.0.0` Max: - | | `v25` | Min: `43.0.0` Max: - | | `v24` | Min: `40.0.0` Max: - | | `v23` | Min: `38.0.0` Max: - | ### Perl [Changelog](https://github.com/googleads/google-ads-perl/blob/main/CHANGELOG.md) |---|---| | ##### Google Ads API | ##### Client library for Perl | | `v26` | Min: `36.0.0` Max: - | | `v25` | Min: `33.0.0` Max: - | | `v24` | Min: `32.0.0` Max: - | | `v23` | Min: `31.0.0` Max: - | ## Configuration Each Google Ads API client library provides different configuration settings and loading methods that you can use to customize its behavior. Here are the standard environment variables that you can use to configure the client libraries: - **Client library** - `GOOGLE_ADS_CONFIGURATION_FILE_PATH`: Path to the configuration file (read automatically when loading from a configuration file without an explicit path argument in Java (`fromPropertiesFile()`), Perl (`Client->new()`), PHP (`fromFile()`), Python (`load_from_storage()`, and also checked by `load_from_env()`), and Ruby (`GoogleAdsClient.new`); in `.NET`, load this variable explicitly using `config.TryLoadFromEnvironmentFilePath` or load configuration files using `LoadFromSettingsJson`, `LoadFromConfigurationSection`, or `LoadFromConfigurationRoot`). - **OAuth2** - **Application mode** - `GOOGLE_ADS_CLIENT_ID`: Set this value to your OAuth2 client ID. - `GOOGLE_ADS_CLIENT_SECRET`: Set this value to your OAuth2 client secret. - `GOOGLE_ADS_REFRESH_TOKEN`: Set this value to a pre-generated OAuth2 refresh token if you want to reuse OAuth2 tokens. This setting is optional. - **Service account mode** - `GOOGLE_ADS_JSON_KEY_FILE_PATH`: Set this value to the path of your OAuth2 JSON key file (in `.NET`, also set `GOOGLE_ADS_OAUTH2_MODE` to `SERVICE_ACCOUNT`, as `OAuth2Mode` defaults to `APPLICATION`; in PHP versions earlier than `v32.1.0` or when using custom scopes, also set `[OAUTH2] scopes` in `google_ads_php.ini` or call `withScopes()`, as `fromEnvironmentVariables()` does not read OAuth2 scopes from an environment variable). - `GOOGLE_ADS_IMPERSONATED_EMAIL`: Set this value to the email address of the account you are impersonating when using Google Workspace domain-wide delegation. This setting is optional. - **Application Default Credentials mode** - `GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS`: Set this value to `true` to authenticate using Application Default Credentials (ADC). Supported in Java `v41.1.0` and later, Python `v28.3.0` and later, and Ruby `v36.1.0` and later (in .NET `v24.1.0` and later, `LoadFromEnvironmentVariables()` reads the unprefixed `USE_APPLICATION_DEFAULT_CREDENTIALS` variable instead, or set `UseApplicationDefaultCredentials = true` on `GoogleAdsConfig`; in PHP, `OAuth2TokenBuilder` automatically falls back to ADC when no explicit OAuth2 credentials are set; Perl does not support ADC). - **Google Ads API** - `GOOGLE_ADS_LOGIN_CUSTOMER_ID`: This is the customer ID of the authorized customer to use in the request, without hyphens (`-`). - `GOOGLE_ADS_LINKED_CUSTOMER_ID`: This header is only required for methods that update the resources of an entity when permissioned through Linked Accounts in the Google Ads UI (`AccountLink` resource in the Google Ads API). Set this value to the customer ID of the data provider that updates the resources of the specified customer ID. It should be set without hyphens (`-`). To learn more about Linked Accounts, visit the [Help Center](https://support.google.com/google-ads/answer/7365001). > [!NOTE] > **Note:** For more detail on how to use them and any additional client library-specific environment variables, refer to the configuration guides that are dedicated to each client library: [Java](https://developers.google.com/google-ads/api/docs/client-libs/java/config-file.md.txt), [.NET](https://developers.google.com/google-ads/api/docs/client-libs/dotnet/configuration.md.txt), [PHP](https://developers.google.com/google-ads/api/docs/client-libs/php/configuration.md.txt), [Python](https://developers.google.com/google-ads/api/docs/client-libs/python/configuration.md.txt), [Ruby](https://developers.google.com/google-ads/api/docs/client-libs/ruby/configuration.md.txt), [Perl](https://developers.google.com/google-ads/api/docs/client-libs/perl/configuration.md.txt). Environment variables are commonly defined in a bash configuration file such as a `.bashrc` or `.bash_profile` file located in the `$HOME` directory. They can also be defined using the command line. > [!NOTE] > **Note:** These instructions assume you're using Bash. If you're using a different shell, consult documentation for equivalent commands. Here are some basic steps to define an environment variable using a `.bashrc` file using a terminal: ```bash # Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to # the bottom of your .bashrc file. echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc # Update your bash environment to use the most recently updated # version of your .bashrc file. source ~/.bashrc ``` Environment variables can also be set in your terminal instance directly from the command line: ```bash export GOOGLE_ADS_CLIENT_ID=1234567890 ``` Another alternative is to set environment variables when calling the command that uses them: ```bash GOOGLE_ADS_CLIENT_ID=1234567890 php /path/to/script/that/uses/envvar.php ``` ## Fetch entities [`GoogleAdsService.SearchStream`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/SearchStream.md.txt) is typically used to fetch entities, and the results are returned as a stream of rows. Alternatively, you can use [`GoogleAdsService.Search`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/Search.md.txt) to fetch entities over an unreliable internet connection. `GoogleAdsService.Search` returns results as fixed page sizes of 10,000 rows per page. The client libraries automatically [implement paging](https://developers.google.com/google-ads/api/docs/reporting/paging.md.txt) when you iterate results so that you can sequentially download and process them all at once. ### Java ```java 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 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()); } } } } ``` ### C# ```c# public void Run(GoogleAdsClient client, long customerId) { // Get the GoogleAdsService. GoogleAdsServiceClient googleAdsService = client.GetService( Services.V26.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; } } ``` ### PHP ```php 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 ); } } ``` ### Python ```python 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.' ) ``` ### Ruby ```ruby 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 ``` ### Perl ```perl 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::V26::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; } ``` ### curl > [!NOTE] > **Note:** While a direct REST code sample for this step isn't provided here, you can achieve this using a manual REST request. > > Refer to the Google Ads API REST interface documentation and the method-specific reference pages. You will need to construct the JSON payload based on the proto definitions. > > Key Resources: > > - [Using REST](https://developers.google.com/google-ads/api/rest/overview.md.txt) > - [REST Interface Structure](https://developers.google.com/google-ads/api/rest/design/overview.md.txt) > - [JSON Field Mappings](https://developers.google.com/google-ads/api/rest/design/json-mappings.md.txt) > - Consult the [REST API Reference](https://developers.google.com/google-ads/api/reference/rpc/latest/overview) for the specific service and method.
## Code examples [Check out our code examples](https://developers.google.com/google-ads/api/samples.md.txt) of some common functions in the Google Ads API.