Product catalog for location data providers

This guide defines the product catalog taxonomy and integration requirements for location data providers. Location data providers include organizations that track visits to physical locations, such as restaurant chains measuring foot traffic across locations, hotel brands tracking visits to individual properties, car dealerships, car rental companies, and rideshare services tracking pickup and drop-off locations.

By building on the core product catalog workflow, this guide explains how to structure your category and location taxonomy and configure support for location-based events, such as store visits and foot traffic.

Benefits include the following:

• A single tracking tag for both daily visits and weekly visits
• More frequent brand-level optimization signals
• Granular location-level measurement
• Compliance with The Trade Desk legal requirements

The following sections explain the legal requirements behind this model, compare the two event types, show how to build your category and location taxonomy, and answer FAQs.

Restrictions on location data

IMPORTANT: Do not send the combination of user ID + exact time + exact location in the same record.

The Trade Desk does not accept records that contain a user ID + exact time + exact location combination. Even if the user ID is anonymous, this combination can identify an individual and is considered personally identifiable information (PII). Make sure at least one of these elements is always obscured or removed.

The following table uses Northstar Restaurant at 123 Main St. as an example of permitted and prohibited location data combinations.

Event types: daily and weekly visits

Depending on what your infrastructure and legal review support, you can capture daily visits, weekly visits, or both. The following table highlights the key differences between the two event types, including their use cases, data granularity, reporting cadence, and privacy protections. Because both event types use the same tag in an advertiser campaign, advertisers don't need different campaign configurations to support them.

Step 1: Build your taxonomy for location data

In most cases, before creating a product catalog, you'll need to create a custom taxonomy for the locations you manage. When building your taxonomy, follow these guidelines:

• Decide how you want to categorize your locations, including which businesses need their own category and how granular each one should be. Well-defined categories make the catalog easier to manage, maintain, and activate. See the following table for common category breakdowns by industry.
• If you support both event types, create two subcatalogs: a brand- or geographic group-level catalog for daily visits and a store-level catalog for weekly visits.
• To optimize targeting and measurement, be sure to use categories consistently across both daily visit and weekly visit catalogs for the same brand. For example, if a location is tagged QSR in your store-level weekly visits records, it should also be categorized as QSR in your brand-level daily visits records.
• For general guidance on building a taxonomy, see Build custom taxonomy.

Upload the required categories using the PUT /ecommerce/category/batch endpoint. The following table shows common category breakdowns by industry.

The following is an example request body for the PUT /ecommerce/category/batch endpoint showing parent and child categories:

{
  "MerchantId": "MERCHANT_ID_PLACEHOLDER",
  "Categories": [
    {
      "CategoryId": "FNB",
      "CategoryName": "Food and Beverage"
    },
    {
      "CategoryId": "QSR",
      "CategoryName": "Quick Service Restaurant",
      "ParentCategories": ["FNB"]
    },
    {
      "CategoryId": "COFFEE",
      "CategoryName": "Coffee/Cafe",
      "ParentCategories": ["FNB"]
    },
    {
      "CategoryId": "COMM",
      "CategoryName": "Commerce"
    },
    {
      "CategoryId": "MASS-RETAIL",
      "CategoryName": "Mass Retail",
      "ParentCategories": ["COMM"]
    }
  ]
}

The following diagram shows the category hierarchy based on the parent-child relationships defined in the example request body.

Step 2: Upload product data

To upload location data, follow the Commerce Solutions API steps in the standard product catalog workflow, along with the location-specific requirements described in this section. The following field reference explains how standard product catalog fields map to location data. To configure the event types you support, see the Daily visits and Weekly visits sections.

The example below shows how to represent weekly-visit location data using standard product catalog fields, where each store is treated as the "product":

{
  "MerchantId": "MERCHANT_ID_PLACEHOLDER",
  "Products": [
    {
      "SkuId": "nsm-loc-90210-001",
      "ProductName": "Northstar Restaurant #12045",
      "CategoryId": "QSR",
      "BrandName": "Northstar Restaurant",
      "Description": "123 Main St., Anytown, CA 90210",
      "Availability": "Open"
    },
    {
      "SkuId": "nsm-loc-90211-002",
      "ProductName": "Northstar Restaurant #12046",
      "CategoryId": "QSR",
      "BrandName": "Northstar Restaurant",
      "Description": "456 Oak Ave, Sometown, CA 90211"
    },
    {
      "SkuId": "hcc-loc-90210-001",
      "ProductName": "Harbor Coffee Co. #12324",
      "CategoryId": "COFFEE",
      "BrandName": "Harbor Coffee Co.",
      "Description": "124 Main St., Anytown, CA 90210"
    }
  ]
}

The Availability field is optional. If not needed, you can omit it from the payload, as shown in the example.

Field reference

When uploading your catalog, use location-specific values for the fields listed in the following table. The table shows the required fields for daily visits and weekly visits. Because SKU and item IDs are used differently for each event type, see the Daily visits and Weekly visits sections for implementation details.

Fields not listed are optional and can be omitted. For information on standard product catalog fields, see Upload product catalog data.

Daily visits

The daily visits event gives advertisers a daily visit signal at the brand or geographic-group level. Each SKU or item ID in this catalog represents a minimum of three locations (never a single store), ensuring the specific location a user visited is never exposed.

SKU or item ID naming convention

For daily visits, use a consistent lowercase kebab-case format for values in the SkuId field that identifies both the brand and geographic scope (for example, northstar-market-la-dma).

Requirements

You can define geographic groups to fit your business, but each SKU or item ID must represent at least three locations. The Trade Desk recommends organizing your taxonomy from the broadest geographic level to the most granular, using the following tiers as a starting point.

IMPORTANT: A daily visits SKU or item ID must never map to a single store. If a postal code or city has only one location, roll up to the next geographic tier (for example, metro or DMA level) to keep the specific location blurred.

Catalog structure

Build your daily visits catalog by uploading one object per brand or geographic group, using the tiers you had defined. The following example shows how Northstar Restaurant, Harbor Coffee Co., and Summit General structure their group-level entries.

The category IDs follow the parent-child structure defined in Build your taxonomy for location data.

Conversion events

To send daily-visit conversion event data to The Trade Desk, be sure to follow these requirements.

Weekly visits

The weekly visits event provides granular, store-level visit data on a weekly cadence. Each SKU or item ID represents an individual store location, enabling advertisers to measure specific subsets of locations and analyze store-level details.

SKU or item ID naming convention

To uniquely identify stores and manage the product catalog more efficiently, encode enough information in the SKU or item ID values for weekly visits (for example, nsm-loc-90210-001 where "nsm" is the Northstar Restaurant store brand name and "loc" is the location).

Requirements

Each record in the weekly visits catalog must represent exactly one physical store location. The following fields are critical:

• SkuId must be globally unique within your catalog. No two stores can share an ID.
• Description must include the full street address for human readability and in-platform display.
• Availability must be updated promptly when a location opens or permanently closes.

Catalog structure

Build your weekly visits catalog by uploading one object per store. The following example shows how Northstar Restaurant, Harbor Coffee Co., and Summit General structure their store-level entries.

Conversion events

To send weekly-visit conversion event data to The Trade Desk, be sure to follow these requirements.

Next steps

After uploading your location data, select the type of event data you plan to send with location data:

• Offline Conversion Events API
• Conversion events: Real-Time Conversion Events API quickstart

NOTE: Other event data integration options exist. For details, contact your Technical Account Manager.

FAQs

The following is a list of frequently asked questions about integrating location data with your product catalog.

Can advertisers tell daily visits and weekly visits apart in their reporting?

Yes. Both events share the same advertiser-facing tag, but the event type (Daily Visits or Weekly Visits) tells advertisers which granularity and cadence they're looking at.

Do I have to support both event types?

No. You can implement daily visits only, weekly visits only, or both, depending on what your infrastructure and legal review support. Most location data providers start with daily visits and add weekly visits once store-level aggregation is in place.

What happens if a daily visits SKU or item ID ends up representing fewer than three locations (for example, a chain closes locations in a cluster)?

Re-assign that group up to the next geographic tier so it represents three or more locations again, and update the product catalog accordingly. Do not leave a daily visits SKU or item ID mapped to fewer than three locations.