> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geotargeting

> Target campaigns to specific geographic locations including states, cities, and custom regions for Sponsored Listings and Sponsored Brands

export const LastUpdated = ({date, lang = "en"}) => {
  const translations = {
    en: "Last updated:",
    es: "Última actualización:",
    pt: "Última atualização:",
    fr: "Dernière mise à jour:",
    de: "Zuletzt aktualisiert:"
  };
  const label = translations[lang] || translations.en;
  return <>
<style>{`
.last-updated-component {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 10px 16px;
border-radius: 8px;
margin-top: 12px;
margin-bottom: 16px;
font-size: 14px;
background-color: rgba(0, 0, 0, 0.05);
border: 1px solid rgba(0, 0, 0, 0.12);
color: rgba(0, 0, 0, 0.75);
line-height: 1;
}

        .last-updated-component svg {
          flex-shrink: 0;
          vertical-align: middle;
        }

        .last-updated-component span {
          display: inline-flex !important;
          align-items: center !important;
          line-height: 1 !important;
        }

        [data-theme="dark"] .last-updated-component {
          background-color: #3a3a3a;
          border: 2px solid #888888;
          color: #ffffff;
        }

        [data-theme="dark"] .last-updated-component svg {
          stroke: #ffffff;
        }
      `}</style>
      <div className="last-updated-component">
        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          <circle cx="12" cy="12" r="10" />
          <polyline points="12 6 12 12 16 14" />
        </svg>
        <span>
          <strong style={{
    fontWeight: 600
  }}>{label}</strong> 
          <time dateTime={date}>{date}</time>
        </span>
      </div>
    </>;
};

<div style={{ textAlign: "justify", marginBottom: "1.5rem" }}>
  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.
</div>

## How It Works

### For Sponsored Listings

<Steps>
  <Step title="Pre-Configuration">
    <div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
      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.
    </div>
  </Step>

  <Step title="Campaign Setup">
    <div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
      Advertisers can select multiple regions in the Admin/Vendor Dashboard when creating their campaigns.
    </div>
  </Step>

  <Step title="Auction Process">
    <div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
      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:
    </div>

    ```json theme={null}
    {
      "auctions": [
        {
          "type": "listings",
          "slots": 2,
          "category": {
            "id": "category"
          },
          "geoTargeting": {
            "location": "new-york"
          }
        }
      ]
    }
    ```
  </Step>
</Steps>

### For Sponsored Brands

<div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
  Sponsored Brands geolocation targeting works similarly but uses a streamlined approach:
</div>

<Steps>
  <Step title="Marketplace Configuration">
    <div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
      Marketplace administrators configure available locations at the marketplace level during the initial setup. This makes geographic targeting options available for campaign creation.
    </div>
  </Step>

  <Step title="Campaign Creation">
    <div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
      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.
    </div>
  </Step>

  <Step title="Auction Request">
    <div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
      Sponsored Brands auction requests use the same `geoTargeting` field format for consistency:
    </div>

    ```json theme={null}
    {
      "auctions": [
        {
          "winners": 2,
          "placementId": "some-placement",
          "triggers": {
            "searchQuery": "electronics"
          },
          "geoTargeting": "santiago",
          "opaqueUserId": "user-123"
        }
      ]
    }
    ```
  </Step>
</Steps>

<Note>
  For Sponsored Brands, the `geoTargeting` field accepts a string value directly, while Sponsored Listings use the `geoTargeting.location` object structure.
</Note>

## 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.

### Sponsored Brands Specific

5. **Marketplace Configuration Required**: Geolocation options only appear during Sponsored Brands campaign creation if locations have been configured at the marketplace level.

6. **Backward Compatibility**: Existing Sponsored Brands campaigns without geolocation settings continue to participate in all auctions.

7. **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

***

<LastUpdated date="2025-11-24" />