Skip to main content

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.

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

{
  "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.
  • brand-scan-summary — raw product engagement (country-level)
  • brand-retail-footprint — where your products are actually available