Our client libraries provide high-level views and basic building blocks of Google Ads API functionality, making it easier to develop apps quickly. We recommend starting out with one if you're new to the API.
Client library | Source | Distribution | Code examples |
---|---|---|---|
Java | google-ads-java | Maven, tar.gz | View on GitHub |
.NET | google-ads-dotnet | nuget, tar.gz, zip | View on GitHub |
PHP | google-ads-php | tar.gz | View on GitHub |
Python | google-ads-python | tar.gz, zip | View on GitHub |
Ruby | google-ads-ruby | gem, tar.gz, zip | View on GitHub |
Perl | google-ads-perl | tar.gz, zip | View on GitHub |
Supported API versions
The table shows which client libraries work with which API versions.
Java
Google Ads API | Client library for Java |
v13 |
Min: 23.0.0 Max: - |
v12 |
Min: 22.0.0 Max: - |
C#
Google Ads API | Client library for .NET |
v13 |
Min: 15.0.0 Max: - |
v12 |
Min: 14.2.0 Max: - |
PHP
Google Ads API | Client library for PHP |
v13 |
Min: 18.0.0 Max: - |
v12 |
Min: 17.1.0 Max: - |
Python
Google Ads API | Client library for Python |
v13 |
Min: 20.0.0 Max: - |
v12 |
Min: 19.0.0 Max: - |
Ruby
Google Ads API | Client library for Ruby |
v13 |
Min: 21.0.0 Max: - |
v12 |
Min: 20.0.0 Max: - |
Perl
Google Ads API | Client library for Perl |
v13 |
Min: 15.0.0 Max: - |
v12 |
Min: 14.0.0 Max: - |
Configuration
Each Ads API Client library provides different configuration settings and loading methods that you can use to customize its behavior.
Here are the environment variables that are common to all client libraries and that can be loaded to set configuration settings:
- Client library
GOOGLE_ADS_CONFIGURATION_FILE_PATH
: Path to the configuration file.
- 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 OAuth2 JSON configuration file path.GOOGLE_ADS_IMPERSONATED_EMAIL
: Set this value to the email address of the account you are impersonating.
- Application Mode
- Google Ads API
GOOGLE_ADS_DEVELOPER_TOKEN
: Set this to your developer token.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.
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.
Here are some basic steps to define an environment variable using a .bashrc
file using a terminal:
# 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.
src ~/.bashrc
Environment variables can also be set in your terminal instance directly from the command line:
export GOOGLE_ADS_CLIENT_ID=1234567890
Another alternative is to set environment variables when calling the command that uses them:
GOOGLE_ADS_CLIENT_ID=1234567890 php /path/to/script/that/uses/envvar.php
Search pagination
GoogleAdsService.Search
is typically
used in interactive apps that display pages of results.
Our client library automatically implements paging when you iterate results so that you can sequentially download and process them all at once, for example:
Java
private void runExample(GoogleAdsClient googleAdsClient, long customerId, long labelId) { try (GoogleAdsServiceClient googleAdsServiceClient = googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) { // Creates a request that will retrieve all campaign labels with the specified // labelId using pages of the specified page size. SearchGoogleAdsRequest request = SearchGoogleAdsRequest.newBuilder() .setCustomerId(Long.toString(customerId)) .setPageSize(PAGE_SIZE) .setQuery( "SELECT campaign.id, campaign.name, label.id, label.name " + "FROM campaign_label WHERE label.id = " + labelId + " ORDER BY campaign.id") .build(); // Issues the search request. SearchPagedResponse searchPagedResponse = googleAdsServiceClient.search(request); // Checks if the total results count is greater than 0. if (searchPagedResponse.getPage().getResponse().getTotalResultsCount() > 0) { // Iterates over all rows in all pages and prints the requested field values for the // campaigns and labels in each row. The results include the campaign and label // objects because these were included in the search criteria. for (GoogleAdsRow googleAdsRow : searchPagedResponse.iterateAll()) { System.out.printf( "Campaign found with name '%s', ID %d, and label: %s.%n", googleAdsRow.getCampaign().getName(), googleAdsRow.getCampaign().getId(), googleAdsRow.getLabel().getName()); } } else { System.out.println("No campaigns were found."); } } }
C#
public void Run(GoogleAdsClient client, long customerId, long labelId) { // Get the GoogleAdsServiceClient. GoogleAdsServiceClient googleAdsService = client.GetService(Services.V13.GoogleAdsService); // Creates a request that will retrieve all campaign labels with the specified // labelId using pages of the specified page size. SearchGoogleAdsRequest request = new SearchGoogleAdsRequest() { CustomerId = customerId.ToString(), Query = "SELECT campaign.id, campaign.name, label.id, label.name " + $"FROM campaign_label WHERE label.id = {labelId} ORDER BY campaign.id", }; try { int count = 0; // Issues the search request and prints the result. foreach (GoogleAdsRow googleAdsRow in googleAdsService.Search(request)) { count++; Console.WriteLine($"Campaign found with name '{googleAdsRow.Campaign.Name}'" + $", ID {googleAdsRow.Campaign.Id}, and label: " + $"'${googleAdsRow.Label.Name}'."); } if (count == 0) { Console.WriteLine("No campaigns were found."); } } catch (GoogleAdsException e) { Console.WriteLine("Failure:"); Console.WriteLine($"Message: {e.Message}"); Console.WriteLine($"Failure: {e.Failure}"); Console.WriteLine($"Request ID: {e.RequestId}"); throw; } }
PHP
public static function runExample( GoogleAdsClient $googleAdsClient, int $customerId, int $labelId ) { $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); // Creates a query that will retrieve all campaign labels with the specified // label ID. $query = "SELECT campaign.id, campaign.name, label.id, label.name " . "FROM campaign_label WHERE label.id = $labelId ORDER BY campaign.id"; // Issues a search request by specifying page size. $response = $googleAdsServiceClient->search($customerId, $query, ['pageSize' => self::PAGE_SIZE]); // Iterates over all rows in all pages and prints the requested field values for the // campaigns and labels in each row. The results include the campaign and label // objects because these were included in the search criteria. foreach ($response->iterateAllElements() as $googleAdsRow) { /** @var GoogleAdsRow $googleAdsRow */ printf( "Campaign found with name '%s', ID %d, and label: '%s'.%s", $googleAdsRow->getCampaign()->getName(), $googleAdsRow->getCampaign()->getId(), $googleAdsRow->getLabel()->getName(), PHP_EOL ); } }
Python
def main(client, customer_id, label_id, page_size): """Demonstrates how to retrieve all campaigns by a given label ID. Args: client: An initialized GoogleAdsClient instance. customer_id: A client customer ID str. label_id: A label ID to use when searching for campaigns. page_size: An int of the number of results to include in each page of results. """ ga_service = client.get_service("GoogleAdsService") # Creates a query that will retrieve all campaign labels with the # specified label ID. query = f""" SELECT campaign.id, campaign.name, label.id, label.name FROM campaign_label WHERE label.id = "{label_id}" ORDER BY campaign.id""" # Retrieves a google.api_core.page_iterator.GRPCIterator instance # initialized with the specified request parameters. request = client.get_type("SearchGoogleAdsRequest") request.customer_id = customer_id request.query = query request.page_size = page_size iterator = ga_service.search(request=request) # Iterates over all rows in all pages and prints the requested field # values for the campaigns and labels in each row. The results include # the campaign and label objects because these were included in the # search criteria. for row in iterator: print( f'Campaign found with ID "{row.campaign.id}", name ' f'"{row.campaign.name}", and label "{row.label.name}".' ) if __name__ == "__main__": # GoogleAdsClient will read the google-ads.yaml configuration file in the # home directory if none is specified. googleads_client = GoogleAdsClient.load_from_storage(version="v13") parser = argparse.ArgumentParser( description="Lists all campaigns for specified customer." ) # The following argument(s) should be provided to run the example. parser.add_argument( "-c", "--customer_id", type=str, required=True, help="The Google Ads customer ID.", ) parser.add_argument( "-l", "--label_id", type=str, required=True, help="A label ID associated with a campaign.", ) args = parser.parse_args() try: main( googleads_client, args.customer_id, args.label_id, _DEFAULT_PAGE_SIZE, ) except GoogleAdsException as ex: print( f'Request with ID "{ex.request_id}" failed with status ' f'"{ex.error.code().name}" and includes the following errors:' ) for error in ex.failure.errors: print(f'\tError with message "{error.message}".') if error.location: for field_path_element in error.location.field_path_elements: print(f"\t\tOn field: {field_path_element.field_name}") sys.exit(1)
Ruby
def get_campaigns_by_label(customer_id, label_id) # GoogleAdsClient will read a config file from # ENV['HOME']/google_ads_config.rb when called without parameters client = Google::Ads::GoogleAds::GoogleAdsClient.new query = <<~EOQUERY SELECT campaign.id, campaign.name, label.id, label.name FROM campaign_label WHERE label.id = '#{label_id}' ORDER BY campaign.id EOQUERY ga_service = client.service.google_ads response = ga_service.search( customer_id: customer_id, query: query, page_size: PAGE_SIZE, ) response.each do |row| puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found." end end
Perl
sub get_campaigns_by_label { my ($api_client, $customer_id, $label_id) = @_; # Create the search query. my $search_query = "SELECT campaign.id, campaign.name, label.id, label.name " . "FROM campaign_label WHERE label.id = $label_id ORDER BY campaign.id"; # Create a search Google Ads request that will retrieve all campaign labels # with the specified label Id using pages of the specified page size. my $search_request = Google::Ads::GoogleAds::V13::Services::GoogleAdsService::SearchGoogleAdsRequest ->new({ customerId => $customer_id, query => $search_query, pageSize => PAGE_SIZE }); # Get the GoogleAdsService. my $google_ads_service = $api_client->GoogleAdsService(); my $iterator = Google::Ads::GoogleAds::Utils::SearchGoogleAdsIterator->new({ service => $google_ads_service, request => $search_request }); # Iterate over all rows in all pages and print the requested field values for the # campaigns and labels in each row. The results include the campaign and label # objects because these were included in the search criteria. while ($iterator->has_next) { my $google_ads_row = $iterator->next; printf "Campaign found with name '%s', ID %d, and label: '%s'.\n", $google_ads_row->{campaign}{name}, $google_ads_row->{campaign}{id}, $google_ads_row->{label}{name}; } return 1; }
Depending on the use case, you may need to:
- Optimize how many pages are fetched.
- Optimize how much results are stored at any one time.
- Download and process pages of results in a particular order.
This can be done by storing the page tokens instead of results, which adds more complexity to your code.
Java
/** * Fetches and prints the results of a page of a search using a cache of page tokens. * * @param googleAdsClient the Google Ads API client. * @param customerId the client customer ID. * @param query the search query. * @param pageNumber the number of the page to fetch and print results for. * @param pageTokens the cache of page tokens to use and update. */ private static void fetchAndPrintPageResults( GoogleAdsClient googleAdsClient, long customerId, String query, int pageNumber, SortedMap<Integer, String> pageTokens) { int currentPageNumber; // There is no need to fetch the pages we already know the page tokens for. if (pageTokens.containsKey(pageNumber)) { System.out.println( "The token of the requested page was cached, we will use it to get the results."); currentPageNumber = pageNumber; } else { System.out.printf( "The token of the requested page was never cached, we will use the closest page we know" + " the token for (page %d) and sequentially get pages from there.%n", pageTokens.size()); currentPageNumber = pageTokens.lastKey(); } // Fetches next pages in sequence and caches their tokens until the requested page results // are returned. while (currentPageNumber <= pageNumber) { // Fetches the next page. System.out.printf("Fetching page %d...%n", currentPageNumber); SearchGoogleAdsRequest request = SearchGoogleAdsRequest.newBuilder() .setCustomerId(Long.toString(customerId)) .setPageSize(PAGE_SIZE) .setQuery(query) .setReturnTotalResultsCount(true) // Uses the page token cached for the current page number. .setPageToken(pageTokens.get(currentPageNumber)) .build(); try (GoogleAdsServiceClient googleAdsServiceClient = googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) { SearchPagedResponse response = googleAdsServiceClient.search(request); cacheNextPageToken(pageTokens, response.getPage(), currentPageNumber + 1); // Prints only the results for the requested page. if (currentPageNumber == pageNumber) { // Prints the results of the requested page. System.out.printf("Printing results found for page %d:%n", pageNumber); for (GoogleAdsRow googleAdsRow : response.getPage().getResponse().getResultsList()) { System.out.printf( "- Campaign with ID %d and name '%s'.%n", googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName()); } } currentPageNumber++; } } }
C#
/// <summary> /// Fetches and prints the results of a page of a search using a cache of page tokens. /// </summary> /// <param name="googleAdsService">The Google Ads API Service client.</param> /// <param name="request">The request.</param> /// <param name="pageNumber">The number of the page to fetch and print results for.</param> /// <param name="pageTokens">The cache of page tokens to use and update.</param> /// <returns></returns> private static void FetchAndPrintPageResults(GoogleAdsServiceClient googleAdsService, SearchGoogleAdsRequest request, int pageNumber, Dictionary<int, string> pageTokens) { int currentPageNumber = pageNumber; // There is no need to fetch the pages we already know the page tokens for. if (pageTokens.ContainsKey(pageNumber - 1)) { Console.WriteLine("The token of the requested page was cached, we will use it " + "to get the results."); currentPageNumber = pageNumber; } else { Console.WriteLine("The token of the requested page was never cached, we will " + $"use the closest page we know the token for (page #{pageNumber}) and " + $"sequentially get pages from there."); currentPageNumber = pageNumber; while (!pageTokens.ContainsKey(currentPageNumber)) { currentPageNumber--; } } SearchGoogleAdsResponse response = null; // Fetches next pages in sequence and caches their tokens until the requested page // results are returned. while (currentPageNumber <= pageNumber) { // Fetches the next page. Console.WriteLine($"Fetching page #{currentPageNumber}..."); request.PageToken = pageTokens[currentPageNumber - 1]; response = googleAdsService.Search(request) .AsRawResponses().First(); CacheNextPageToken(pageTokens, response, currentPageNumber); currentPageNumber++; } // Prints the results of the requested page. Console.WriteLine($"Printing results found for the page #{pageNumber}"); foreach (GoogleAdsRow row in response.Results) { Campaign c = row.Campaign; Console.WriteLine($" - Campaign with ID {c.Id} and name '{c.Name}'"); } }
PHP
/** * Fetches and prints the results of a page of a search using a cache of page tokens. * * @param GoogleAdsServiceClient $googleAdsServiceClient the Google Ads API Service client * @param int $customerId the customer ID * @param string $searchQuery the search query * @param array $searchOptions the search options * @param int $pageNumber the number of the page to fetch and print results for * @param array &$pageTokens the cache of page tokens to use and update */ private static function fetchAndPrintPageResults( GoogleAdsServiceClient $googleAdsServiceClient, int $customerId, string $searchQuery, array $searchOptions, int $pageNumber, array &$pageTokens ) { // There is no need to fetch the pages we already know the page tokens for. if (isset($pageTokens[$pageNumber])) { printf( 'The token of the requested page was cached, we will use it to get the results.%s', PHP_EOL ); $currentPageNumber = $pageNumber; } else { printf( 'The token of the requested page was never cached, we will use the closest page ' . 'we know the token for (page #%d) and sequentially get pages from there.%s', count($pageTokens), PHP_EOL ); $currentPageNumber = count($pageTokens); } // Fetches next pages in sequence and caches their tokens until the requested page results // are returned. while ($currentPageNumber <= $pageNumber) { // Fetches the next page. printf('Fetching page #%d...%s', $currentPageNumber, PHP_EOL); $response = $googleAdsServiceClient->search( $customerId, $searchQuery, $searchOptions + [ // Uses the page token cached for the current page number. 'pageToken' => $pageTokens[$currentPageNumber] ] ); self::cacheNextPageToken($pageTokens, $response->getPage(), $currentPageNumber); $currentPageNumber++; } // Prints the results of the requested page. printf('Printing results found for the page #%d:%s', $pageNumber, PHP_EOL); foreach ($response->getPage()->getIterator() as $googleAdsRow) { /** @var GoogleAdsRow $googleAdsRow */ printf( " - Campaign with ID %d and name '%s'.%s", $googleAdsRow->getCampaign()->getId(), $googleAdsRow->getCampaign()->getName(), PHP_EOL ); } }
Python
def fetch_and_print_results( client, customer_id, query, page_number, page_tokens ): """Fetches and prints the results of a page using a cache of page tokens. Args: client: an initialized GoogleAdsClient instance. customer_id: a client customer ID. query: the search query. page_number: the number of the page to fetch and print results for. page_tokens: the cache of page tokens to use and update. """ current_page_number = None # There is no need to fetch the pages we already know the page tokens for. if page_tokens.get(page_number, None): print( "The token of the request page was cached, we will use it to get " "the results." ) current_page_number = page_number else: count = len(page_tokens.keys()) print( "The token of the requested page was never cached, we will use " f"the closest page we know the token for (page {count}) and " "sequentially get pages from there." ) current_page_number = count googleads_service = client.get_service("GoogleAdsService") # Fetches next pages in sequence and caches their tokens until the requested # page results are returned. while current_page_number <= page_number: # Fetches the next page. print(f"Fetching page {current_page_number}...") request = client.get_type("SearchGoogleAdsRequest") request.customer_id = customer_id request.query = query request.page_size = _PAGE_SIZE request.return_total_results_count = True # Uses the page token cached for the current page number. request.page_token = page_tokens[current_page_number] response = googleads_service.search(request=request) cache_next_page_token(page_tokens, response, current_page_number) current_page_number += 1 # Prints the results of the requested page. print(f"Printing results found for the page {page_number}.") for row in response.results: print( f" - Campaign with ID {row.campaign.id} and name " f"{row.campaign.name}." )
Ruby
def fetch_and_print_page_results(client, customer_id, query, page_size, return_total_results_count, page_number, page_tokens) if page_tokens.has_key?(page_number) puts 'The page token for the request page was cached. Reusing it.' current_page = page_number else puts "The token for the requested page has not been cached yet. We will start " \ "at page #{page_tokens.size} and request and cache pages until we find it." current_page = page_tokens.size end while current_page <= page_number puts page_tokens response = client.service.google_ads.search( customer_id: customer_id, query: query, page_size: page_size, return_total_results_count: return_total_results_count, page_token: page_tokens[current_page], ) cache_next_page_token(page_tokens, response.page, current_page + 1) current_page += 1 end puts "Printing results found for page #{page_number}." response.page.response.results.each do |result| puts "- Campaign with ID #{result.campaign.id} and name #{result.campaign.name}." end end
Perl
# Fetches and prints the results of a page of a search using a cache of page tokens. sub fetch_and_print_page_results { my ( $api_client, $customer_id, $query, $search_options, $page_number, $page_tokens ) = @_; my $current_page_number = undef; # There is no need to fetch the pages we already know the page tokens for. if (exists $page_tokens->{$page_number}) { print "The token of the requested page was cached, " . "we will use it to get the results.\n"; $current_page_number = $page_number; } else { printf "The token of the requested page was never cached, " . "we will use the closest page we know the token for (page #%d) " . "and sequentially get pages from there.\n", scalar keys %$page_tokens; $current_page_number = scalar keys %$page_tokens; } # Fetch next pages in sequence and cache their tokens until the requested page # results are returned. my $response = undef; while ($current_page_number <= $page_number) { # Fetch the next page. printf "Fetching page #%d...\n", $current_page_number; $response = $api_client->GoogleAdsService()->search({ customerId => $customer_id, query => $query, %$search_options, # Use the page token cached for the current page number. pageToken => $page_tokens->{$current_page_number}}); cache_next_page_token($page_tokens, $response, $current_page_number); $current_page_number++; } # Print the results of the requested page. printf "Printing results found for the page #%d:\n", $page_number; foreach my $google_ads_row (@{$response->{results}}) { printf " - Campaign with ID %d and name '%s'.\n", $google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name}; } }
Code examples
Check out our code examples of some common functions in the Google Ads API.