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

# Brand Search Demand

> Report where people are searching for a brand's products, with metro/city-level geographic breakdown.

Answers "where is demand for my brand coming from?" at metro / city
granularity. Closient's search events carry lat/lon per query, so unlike
raw scans (country-level only), search demand can be aggregated to a
useful geographic resolution.

## 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?"

For raw product engagement (scans), pair with `brand-scan-summary`.

## Auth

Same as `brand-scan-summary`: OAuth token with scope `brands:read` and
membership in the owning organization.

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

```json theme={null}
{
  "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.

The endpoint filters `Impression.organization_id == <brand's org>`, groups
by geohash bucket at the requested radius, and joins back to `SearchEvent`
for the query text and user dedupe.

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