טירגוט למיקום גיאוגרפי

במדריך הזה מתוארים טירגוט למיקום גיאוגרפי והדרכים שבהן אפשר להשתמש ב-Google Ads API כדי להוסיף, לאחזר ולעדכן טירגוט למיקום גיאוגרפי בקמפיינים.

למה חשוב להשתמש בטירגוט גיאוגרפי?

טירגוט למיקום גיאוגרפי מאפשר לכם להציג מודעות למשתמשים באזור גיאוגרפי מסוים. לדוגמה, נניח שאתם מפרסמים רשת של סופרמרקטים. בלי טירגוט לפי מיקום, המודעות יוצגו בכל האזורים ברחבי העולם, ויכול להיות שהן יקבלו קליקים ממשתמשים באזורים שבהם אין לכם מיקומי סופרמרקטים. כך נוצרות עלויות בלי אפשרות להחזר על ההשקעה. בעזרת טירגוט למיקום, המודעות בקמפיינים יוצגו רק באזורים שבהם יש לכם סופרמרקטים פתוחים. הגישה הזו מאפשרת לכם לטרגט ישירות לקוחות שמחפשים סופרמרקטים באופן מקומי.

באמצעות Google Ads API אפשר לטרגט את המודעות לפי מדינה, אזור או קרבת מקום לנקודה גיאוגרפית ספציפית.

מידע נוסף על טירגוט מודעות למיקומים גיאוגרפיים

טירגוט גיאוגרפי של קמפיינים לאזור

אפשר לטרגט קמפיינים לכל אזור גיאוגרפי ש-Google Ads תומך בטירגוט למיקום שלו, למשל מדינה, מדינה (State), עיר או אזור דואר. לכל מיקום שאפשר לטרגט יש מזהה ייחודי של קריטריון. אפשר לחפש מזהה של קריטריון באמצעות GeoTargetConstantService.SuggestGeoTargetConstants. השדה resource_name של כל GeoTargetConstant הוא מהפורמט geoTargetConstants/{Criterion ID}. לדוגמה, הערך של resource_name במדינת ניו יורק הוא geoTargetConstants/21167.

אפשר להוסיף טירגוט גיאוגרפי לקמפיינים באמצעות הערך CampaignCriterionService. בקטע הקוד הבא מוסבר איך לטרגט את הקמפיין באמצעות מזהה קריטריון.

Java

private static CampaignCriterion buildLocationIdCriterion(
    long locationId, String campaignResourceName) {
  Builder criterionBuilder = CampaignCriterion.newBuilder().setCampaign(campaignResourceName);

  criterionBuilder
      .getLocationBuilder()
      .setGeoTargetConstant(ResourceNames.geoTargetConstant(locationId));

  return criterionBuilder.build();
}
AddCampaignTargetingCriteria.java
      

C#‎

private CampaignCriterion buildLocationCriterion(long locationId,
    string campaignResourceName)
{
    GeoTargetConstantName location = new GeoTargetConstantName(locationId.ToString());
    return new CampaignCriterion()
    {
        Campaign = campaignResourceName,
        Location = new LocationInfo()
        {
            GeoTargetConstant = location.ToString()
        }
    };
}
AddCampaignTargetingCriteria.cs
      

PHP

private static function createLocationCampaignCriterionOperation(
    int $locationId,
    string $campaignResourceName
) {
    // Constructs a campaign criterion for the specified campaign ID using the specified
    // location ID.
    $campaignCriterion = new CampaignCriterion([
        // Creates a location using the specified location ID.
        'location' => new LocationInfo([
            // Besides using location ID, you can also search by location names using
            // GeoTargetConstantServiceClient::suggestGeoTargetConstants() and directly
            // apply GeoTargetConstant::$resourceName here. An example can be found
            // in GetGeoTargetConstantByNames.php.
            'geo_target_constant' => ResourceNames::forGeoTargetConstant($locationId)
        ]),
        'campaign' => $campaignResourceName
    ]);

    return new CampaignCriterionOperation(['create' => $campaignCriterion]);
}
AddCampaignTargetingCriteria.php
      

Python

def create_location_op(client, customer_id, campaign_id, location_id):
    campaign_service = client.get_service("CampaignService")
    geo_target_constant_service = client.get_service("GeoTargetConstantService")

    # Create the campaign criterion.
    campaign_criterion_operation = client.get_type("CampaignCriterionOperation")
    campaign_criterion = campaign_criterion_operation.create
    campaign_criterion.campaign = campaign_service.campaign_path(
        customer_id, campaign_id
    )

    # Besides using location_id, you can also search by location names from
    # GeoTargetConstantService.suggest_geo_target_constants() and directly
    # apply GeoTargetConstant.resource_name here. An example can be found
    # in get_geo_target_constant_by_names.py.
    campaign_criterion.location.geo_target_constant = (
        geo_target_constant_service.geo_target_constant_path(location_id)
    )

    return campaign_criterion_operation
add_campaign_targeting_criteria.py
      

Ruby

def create_location(client, customer_id, campaign_id, location_id)
  client.operation.create_resource.campaign_criterion do |criterion|
    criterion.campaign = client.path.campaign(customer_id, campaign_id)

    criterion.location = client.resource.location_info do  |li|
      # Besides using location_id, you can also search by location names from
      # GeoTargetConstantService.suggest_geo_target_constants() and directly
      # apply GeoTargetConstant.resource_name here. An example can be found
      # in get_geo_target_constant_by_names.rb.
      li.geo_target_constant = client.path.geo_target_constant(location_id)
    end
  end
end
add_campaign_targeting_criteria.rb
      

Perl

sub create_location_campaign_criterion_operation {
  my ($location_id, $campaign_resource_name) = @_;

  # Construct a campaign criterion for the specified campaign using the
  # specified location ID.
  my $campaign_criterion =
    Google::Ads::GoogleAds::V19::Resources::CampaignCriterion->new({
      # Create a location using the specified location ID.
      location => Google::Ads::GoogleAds::V19::Common::LocationInfo->new({
          # Besides using location ID, you can also search by location names
          # using GeoTargetConstantService::suggest() and directly apply
          # GeoTargetConstant->{resourceName} here. An example can be found
          # in get_geo_target_constants_by_names.pl.
          geoTargetConstant =>
            Google::Ads::GoogleAds::V19::Utils::ResourceNames::geo_target_constant(
            $location_id)}
      ),
      campaign => $campaign_resource_name
    });

  return
    Google::Ads::GoogleAds::V19::Services::CampaignCriterionService::CampaignCriterionOperation
    ->new({
      create => $campaign_criterion
    });
}
add_campaign_targeting_criteria.pl
      

Google עשויה להוציא משימוש מדי פעם קריטריונים מסוימים של מיקומים מסיבות שונות: יכול להיות שהמיקום עבר ארגון מחדש לאזורים קטנים או גדולים יותר, שחלו שינויים גיאו-פוליטיים וכו'. אפשר להיעזר בשדה status של אובייקט GeoTargetConstant כדי לקבוע אם מיקום מסוים הוא ENABLED או REMOVAL_PLANNED. איך אנחנו מוציאים משימוש את הטירגוט למיקום גיאוגרפי

חיפוש לפי שם המיקום

אפשר גם לחפש את מזהה הקריטריון לפי שם המיקום באמצעות הפונקציה GeoTargetConstantService.SuggestGeoTargetConstants. בדוגמת הקוד הבאה מוסבר איך לחפש מזהה של קריטריון מיקום לפי שם המיקום.

Java

private void runExample(GoogleAdsClient googleAdsClient) {
  try (GeoTargetConstantServiceClient geoTargetClient =
      googleAdsClient.getLatestVersion().createGeoTargetConstantServiceClient()) {

    SuggestGeoTargetConstantsRequest.Builder requestBuilder =
        SuggestGeoTargetConstantsRequest.newBuilder();

    // Locale is using ISO 639-1 format. If an invalid locale is given, 'en' is used by default.
    requestBuilder.setLocale("en");

    // A list of country codes can be referenced here:
    // https://developers.google.com/google-ads/api/reference/data/geotargets
    requestBuilder.setCountryCode("FR");

    requestBuilder
        .getLocationNamesBuilder()
        .addAllNames(ImmutableList.of("Paris", "Quebec", "Spain", "Deutschland"));

    SuggestGeoTargetConstantsResponse response =
        geoTargetClient.suggestGeoTargetConstants(requestBuilder.build());

    for (GeoTargetConstantSuggestion suggestion :
        response.getGeoTargetConstantSuggestionsList()) {
      System.out.printf(
          "%s (%s,%s,%s,%s) is found in locale (%s) with reach (%d) for search term (%s).%n",
          suggestion.getGeoTargetConstant().getResourceName(),
          suggestion.getGeoTargetConstant().getName(),
          suggestion.getGeoTargetConstant().getCountryCode(),
          suggestion.getGeoTargetConstant().getTargetType(),
          suggestion.getGeoTargetConstant().getStatus().name(),
          suggestion.getLocale(),
          suggestion.getReach(),
          suggestion.getSearchTerm());
    }
  }
}
GetGeoTargetConstantsByNames.java
      

C#‎

public void Run(GoogleAdsClient client)
{
    // Get the GeoTargetConstantServiceClient.
    GeoTargetConstantServiceClient geoService =
        client.GetService(Services.V19.GeoTargetConstantService);

    // Locale is using ISO 639-1 format. If an invalid locale is given,
    // 'en' is used by default.
    string locale = "en";

    // A list of country codes can be referenced here:
    // https://developers.google.com/google-ads/api/reference/data/geotargets
    string countryCode = "FR";

    string[] locations = { "Paris", "Quebec", "Spain", "Deutschland" };

    SuggestGeoTargetConstantsRequest request = new SuggestGeoTargetConstantsRequest()
    {
        Locale = locale,
        CountryCode = countryCode,
        LocationNames = new SuggestGeoTargetConstantsRequest.Types.LocationNames()
    };

    request.LocationNames.Names.AddRange(locations);

    try
    {
        SuggestGeoTargetConstantsResponse response =
            geoService.SuggestGeoTargetConstants(request);

        foreach (GeoTargetConstantSuggestion suggestion
            in response.GeoTargetConstantSuggestions)
        {
            Console.WriteLine(
                $"{suggestion.GeoTargetConstant.ResourceName} " +
                $"({suggestion.GeoTargetConstant.Name}, " +
                $"{suggestion.GeoTargetConstant.CountryCode}, " +
                $"{suggestion.GeoTargetConstant.TargetType}, " +
                $"{suggestion.GeoTargetConstant.Status}) is found in locale " +
                $"({suggestion.Locale}) with reach ({suggestion.Reach}) " +
                $"for search term ({suggestion.SearchTerm}).");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
GetGeoTargetConstantsByNames.cs
      

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    array $locationNames,
    string $locale,
    string $countryCode
) {
    $geoTargetConstantServiceClient = $googleAdsClient->getGeoTargetConstantServiceClient();

    $response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
        new SuggestGeoTargetConstantsRequest([
            'locale' => $locale,
            'country_code' => $countryCode,
            'location_names' => new LocationNames(['names' => $locationNames])
        ])
    );

    // Iterates over all geo target constant suggestion objects and prints the requested field
    // values for each one.
    foreach ($response->getGeoTargetConstantSuggestions() as $geoTargetConstantSuggestion) {
        /** @var GeoTargetConstantSuggestion $geoTargetConstantSuggestion */
        printf(
            "Found '%s' ('%s','%s','%s',%s) in locale '%s' with reach %d"
            . " for the search term '%s'.%s",
            $geoTargetConstantSuggestion->getGeoTargetConstant()->getResourceName(),
            $geoTargetConstantSuggestion->getGeoTargetConstant()->getName(),
            $geoTargetConstantSuggestion->getGeoTargetConstant()->getCountryCode(),
            $geoTargetConstantSuggestion->getGeoTargetConstant()->getTargetType(),
            GeoTargetConstantStatus::name(
                $geoTargetConstantSuggestion->getGeoTargetConstant()->getStatus()
            ),
            $geoTargetConstantSuggestion->getLocale(),
            $geoTargetConstantSuggestion->getReach(),
            $geoTargetConstantSuggestion->getSearchTerm(),
            PHP_EOL
        );
    }
}
GetGeoTargetConstantsByNames.php
      

Python

def main(client):
    gtc_service = client.get_service("GeoTargetConstantService")

    gtc_request = client.get_type("SuggestGeoTargetConstantsRequest")

    gtc_request.locale = LOCALE
    gtc_request.country_code = COUNTRY_CODE

    # The location names to get suggested geo target constants.
    gtc_request.location_names.names.extend(
        ["Paris", "Quebec", "Spain", "Deutschland"]
    )

    results = gtc_service.suggest_geo_target_constants(gtc_request)

    for suggestion in results.geo_target_constant_suggestions:
        geo_target_constant = suggestion.geo_target_constant
        print(
            f"{geo_target_constant.resource_name} "
            f"({geo_target_constant.name}, "
            f"{geo_target_constant.country_code}, "
            f"{geo_target_constant.target_type}, "
            f"{geo_target_constant.status.name}) "
            f"is found in locale ({suggestion.locale}) "
            f"with reach ({suggestion.reach}) "
            f"from search term ({suggestion.search_term})."
        )
get_geo_target_constants_by_names.py
      

Ruby

def get_geo_target_constants_by_names
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  gtc_service = client.service.geo_target_constant

  location_names = client.resource.location_names do |ln|
    ['Paris', 'Quebec', 'Spain', 'Deutschland'].each do |name|
      ln.names << name
    end
  end

  # Locale is using ISO 639-1 format. If an invalid locale is given,
  # 'en' is used by default.
  locale = 'en'

  # A list of country codes can be referenced here:
  # https://developers.google.com/google-ads/api/reference/data/geotargets
  country_code = 'FR'

  response = gtc_service.suggest_geo_target_constants(
    locale: locale,
    country_code: country_code,
    location_names: location_names
  )

  response.geo_target_constant_suggestions.each do |suggestion|
    puts sprintf("%s (%s,%s,%s,%s) is found in locale (%s) with reach (%d)" \
        " from search term (%s).", suggestion.geo_target_constant.resource_name,
        suggestion.geo_target_constant.name,
        suggestion.geo_target_constant.country_code,
        suggestion.geo_target_constant.target_type,
        suggestion.geo_target_constant.status,
        suggestion.locale,
        suggestion.reach,
        suggestion.search_term)
  end
end
get_geo_target_constants_by_names.rb
      

Perl

sub get_geo_target_constants_by_names {
  my ($api_client, $location_names, $locale, $country_code) = @_;

  my $suggest_response = $api_client->GeoTargetConstantService()->suggest({
      locale        => $locale,
      countryCode   => $country_code,
      locationNames =>
        Google::Ads::GoogleAds::V19::Services::GeoTargetConstantService::LocationNames
        ->new({
          names => $location_names
        })});

  # Iterate over all geo target constant suggestion objects and print the requested
  # field values for each one.
  foreach my $geo_target_constant_suggestion (
    @{$suggest_response->{geoTargetConstantSuggestions}})
  {
    printf "Found '%s' ('%s','%s','%s',%s) in locale '%s' with reach %d" .
      " for the search term '%s'.\n",
      $geo_target_constant_suggestion->{geoTargetConstant}{resourceName},
      $geo_target_constant_suggestion->{geoTargetConstant}{name},
      $geo_target_constant_suggestion->{geoTargetConstant}{countryCode},
      $geo_target_constant_suggestion->{geoTargetConstant}{targetType},
      $geo_target_constant_suggestion->{geoTargetConstant}{status},
      $geo_target_constant_suggestion->{locale},
      $geo_target_constant_suggestion->{reach},
      $geo_target_constant_suggestion->{searchTerm};
  }

  return 1;
}
get_geo_target_constants_by_names.pl
      

טירגוט קמפיינים לפי קרבת מיקום

לפעמים כדאי לטרגט בצורה מדויקת יותר מעיר או ממדינה. לדוגמה, יכול להיות שתרצו לפרסם את הסופרמרקטים שלכם במרחק של עד 10 קילומטרים ממיקום החנות. במקרים כאלה, אפשר להשתמש בטירגוט לפי קרבה. הקוד ליצירת יעד של קרבת מקום דומה לקוד להוספת יעד מיקום, אלא שצריך ליצור אובייקט ProximityInfo במקום אובייקט LocationInfo.

Java

private static CampaignCriterion buildProximityLocation(String campaignResourceName) {
  Builder builder = CampaignCriterion.newBuilder().setCampaign(campaignResourceName);

  ProximityInfo.Builder proximityBuilder = builder.getProximityBuilder();
  proximityBuilder.setRadius(10.0).setRadiusUnits(ProximityRadiusUnits.MILES);

  AddressInfo.Builder addressBuilder = proximityBuilder.getAddressBuilder();
  addressBuilder
      .setStreetAddress("38 avenue de l'Opéra")
      .setCityName("Paris")
      .setPostalCode("75002")
      .setCountryCode("FR");

  return builder.build();
}
AddCampaignTargetingCriteria.java
      

C#‎

private CampaignCriterion buildProximityCriterion(string campaignResourceName)
{
    ProximityInfo proximity = new ProximityInfo()
    {
        Address = new AddressInfo()
        {
            StreetAddress = "38 avenue de l'Opéra",
            CityName = "Paris",
            PostalCode = "75002",
            CountryCode = "FR"
        },
        Radius = 10d,
        // Default is kilometers.
        RadiusUnits = ProximityRadiusUnits.Miles
    };

    return new CampaignCriterion()
    {
        Campaign = campaignResourceName,
        Proximity = proximity
    };
}
AddCampaignTargetingCriteria.cs
      

PHP

private static function createProximityCampaignCriterionOperation(string $campaignResourceName)
{
    // Constructs a campaign criterion as a proximity.
    $campaignCriterion = new CampaignCriterion([
        'proximity' => new ProximityInfo([
            'address' => new AddressInfo([
                'street_address' => '38 avenue de l\'Opéra',
                'city_name' => 'Paris',
                'postal_code' => '75002',
                'country_code' => 'FR',
            ]),
            'radius' => 10.0,
            // Default is kilometers.
            'radius_units' => ProximityRadiusUnits::MILES
        ]),
        'campaign' => $campaignResourceName
    ]);

    return new CampaignCriterionOperation(['create' => $campaignCriterion]);
}
AddCampaignTargetingCriteria.php
      

Python

def create_proximity_op(client, customer_id, campaign_id):
    campaign_service = client.get_service("CampaignService")

    # Create the campaign criterion.
    campaign_criterion_operation = client.get_type("CampaignCriterionOperation")
    campaign_criterion = campaign_criterion_operation.create
    campaign_criterion.campaign = campaign_service.campaign_path(
        customer_id, campaign_id
    )
    campaign_criterion.proximity.address.street_address = "38 avenue de l'Opera"
    campaign_criterion.proximity.address.city_name = "Paris"
    campaign_criterion.proximity.address.postal_code = "75002"
    campaign_criterion.proximity.address.country_code = "FR"
    campaign_criterion.proximity.radius = 10
    # Default is kilometers.
    campaign_criterion.proximity.radius_units = (
        client.enums.ProximityRadiusUnitsEnum.MILES
    )

    return campaign_criterion_operation
add_campaign_targeting_criteria.py
      

Ruby

def create_proximity(client, customer_id, campaign_id)
  client.operation.create_resource.campaign_criterion do |criterion|
    criterion.campaign = client.path.campaign(customer_id, campaign_id)

    criterion.proximity = client.resource.proximity_info do |proximity|
      proximity.address = client.resource.address_info do |address|
        address.street_address = "38 avenue de l'Opéra"
        address.city_name = "Paris"
        address.postal_code = "75002"
        address.country_code = "FR"
      end

      proximity.radius = 10
      proximity.radius_units = :MILES
    end
  end
end
add_campaign_targeting_criteria.rb
      

Perl

sub create_proximity_campaign_criterion_operation {
  my ($campaign_resource_name) = @_;

  # Construct a campaign criterion as a proximity.
  my $campaign_criterion =
    Google::Ads::GoogleAds::V19::Resources::CampaignCriterion->new({
      proximity => Google::Ads::GoogleAds::V19::Common::ProximityInfo->new({
          address => Google::Ads::GoogleAds::V19::Common::AddressInfo->new({
              streetAddress => "38 avenue de l'Opéra",
              cityName      => "cityName",
              postalCode    => "75002",
              countryCode   => "FR"
            }
          ),
          radius => 10.0,
          # Default is kilometers.
          radiusUnits => MILES
        }
      ),
      campaign => $campaign_resource_name
    });

  return
    Google::Ads::GoogleAds::V19::Services::CampaignCriterionService::CampaignCriterionOperation
    ->new({
      create => $campaign_criterion
    });
}
add_campaign_targeting_criteria.pl
      

אחזור יעדים גיאוגרפיים

אפשר לאחזר את היעדים הגיאוגרפיים של קמפיין באמצעות הפונקציה GoogleAdsService.SearchStream. אפשר לסנן את התוצאות בפסקה WHERE.

SELECT
  campaign_criterion.campaign,
  campaign_criterion.location.geo_target_constant,
  campaign_criterion.proximity.geo_point.longitude_in_micro_degrees,
  campaign_criterion.proximity.geo_point.latitude_in_micro_degrees,
  campaign_criterion.proximity.radius,
  campaign_criterion.negative
FROM campaign_criterion
WHERE
  campaign_criterion.campaign = 'customers/{customer_id}/campaigns/{campaign_id}'
  AND campaign_criterion.type IN (LOCATION, PROXIMITY)

עדכון של יעדי טירגוט גיאוגרפי

כדי לעדכן את המיקומים לטירגוט בקמפיין, צריך לאחזר את רשימת היעדים הגיאוגרפיים הקיימים ולהשוות אותה לרשימה של היעדים החדשים. לאחר מכן תוכלו להשתמש בפעולה remove כדי להסיר את היעדים שאתם לא צריכים, ובפעולה create כדי להוסיף את יעדי הטירגוט הגיאוגרפי החדשים שאתם צריכים (אבל חסרים בקמפיין הקיים).

החרגת יעדים גיאוגרפיים

אפשר גם להחריג את LocationInfo, אבל לא את ProximityInfo. התכונה הזו שימושית במיוחד אם רוצים לטרגט אזור מסוים, אבל להחריג אזור משנה (לדוגמה, לטרגט את כל ארצות הברית, מלבד ניו יורק). כדי להחריג אזור, מגדירים את השדה negative בקובץ CampaignCriterion לערך true.

טירגוט למספר אזורים גיאוגרפיים

באמצעות LocationGroupInfo, אפשר להגדיר לקמפיין טירגוט למספר אזורים גיאוגרפיים. האזור ממוקד במיקומים שמוגדרים בתוספי המיקום של הקמפיין.

הרדיוס שמוגדר ב-LocationGroupInfo מייצג אזור עגול סביב כל מיקום, והוא מורכב מאובייקט radius, אורך ו-radius_units, שיכולים להיות במטרים או במיילים (LocationGroupRadiusUnitsEnum).

אפשר לסנן את המיקומים ב-LocationGroupInfo לפי רשימה של מזהי קריטריונים לטירגוט גיאוגרפי שצוינה בשדה geo_target_constant. אם ההגדרה הזו מוגדרת, המערכת לא תבצע טירגוט למיקומים שנמצאים מחוץ למזהי הקריטריונים שצוינו.