Trend Scraper Agent

Category: Demand Discovery · Execution Model: Deterministic, I/O-Bound, Append-Only

Purpose

The Trend Scraper Agent collects raw, demand-side activity signals from public platforms and event surfaces to establish real-world market presence for a given query and region. It serves as a ground-truth ingestion layer, capturing observable indicators of consumer interest such as search momentum, social velocity, and live event density. These signals form the empirical foundation for downstream semantic research, trend normalization, and opportunity scoring.

Expected Inputs

query string — default: fitness
The topic, activity, or experiential category to scan for demand signals. Examples: "pilates", "cold plunge", "breathwork", "boxing".
region string — default: Los Angeles County, CA
Geographic scope for demand signal collection. Used to contextualize platform data and downstream geospatial analysis.

Outputs

HTTP Response

{
  "message": "string",
  "record": {
    "query": "string",
    "region": "string",
    "sources": {
      "googleTrends": "number",
      "tiktokVelocity": "number",
      "eventbriteVolume": "number",
      "culturalMomentum": "number"
    },
    "timestamp": "ISODate"
  }
}

Side Effect

Writes a new document to the IngestedData collection

Responsibilities

Accept a topic or activity query and target region
Collect observable demand signals from public platforms
Quantify platform-specific indicators into normalized metrics
Persist raw demand data for downstream analysis
Provide empirical validation for abstract trend hypotheses

Lifecycle

Receive query and region parameters
Fetch or simulate platform-specific demand signals
Normalize signals into a unified ingestion schema
Persist results into IngestedData collection
Return ingestion confirmation to caller

Downstream Dependencies

Deep Research Agent
Category Trends Agent
GeoHeat Agent
Demand Pool Agent

Guarantees

Each invocation produces at most one ingestion record
All persisted records include timestamped demand signals
Raw demand data is preserved for audit and refinement

Failure Model

If ingestion fails due to database or network errors, the request returns a 500 error and no data is persisted. Partial ingestion is not possible; each request produces at most one record.

Internal State

{
  "persistence": [
    "IngestedData"
  ],
  "dataCharacteristics": [
    "Append-only records",
    "No in-place mutation",
    "Multiple records may exist for the same query/region over time"
  ]
}

Sample cURL


curl -X POST https://api.whook.ai/v1/agent/scraper/run \
  -H "Content-Type: application/json" \
  -d '{
    "query": "pilates",
    "region": "Los Angeles County, CA"
  }'