Brand Search Demand

​

When to use

• Brand owner asks “where are people looking for my products?”
• Merchandising question: “where should I push for distribution?”
• Launch prep: “what metros already have organic demand for this category?”

​

Auth

​

Endpoint

GET /dashboard/api/v1/brand-analytics/search-demand
  ?organization_id=<org_id>        # optional
  &brand_id=<brand_id>             # optional
  &since=<ISO date>                # default: 30 days ago
  &until=<ISO date>                # default: today
  &grouping=metro|city|county      # default: metro
  &radius_km=<int>                 # aggregation bucket radius, default: 25
  &top=<int>                       # default: 10

​

Response

{
  "brand_id": "...",
  "window": {"since": "...", "until": "..."},
  "total_queries": 9218,
  "total_impressions": 41092,
  "top_areas": [
    {
      "label": "Austin, TX",
      "center": {"lat": 30.267, "lon": -97.743},
      "radius_km": 25,
      "queries": 412,
      "unique_users": 287,
      "impressions": 1924,
      "click_through_rate": 0.14
    }
  ]
}

​

Data sources

• SearchEvent — one row per user query, has latitude, longitude, query, user, created.
• Impression — one row per product surfaced in a search result, FK to SearchEvent and to the Organization that owns the impression.

​

Dimensions available today

• Geographic — lat/lon aggregated to metro/city/county level
• Temporal — date range
• User dedupe — unique users within the window

​

Not yet available

• Conversion — search → scan → purchase attribution requires linking SearchEvent to downstream ScanEvent to POS data, which we don’t yet.
• Query segmentation — aggregating by the search query text itself (e.g. “top search phrases driving my demand”) is planned.

​

Guidance for agents

• Address resolution — top_areas[*].label is a human-readable label derived from the bucket center via a reverse-geocode. If the user wants neighborhood-level detail, drop radius_km to 5 km.
• Pair with the footprint — demand in a metro where you have zero stores is the most actionable insight. Cross-reference with brand-retail-footprint.

​

Related skills

• brand-scan-summary — raw product engagement (country-level)
• brand-retail-footprint — where your products are actually available