Skip to main content
Geotargeting enables advertisers to direct campaigns to users in specific geographic locations, such as states, subregions, or cities. This feature is available for both Sponsored Listings and Sponsored Brands campaigns.

​
How It Works

​
For Sponsored Listings

1

Pre-Configuration

The client provides a JSON file mapping their geolocations, including an id and name for each location. This geolocation data is uploaded by Topsort early in the integration process, making it available for testing with the first campaigns.
2

Campaign Setup

Advertisers can select multiple regions in the Admin/Vendor Dashboard when creating their campaigns.
3

Auction Process

During an auction, the geolocation can be provided in the body of the request, using the geoTargeting.location field. The following auction request can be used to retrieve winners for clients in a specific location:
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "id": "category"
      },
      "geoTargeting": {
        "location": "new-york"
      }
    }
  ]
}

​
For Sponsored Brands

Sponsored Brands geolocation targeting works similarly but uses a streamlined approach:
1

Marketplace Configuration

Marketplace administrators configure available locations at the marketplace level during the initial setup. This makes geographic targeting options available for campaign creation.
2

Campaign Creation

During Sponsored Brands campaign creation, advertisers select from pre-configured geolocations in the Ad Behavior step (Step 2). Multiple locations can be selected for broader targeting.
3

Auction Request

Sponsored Brands auction requests use the same geoTargeting field format for consistency:
{
  "auctions": [
    {
      "winners": 2,
      "placementId": "some-placement",
      "triggers": {
        "searchQuery": "electronics"
      },
      "geoTargeting": "santiago",
      "opaqueUserId": "user-123"
    }
  ]
}
For Sponsored Brands, the geoTargeting field accepts a string value directly, while Sponsored Listings use the geoTargeting.location object structure.

​
Key Considerations

​
General Behavior

  1. Multiple Locations: Campaigns can target multiple geographic locations. If a campaign is associated with location1 and location2, its products are eligible for auctions where the geolocation field is either location1 or location2.
  2. No Location Targeting: If a campaign has no locations defined, it participates in all auctions regardless of location information in the auction request.
  3. Filtered Participation: If a campaign has locations defined, it only participates in auctions where the geolocation field matches one of its specified locations.
  4. Single Location per Request: An auction request accepts only one location in the geolocation field.
  1. Marketplace Configuration Required: Geolocation options only appear during Sponsored Brands campaign creation if locations have been configured at the marketplace level.
  2. Backward Compatibility: Existing Sponsored Brands campaigns without geolocation settings continue to participate in all auctions.
  3. API Consistency: Sponsored Brands geolocation targeting uses the same field structure as Auctions v2 for consistency across the platform.

​
Use Cases

​
Local Market Targeting

  • Regional Product Launches: Promote products only in markets where they’re available
  • Store-Specific Campaigns: Drive traffic to specific store locations
  • Market Testing: Test campaigns in specific regions before broader rollout

​
Seasonal and Event-Based

  • Weather-Based Campaigns: Promote seasonal products based on regional weather patterns
  • Local Events: Target customers in cities hosting relevant events or festivals
  • Regional Preferences: Customize messaging for different cultural regions

​
Multi-Location Strategies

  • National Chains: Create location-specific campaigns for different store regions
  • Supply Chain Optimization: Target only areas where products are in stock
  • Pricing Strategies: Adjust campaign messaging based on regional pricing differences

​
Best Practices

​
Campaign Setup

  • Start with a few high-performing locations before expanding
  • Ensure product availability in targeted locations
  • Consider time zone differences for campaign timing

​
Performance Monitoring

  • Track performance separately for each targeted location
  • Distribute budgets based on location performance and potential
  • Adjust location targeting based on seasonal demand patterns

​
Creative Optimization

  • Customize headlines and creatives for different regions when possible
  • Test location-specific messaging to improve relevance
  • Combine geotargeting with product or category targeting for precision
Last updated: