مکان یابی

این راهنما مکان یابی و نحوه استفاده از Google Ads API را برای افزودن، بازیابی و به روز رسانی مکان یابی برای کمپین های خود شرح می دهد.

چرا هدف گذاری جغرافیایی مهم است؟

مکان یابی به شما این امکان را می دهد که تبلیغات را به کاربران در یک منطقه جغرافیایی خاص ارائه دهید. برای مثال، فرض کنید در حال تبلیغ برای سوپرمارکت های زنجیره ای هستید. بدون مکان یابی، تبلیغات شما در همه مناطق در سراسر جهان نمایش داده می شود و تبلیغات شما ممکن است از کاربران مناطقی که هیچ مکان سوپرمارکتی ندارید، کلیک دریافت کند. این باعث ایجاد هزینه می شود در حالی که امکان بازگشت سرمایه را فراهم نمی کند. با مکان یابی، کمپین های شما تبلیغات را فقط در مناطقی نشان می دهند که سوپرمارکت های باز دارید. این رویکرد همچنین به شما امکان می دهد مستقیماً مشتریانی را که به صورت محلی برای سوپرمارکت ها جستجو می کنند، هدف قرار دهید.

Google Ads API به شما امکان می دهد تبلیغات خود را بر اساس کشور، منطقه یا نزدیکی در اطراف یک نقطه جغرافیایی خاص هدف قرار دهید .

درباره هدف‌یابی تبلیغات در مکان‌های جغرافیایی بیشتر بیاموزید.

کمپین های هدف جغرافیایی برای یک منطقه

می‌توانید کمپین‌ها را به هر منطقه جغرافیایی که Google Ads از هدف‌یابی موقعیت مکانی پشتیبانی می‌کند، هدف قرار دهید، به عنوان مثال، یک کشور، یک ایالت، یک شهر یا یک منطقه پستی. هر مکان قابل هدف به طور منحصر به فرد توسط یک شناسه معیار شناسایی می شود. می‌توانید با استفاده از GeoTargetConstantService.SuggestGeoTargetConstants ، یک شناسه معیار جستجو کنید. resource_name هر GeoTargetConstant به شکل geoTargetConstants/{Criterion ID} است. به عنوان مثال، مقدار resource_name ایالت نیویورک geoTargetConstants/21167 است.

می‌توانید با استفاده از CampaignCriterionService ، اهداف جغرافیایی را به کمپین‌های خود اضافه کنید. قطعه کد زیر نحوه هدف قرار دادن کمپین خود را با شناسه معیار نشان می دهد.

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
      

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
      

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
      

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
      

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
      

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::V17::Resources::CampaignCriterion->new({
      # Create a location using the specified location ID.
      location => Google::Ads::GoogleAds::V17::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::V17::Utils::ResourceNames::geo_target_constant(
            $location_id)}
      ),
      campaign => $campaign_resource_name
    });

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

Google گاهی اوقات ممکن است برخی از معیارهای مکان را به دلایل مختلف حذف کند: مکان ممکن است به مناطق کوچکتر یا بزرگتر تغییر ساختار داده شود، تغییرات جغرافیایی سیاسی، و غیره. برای تعیین اینکه آیا یک مکان ENABLED است یا REMOVAL_PLANNED به فیلد status یک شی GeoTargetConstant مراجعه کنید. درباره نحوه حذف تدریجی اهداف مکان بیشتر بخوانید.

با نام مکان جستجو کنید

همچنین می‌توانید با استفاده از GeoTargetConstantService.SuggestGeoTargetConstants ، شناسه معیار را با نام مکان جستجو کنید. مثال کد زیر نحوه جستجوی شناسه معیار مکان را با نام مکان نشان می دهد.

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
      

public void Run(GoogleAdsClient client)
{
    // Get the GeoTargetConstantServiceClient.
    GeoTargetConstantServiceClient geoService =
        client.GetService(Services.V17.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
      

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
      

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
      

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
      

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::V17::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 کیلومتری محل فروشگاه خود تبلیغ کنید. در چنین مواردی، می توانید از هدف گذاری مجاورت استفاده کنید. کد ایجاد یک هدف نزدیکی شبیه به افزودن یک هدف موقعیت است، با این تفاوت که شما باید به جای شی LocationInfo یک شی ProximityInfo ایجاد کنید.

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
      

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
      

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
      

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
      

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
      

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

  # Construct a campaign criterion as a proximity.
  my $campaign_criterion =
    Google::Ads::GoogleAds::V17::Resources::CampaignCriterion->new({
      proximity => Google::Ads::GoogleAds::V17::Common::ProximityInfo->new({
          address => Google::Ads::GoogleAds::V17::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::V17::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 تجویز شده است، فیلتر کرد. در صورت تعریف، هیچ مکانی که خارج از شناسه معیارهای معین وجود داشته باشد، هدف قرار نخواهد گرفت.