Search For Language And Carrier Constants

Java

// Copyright 2020 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
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// 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.

package com.google.ads.googleads.examples.targeting;

import com.beust.jcommander.Parameter;
import com.google.ads.googleads.examples.utils.ArgumentNames;
import com.google.ads.googleads.examples.utils.CodeSampleParams;
import com.google.ads.googleads.lib.GoogleAdsClient;
import com.google.ads.googleads.v13.errors.GoogleAdsError;
import com.google.ads.googleads.v13.errors.GoogleAdsException;
import com.google.ads.googleads.v13.resources.CarrierConstant;
import com.google.ads.googleads.v13.resources.LanguageConstant;
import com.google.ads.googleads.v13.services.GoogleAdsRow;
import com.google.ads.googleads.v13.services.GoogleAdsServiceClient;
import com.google.ads.googleads.v13.services.SearchGoogleAdsStreamRequest;
import com.google.ads.googleads.v13.services.SearchGoogleAdsStreamResponse;
import com.google.api.gax.rpc.ServerStream;
import java.io.FileNotFoundException;
import java.io.IOException;

/**
 * Illustrates how to:
 *
 * <ul>
 *   <li>Search for language constants where the name includes a given string.
 *   <li>Search for all the available mobile carrier constants with a given country code.
 * </ul>
 */
public class SearchForLanguageAndCarrierConstants {

  private static class SearchForLanguageAndCarrierConstantsParams extends CodeSampleParams {

    @Parameter(names = ArgumentNames.CUSTOMER_ID, required = true)
    private Long customerId;

    @Parameter(names = ArgumentNames.LANGUAGE_NAME)
    private String languageName = "eng";

    @Parameter(
        names = ArgumentNames.CARRIER_COUNTRY_CODE,
        description =
            "Country code for carrier constant filtering. A list of country codes can be"
                + " referenced here:"
                + " https://developers.google.com/google-ads/api/reference/data/geotargets.")
    private String countryCode = "US";
  }

  public static void main(String[] args) {
    SearchForLanguageAndCarrierConstantsParams params =
        new SearchForLanguageAndCarrierConstantsParams();
    if (!params.parseArguments(args)) {

      // Either pass the required parameters for this example on the command line, or insert them
      // into the code here. See the parameter class definition above for descriptions.
      params.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");

      // Optional: specify the language name or country code.
      // params.languageName = "INSERT_LANGUAGE_NAME_HERE";
      // params.countryCode = "INSERT_COUNTRY_CODE_HERE";
    }

    GoogleAdsClient googleAdsClient = null;
    try {
      googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
    } catch (FileNotFoundException fnfe) {
      System.err.printf(
          "Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
      System.exit(1);
    } catch (IOException ioe) {
      System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
      System.exit(1);
    }

    try {
      new SearchForLanguageAndCarrierConstants()
          .runExample(googleAdsClient, params.customerId, params.languageName, params.countryCode);
    } catch (GoogleAdsException gae) {
      // GoogleAdsException is the base class for most exceptions thrown by an API request.
      // Instances of this exception have a message and a GoogleAdsFailure that contains a
      // collection of GoogleAdsErrors that indicate the underlying causes of the
      // GoogleAdsException.
      System.err.printf(
          "Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
          gae.getRequestId());
      int i = 0;
      for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
        System.err.printf("  Error %d: %s%n", i++, googleAdsError);
      }
      System.exit(1);
    }
  }

  /**
   * Runs the example.
   *
   * @param googleAdsClient the Google Ads API client.
   * @param customerId the client customer ID.
   * @param languageName the string to use for searching for language constants.
   * @param countryCode the country code for searching for carrier constants.
   * @throws GoogleAdsException if an API request failed with one or more service errors.
   */
  private void runExample(
      GoogleAdsClient googleAdsClient, long customerId, String languageName, String countryCode) {
    searchForLanguageConstants(googleAdsClient, customerId, languageName);
    searchForCarrierConstants(googleAdsClient, customerId, countryCode);
  }

  /**
   * Searches for language constants where the name includes the specified language name.
   *
   * @param googleAdsClient the Google Ads API client.
   * @param customerId the client customer ID.
   * @param languageName the string to use for searching for language constants.
   */
  private void searchForLanguageConstants(
      GoogleAdsClient googleAdsClient, long customerId, String languageName) {
    try (GoogleAdsServiceClient googleAdsServiceClient =
        googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {

      // Creates a query that retrieves each language constant with the language name parameter in
      // the name.
      String searchQuery =
          "SELECT language_constant.id, "
              + "language_constant.code, "
              + "language_constant.name, "
              + "language_constant.targetable "
              + "FROM language_constant "
              + "WHERE language_constant.name LIKE '%"
              + languageName
              + "%'";

      // Constructs the SearchGoogleAdsStreamRequest.
      SearchGoogleAdsStreamRequest request =
          SearchGoogleAdsStreamRequest.newBuilder()
              .setCustomerId(Long.toString(customerId))
              .setQuery(searchQuery)
              .build();

      // Creates and issues a search Google Ads stream request that will retrieve all of the
      // requested field values for the matching language constants.
      ServerStream<SearchGoogleAdsStreamResponse> stream =
          googleAdsServiceClient.searchStreamCallable().call(request);

      for (SearchGoogleAdsStreamResponse response : stream) {
        for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
          LanguageConstant languageConstant = googleAdsRow.getLanguageConstant();
          System.out.printf(
              "Language with ID %d, code '%s', name '%s', and targetable '%s' was found.%n",
              languageConstant.getId(),
              languageConstant.getCode(),
              languageConstant.getName(),
              languageConstant.getTargetable());
        }
      }
    }
  }

  /**
   * Searches for all the available mobile carrier constants with a given country code.
   *
   * @param googleAdsClient the Google Ads API client.
   * @param customerId the client customer ID.
   * @param countryCode the country code to use for filtering.
   */
  private void searchForCarrierConstants(
      GoogleAdsClient googleAdsClient, long customerId, String countryCode) {
    try (GoogleAdsServiceClient googleAdsServiceClient =
        googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {

      // Creates a query that retrieves each language constant with the language name parameter in
      // the name.
      String searchQuery =
          String.format(
              "SELECT carrier_constant.id, "
                  + "carrier_constant.name, "
                  + "carrier_constant.country_code "
                  + "FROM carrier_constant "
                  + "WHERE carrier_constant.country_code = '%s'",
              countryCode);

      // Constructs the SearchGoogleAdsStreamRequest.
      SearchGoogleAdsStreamRequest request =
          SearchGoogleAdsStreamRequest.newBuilder()
              .setCustomerId(Long.toString(customerId))
              .setQuery(searchQuery)
              .build();

      // Creates and issues a search Google Ads stream request that will retrieve all of the
      // requested field values for the matching carrier constants.
      ServerStream<SearchGoogleAdsStreamResponse> stream =
          googleAdsServiceClient.searchStreamCallable().call(request);

      for (SearchGoogleAdsStreamResponse response : stream) {
        for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
          CarrierConstant carrierConstant = googleAdsRow.getCarrierConstant();
          System.out.printf(
              "Carrier with ID %d, name '%s', and country code '%s' was found.%n",
              carrierConstant.getId(), carrierConstant.getName(), carrierConstant.getCountryCode());
        }
      }
    }
  }
}

      

C#

// Copyright 2020 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
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// 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.

using CommandLine;
using Google.Ads.Gax.Examples;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V13.Errors;
using Google.Ads.GoogleAds.V13.Resources;
using Google.Ads.GoogleAds.V13.Services;
using System;
using System.Collections.Generic;

namespace Google.Ads.GoogleAds.Examples.V13
{
    /// <summary>
    /// This code example illustrates how to search for language constants by name that
    /// includes the specified keyword. Then it searches for all the available mobile carrier
    /// constants with a given country code.
    /// </summary>
    public class SearchForLanguageAndCarrierConstants : ExampleBase
    {
        /// <summary>
        /// Command line options for running the <see cref="SearchForLanguageAndCarrierConstants"/>
        /// example.
        /// </summary>
        public class Options : OptionsBase
        {
            /// <summary>
            /// The Google Ads customer ID for which the call is made.
            /// </summary>
            [Option("customerId", Required = true, HelpText =
                "The Google Ads customer ID for which the call is made.")]
            public long CustomerId { get; set; }

            /// <summary>
            /// The language name to search for.
            /// </summary>
            [Option("languageName", Required = true, HelpText =
                "The language name to search for.")]
            public string LanguageName { get; set; }

            /// <summary>
            /// The country code to search for carrier code.
            /// </summary>
            [Option("carrierCountryCode", Required = true, HelpText =
                "The country code to search for carrier code.")]
            public string CarrierCountryCode { get; set; }
        }

        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            Options options = ExampleUtilities.ParseCommandLine<Options>(args);

            SearchForLanguageAndCarrierConstants codeExample =
                new SearchForLanguageAndCarrierConstants();
            Console.WriteLine(codeExample.Description);
            codeExample.Run(new GoogleAdsClient(),
                options.CustomerId,
                options.LanguageName,
                options.CarrierCountryCode);
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description =>
            "This code example illustrates how to search for language constants by name that " +
            "includes the specified keyword. Then it searches for all the available mobile " +
            "carrier constants with a given country code.";

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="customerId">The Google Ads customer ID for which the call is made.</param>
        /// <param name="languageName">The language name to search for.</param>
        /// <param name="carrierCountryCode">The country code for which the search is performed.
        /// A list of country codes can be referenced here:
        /// https://developers.google.com/google-ads/api/reference/data/geotargets.
        /// </param>
        public void Run(GoogleAdsClient client, long customerId, string languageName,
            string carrierCountryCode)
        {
            try
            {
                SearchTargetableLanguages(client, customerId, languageName);
                SearchTargetableCarriers(client, customerId, carrierCountryCode);
            }
            catch (GoogleAdsException e)
            {
                Console.WriteLine("Failure:");
                Console.WriteLine($"Message: {e.Message}");
                Console.WriteLine($"Failure: {e.Failure}");
                Console.WriteLine($"Request ID: {e.RequestId}");
                throw;
            }
        }

        /// <summary>
        /// Searches the targetable carriers by country code.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="customerId">The Google Ads customer ID for which the call is made.</param>
        /// <param name="countryCode">The country code.</param>
        private void SearchTargetableCarriers(GoogleAdsClient client, long customerId,
            string countryCode)
        {
            // Get the GoogleAdsService.
            GoogleAdsServiceClient googleAdsService =
                client.GetService(Services.V13.GoogleAdsService);

            // Create a query that retrieves the targetable carriers by country code.
            string query = $"SELECT carrier_constant.id, carrier_constant.name, " +
                $"carrier_constant.country_code FROM carrier_constant " +
                $"WHERE carrier_constant.country_code = '{countryCode}'";

            // Issue a search request.
            googleAdsService.SearchStream(customerId.ToString(), query,
                delegate (SearchGoogleAdsStreamResponse resp)
                {
                    // Display the results.
                    foreach (GoogleAdsRow criterionRow in resp.Results)
                    {
                        CarrierConstant carrier = criterionRow.CarrierConstant;
                        Console.WriteLine($"Carrier with ID {carrier.Id}, name '{carrier.Name}' " +
                            $"and country code '{carrier.CountryCode}' was found.");
                    }
                });
        }

        /// <summary>
        /// Search for targetable languages by their name.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="customerId">The Google Ads customer ID for which the call is made.</param>
        /// <param name="languageName">The language name to search for.</param>
        private void SearchTargetableLanguages(GoogleAdsClient client, long customerId,
            string languageName)
        {
            // Get the GoogleAdsService.
            GoogleAdsServiceClient googleAdsService =
                client.GetService(Services.V13.GoogleAdsService);

            // Create a query that retrieves the language constants by the keyword included
            // in the name.
            string query = $"SELECT language_constant.id, language_constant.code, " +
                $"language_constant.name, language_constant.targetable " +
                $"FROM language_constant " +
                $"WHERE language_constant.name LIKE '%{languageName}%'";

            // Issue a search request.
            googleAdsService.SearchStream(customerId.ToString(), query,
                delegate (SearchGoogleAdsStreamResponse resp)
                {
                    foreach (GoogleAdsRow criterionRow in resp.Results)
                    {
                        LanguageConstant language = criterionRow.LanguageConstant;
                        // Display the results.
                        Console.WriteLine($"Language with ID {language.Id}, code " +
                            $"'{language.Code}', name '{language.Name}'and targetable:" +
                            $" '{language.Targetable}' was found.");
                    }
                });
        }
    }
}

      

PHP

<?php

/**
 * Copyright 2020 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
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * 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.
 */

namespace Google\Ads\GoogleAds\Examples\Targeting;

require __DIR__ . '/../../vendor/autoload.php';

use GetOpt\GetOpt;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentNames;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentParser;
use Google\Ads\GoogleAds\Lib\V13\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V13\GoogleAdsClientBuilder;
use Google\Ads\GoogleAds\Lib\V13\GoogleAdsException;
use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V13\GoogleAdsServerStreamDecorator;
use Google\Ads\GoogleAds\V13\Errors\GoogleAdsError;
use Google\Ads\GoogleAds\V13\Services\GoogleAdsRow;
use Google\Ads\GoogleAds\V13\Services\GoogleAdsServiceClient;
use Google\ApiCore\ApiException;

/**
 * This example illustrates how to:
 * 1. Search for language constants where the name includes a given string.
 * 2. Search for all the available mobile carrier constants with a given country code.
 */
class SearchForLanguageAndCarrierConstants
{
    private const CUSTOMER_ID = 'INSERT_CUSTOMER_ID_HERE';
    private const LANGUAGE_NAME = 'eng';
    // A list of country codes can be referenced here:
    // https://developers.google.com/adwords/api/docs/appendix/geotargeting.
    private const CARRIER_COUNTRY_CODE = 'US';

    public static function main()
    {
        // Either pass the required parameters for this example on the command line, or insert them
        // into the constants above.
        $options = (new ArgumentParser())->parseCommandArguments([
            ArgumentNames::CUSTOMER_ID => GetOpt::REQUIRED_ARGUMENT,
            ArgumentNames::LANGUAGE_NAME => GetOpt::OPTIONAL_ARGUMENT,
            ArgumentNames::CARRIER_COUNTRY_CODE => GetOpt::OPTIONAL_ARGUMENT
        ]);

        // Generate a refreshable OAuth2 credential for authentication.
        $oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();

        // Construct a Google Ads client configured from a properties file and the
        // OAuth2 credentials above.
        $googleAdsClient = (new GoogleAdsClientBuilder())
            ->fromFile()
            ->withOAuth2Credential($oAuth2Credential)
            ->build();

        try {
            self::runExample(
                $googleAdsClient,
                $options[ArgumentNames::CUSTOMER_ID] ?: self::CUSTOMER_ID,
                $options[ArgumentNames::LANGUAGE_NAME] ?: self::LANGUAGE_NAME,
                $options[ArgumentNames::CARRIER_COUNTRY_CODE] ?: self::CARRIER_COUNTRY_CODE
            );
        } catch (GoogleAdsException $googleAdsException) {
            printf(
                "Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
                $googleAdsException->getRequestId(),
                PHP_EOL,
                PHP_EOL
            );
            foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {
                /** @var GoogleAdsError $error */
                printf(
                    "\t%s: %s%s",
                    $error->getErrorCode()->getErrorCode(),
                    $error->getMessage(),
                    PHP_EOL
                );
            }
            exit(1);
        } catch (ApiException $apiException) {
            printf(
                "ApiException was thrown with message '%s'.%s",
                $apiException->getMessage(),
                PHP_EOL
            );
            exit(1);
        }
    }

    /**
     * Runs the example.
     *
     * @param GoogleAdsClient $googleAdsClient the Google Ads API client
     * @param int $customerId the customer ID
     * @param string $languageName the string included in the language name to search for
     * @param string $carrierCountryCode the code of the country where the mobile carriers are
     *      located, e.g. "US", "ES", etc.
     */
    public static function runExample(
        GoogleAdsClient $googleAdsClient,
        int $customerId,
        string $languageName,
        string $carrierCountryCode
    ) {
        $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();

        self::searchForLanguageConstants($googleAdsServiceClient, $customerId, $languageName);
        self::searchForCarrierConstants($googleAdsServiceClient, $customerId, $carrierCountryCode);
    }

    /**
     * Searches for language constants where the name includes a given string.
     *
     * @param GoogleAdsServiceClient $googleAdsServiceClient the Google Ads Service API client
     * @param int $customerId the customer ID
     * @param string $languageName the string included in the language name to search for
     */
    public static function searchForLanguageConstants(
        GoogleAdsServiceClient $googleAdsServiceClient,
        int $customerId,
        string $languageName
    ) {
        // Creates a query that retrieves the language constants where the name includes a given
        // string.
        $query = sprintf(
            'SELECT language_constant.id, language_constant.code, ' .
            'language_constant.name, language_constant.targetable ' .
            'FROM language_constant ' .
            'WHERE language_constant.name LIKE "%%%s%%"',
            $languageName
        );

        // Issues a search stream request.
        /** @var GoogleAdsServerStreamDecorator $stream */
        $stream = $googleAdsServiceClient->searchStream($customerId, $query);

        // Iterates over all rows in all messages and prints the requested field values for
        // the language constant in each row.
        foreach ($stream->iterateAllElements() as $googleAdsRow) {
            /** @var GoogleAdsRow $googleAdsRow */
            printf(
                'Language with ID %d, code "%s", name "%s" and targetable "%s" was found.%s',
                $googleAdsRow->getLanguageConstant()->getId(),
                $googleAdsRow->getLanguageConstant()->getCode(),
                $googleAdsRow->getLanguageConstant()->getName(),
                $googleAdsRow->getLanguageConstant()->getTargetable(),
                PHP_EOL
            );
        }
    }

    /**
     * Searches for all the available mobile carrier constants with a given country code.
     *
     * @param GoogleAdsServiceClient $googleAdsServiceClient the Google Ads Service API client
     * @param int $customerId the customer ID
     * @param string $carrierCountryCode the code of the country where the mobile carriers are
     *      located, e.g. "US", "ES", etc.
     */
    public static function searchForCarrierConstants(
        GoogleAdsServiceClient $googleAdsServiceClient,
        int $customerId,
        string $carrierCountryCode
    ) {
        // Creates a query that retrieves the targetable carrier constants by country code.
        $query = sprintf(
            'SELECT carrier_constant.id, carrier_constant.name, carrier_constant.country_code ' .
            'FROM carrier_constant ' .
            'WHERE carrier_constant.country_code = "%s"',
            $carrierCountryCode
        );

        // Issues a search stream request.
        /** @var GoogleAdsServerStreamDecorator $stream */
        $stream = $googleAdsServiceClient->searchStream($customerId, $query);

        // Iterates over all rows in all messages and prints the requested field values for
        // the carrier constant in each row.
        foreach ($stream->iterateAllElements() as $googleAdsRow) {
            /** @var GoogleAdsRow $googleAdsRow */
            printf(
                'Carrier with ID %d, name "%s" and country code "%s" was found.%s',
                $googleAdsRow->getCarrierConstant()->getId(),
                $googleAdsRow->getCarrierConstant()->getName(),
                $googleAdsRow->getCarrierConstant()->getCountryCode(),
                PHP_EOL
            );
        }
    }
}

SearchForLanguageAndCarrierConstants::main();

      

Python

#!/usr/bin/env python
# Copyright 2020 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
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# 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.
"""Demonstrates how to search for language and mobile carrier constants.

Specifically, this example illustrates how to:
1. Search for language constants where the name includes a given string.
2. Search for all the available mobile carrier constants with a given country
    code.
"""


import argparse
import sys

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException


def main(client, customer_id, language_name, carrier_country_code):
    """Demonstrates how to search for language and mobile carrier constants.

    Args:
        client: An initialized Google Ads API client.
        customer_id: The Google Ads customer ID.
        language_name: String included in the language name to search for.
        carrier_country_code: String code of the country where the mobile
            carriers are located.
    """
    search_for_language_constants(client, customer_id, language_name)
    search_for_carrier_constants(client, customer_id, carrier_country_code)


def search_for_language_constants(client, customer_id, language_name):
    """Searches for language constants where the name includes a given string.

    Args:
        client: An initialized Google Ads API client.
        customer_id: The Google Ads customer ID.
        language_name: String included in the language name to search for.
    """
    # Get the GoogleAdsService client.
    googleads_service = client.get_service("GoogleAdsService")

    # Create a query that retrieves the language constants where the name
    # includes a given string.
    query = f"""
        SELECT
          language_constant.id,
          language_constant.code,
          language_constant.name,
          language_constant.targetable
        FROM language_constant
        WHERE language_constant.name LIKE '%{language_name}%'"""

    # Issue a search request and process the stream response to print the
    # requested field values for the carrier constant in each row.
    stream = googleads_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        for row in batch.results:
            print(
                f"Language with ID {row.language_constant.id}, "
                f"code '{row.language_constant.code}', "
                f"name '{row.language_constant.name}', "
                f"and targetable '{row.language_constant.targetable}' "
                "was found."
            )


def search_for_carrier_constants(client, customer_id, carrier_country_code):
    """Searches for mobile carrier constants with a given country code.

    Args:
        client: An initialized Google Ads API client.
        customer_id: The Google Ads customer ID.
        carrier_country_code: String code of the country where the mobile
            carriers are located.
    """
    # Get the GoogleAdsService client.
    googleads_service = client.get_service("GoogleAdsService")

    # Create a query that retrieves the targetable carrier constants by country
    # code.
    query = f"""
        SELECT
          carrier_constant.id,
          carrier_constant.name,
          carrier_constant.country_code
        FROM carrier_constant
        WHERE carrier_constant.country_code = '{carrier_country_code}'"""

    # Issue a search request and process the stream response to print the
    # requested field values for the carrier constant in each row.
    stream = googleads_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        for row in batch.results:
            print(
                f"Carrier with ID {row.carrier_constant.id}, "
                f"name '{row.carrier_constant.name}', "
                f"and country code '{row.carrier_constant.country_code}' "
                "was found."
            )


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=(
            "Demonstrates how to search for language and mobile carrier "
            "constants."
        )
    )
    # 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",
        "--language_name",
        type=str,
        required=False,
        default="eng",
        help="Optional, string included in the language name to search for.",
    )
    parser.add_argument(
        "-p",
        "--carrier_country_code",
        type=str,
        required=False,
        default="US",
        help=(
            "Optional, string code of the country where the mobile carriers "
            "are located, e.g. 'US', 'ES', etc. "
            "A list of country codes can be referenced here: "
            "https://developers.google.com/google-ads/api/reference/data/geotargets"
        ),
    )
    args = parser.parse_args()

    try:
        main(
            googleads_client,
            args.customer_id,
            args.language_name,
            args.carrier_country_code,
        )
    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

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright:: Copyright 2020 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
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# 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.
#
# This example illustrates how to:
# 1. Search for language constants where the name includes a given string.
# 2. Search for all the available mobile carrier constants with a given
# country code.

require 'optparse'
require 'google/ads/google_ads'

def search_for_language_and_carrier_constants(
  customer_id,
  language_name,
  carrier_country_code
)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  search_for_language_constants(client, customer_id, language_name)
  search_for_carrier_constants(client, customer_id, carrier_country_code)
end

def search_for_language_constants(client, customer_id, language_name)
  # Creates a query that retrieves the language constants where the name
  # includes a given string.
  query = <<~QUERY
    SELECT language_constant.id, language_constant.code,
           language_constant.name, language_constant.targetable
    FROM language_constant
    WHERE language_constant.name LIKE '%#{language_name}%'
  QUERY

  # Issues a search stream request.
  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: query,
  )

  # Iterates over all rows in all messages and prints the requested field
  # values for the language constant in each row.
  responses.each do |response|
    response.results.each do |row|
      c = row.language_constant
      puts "Language with ID #{c.id}, code #{c.code}, name #{c.name} and "\
        "targetable #{c.targetable} was found."
    end
  end
end

def search_for_carrier_constants(client, customer_id, carrier_country_code)
  # Creates a query that retrieves the targetable carrier constants
  # by country code.
  query = <<~QUERY
    SELECT carrier_constant.id, carrier_constant.name,
           carrier_constant.country_code
    FROM carrier_constant
    WHERE carrier_constant.country_code = '#{carrier_country_code}'
  QUERY

  # Issues a search stream request.
  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: query,
  )

  # Iterates over all rows in all messages and prints the requested field
  # values for the carrier constant in each row.
  responses.each do |response|
    response.results.each do |row|
      c = row.carrier_constant
      puts "Carrier with ID #{c.id}, name #{c.name} and "\
        "country code #{c.country_code} was found."
    end
  end
end

if __FILE__ == $PROGRAM_NAME
  options = {}

  # Default values for language name and carrier country code
  options[:language_name] = "eng"
  options[:carrier_country_code] = "US"

  # Running the example with -h will print the command line usage.
  OptionParser.new do |opts|
    opts.banner = sprintf('Usage: ruby %s [options]', File.basename(__FILE__))

    opts.separator ''
    opts.separator 'Options:'

    opts.on('-C', '--customer-id CUSTOMER-ID', String, 'Customer ID') do |v|
      options[:customer_id] = v
    end

    opts.on('-L', '--language-name LANGUAGE-NAME', String, 'Language Name') do |v|
      options[:language_name] = v
    end

    opts.on('-R', '--carrier-country-code CARRIER-COUNTRY-CODE', String, 'Carrier Country Code') do |v|
      options[:carrier_country_code] = v
    end

    opts.separator ''
    opts.separator 'Help:'

    opts.on_tail('-h', '--help', 'Show this message') do
      puts opts
      exit
    end
  end.parse!

  begin
    search_for_language_and_carrier_constants(
      options.fetch(:customer_id).tr("-", ""),
      options[:language_name],
      options[:carrier_country_code],
    )
  rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
    e.failure.errors.each do |error|
      STDERR.printf("Error with message: %s\n", error.message)
      if error.location
        error.location.field_path_elements.each do |field_path_element|
          STDERR.printf("\tOn field: %s\n", field_path_element.field_name)
        end
      end
      error.error_code.to_h.each do |k, v|
        next if v == :UNSPECIFIED
        STDERR.printf("\tType: %s\n\tCode: %s\n", k, v)
      end
    end
    raise
  end
end

      

Perl

#!/usr/bin/perl -w
#
# Copyright 2020, 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
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 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.
#
# This example illustrates how to:
# 1. Search for language constants where the name includes a given string.
# 2. Search for all the available mobile carrier constants with a given country code.

use strict;
use warnings;
use utf8;

use FindBin qw($Bin);
use lib "$Bin/../../lib";
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::Utils::GoogleAdsHelper;
use Google::Ads::GoogleAds::Utils::SearchStreamHandler;
use
  Google::Ads::GoogleAds::V13::Services::GoogleAdsService::SearchGoogleAdsStreamRequest;

use Getopt::Long qw(:config auto_help);
use Pod::Usage;
use Cwd qw(abs_path);

# The following parameter(s) should be provided to run the example. You can
# either specify these by changing the INSERT_XXX_ID_HERE values below, or on
# the command line.
#
# Parameters passed on the command line will override any parameters set in
# code.
#
# Running the example with -h will print the command line usage.
my $customer_id   = "INSERT_CUSTOMER_ID_HERE";
my $language_name = "eng";
# A list of country codes can be referenced here:
# https://developers.google.com/google-ads/api/reference/data/geotargets.
my $carrier_country_code = "US";

sub search_for_language_and_carrier_constants {
  my ($api_client, $customer_id, $language_name, $carrier_country_code) = @_;

  search_for_language_constants($api_client, $customer_id, $language_name);

  search_for_carrier_constants($api_client, $customer_id,
    $carrier_country_code);

  return 1;
}

# Searches for language constants where the name includes a given string.
sub search_for_language_constants {
  my ($api_client, $customer_id, $language_name) = @_;

  # Create a query that retrieves the language constants where the name includes
  # a given string.
  my $search_query =
    "SELECT language_constant.id, language_constant.code, " .
    "language_constant.name, language_constant.targetable " .
    "FROM language_constant " .
    "WHERE language_constant.name LIKE '%$language_name%'";

  # Create a search Google Ads stream request that will retrieve the language
  # constants.
  my $search_stream_request =
    Google::Ads::GoogleAds::V13::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      => $search_query
    });

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

  # Issue a search request and process the stream response to print the requested
  # field values for the language constant in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf "Language with ID %d, code '%s', name '%s' " .
        "and targetable '%s' was found.\n",
        $google_ads_row->{languageConstant}{id},
        $google_ads_row->{languageConstant}{code},
        $google_ads_row->{languageConstant}{name},
        to_boolean($google_ads_row->{languageConstant}{targetable});
    });
}

# Searches for all the available mobile carrier constants with a given country code.
sub search_for_carrier_constants {
  my ($api_client, $customer_id, $carrier_country_code) = @_;

  # Create a query that retrieves the targetable carrier constants by country code.
  my $search_query =
    "SELECT carrier_constant.id, carrier_constant.name, " .
    "carrier_constant.country_code FROM carrier_constant " .
    "WHERE carrier_constant.country_code = '$carrier_country_code'";

  # Create a search Google Ads stream request that will retrieve the carrier
  # constants.
  my $search_stream_request =
    Google::Ads::GoogleAds::V13::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      => $search_query
    });

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

  # Issue a search request and process the stream response to print the requested
  # field values for the carrier constant in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf
        "Carrier with ID %d, name '%s' and country code '%s' was found.\n",
        $google_ads_row->{carrierConstant}{id},
        $google_ads_row->{carrierConstant}{name},
        $google_ads_row->{carrierConstant}{countryCode};
    });
}

# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
  return 1;
}

# Get Google Ads Client, credentials will be read from ~/googleads.properties.
my $api_client = Google::Ads::GoogleAds::Client->new();

# By default examples are set to die on any server returned fault.
$api_client->set_die_on_faults(1);

# Parameters passed on the command line will override any parameters set in code.
GetOptions(
  "customer_id=s"          => \$customer_id,
  "language_name=s"        => \$language_name,
  "carrier_country_code=s" => \$carrier_country_code,
);

# Print the help message if the parameters are not initialized in the code nor
# in the command line.
pod2usage(2)
  if not check_params($customer_id, $language_name, $carrier_country_code);

# Call the example.
search_for_language_and_carrier_constants($api_client, $customer_id,
  $language_name, $carrier_country_code);

=pod

=head1 NAME

search_for_language_and_carrier_constants

=head1 DESCRIPTION

This example illustrates how to:
1. Search for language constants where the name includes a given string.
2. Search for all the available mobile carrier constants with a given country code.

=head1 SYNOPSIS

search_for_language_and_carrier_constants.pl [options]

    -help                       Show the help message.
    -customer_id                The Google Ads customer ID.
    -language_name              [optional] The string included in the language
                                name to search for.
    -carrier_country_code       [optional] The code of the country where the mobile
                                carriers are located, e.g. "US", "ES", etc.

=cut