TRAP 01
The Browser CORS Wall
Browsers enforce the Same-Origin Policy (SOP). trends.google.com deliberately excludes Access-Control-Allow-Origin: * headers. Any direct client fetch fails instantly before reaching Google's servers.
Solution: Bolt must scaffold a serverless edge route or Node middleware proxy (e.g. api/trends.ts) that issues server-to-server requests and injects permissive CORS headers for the frontend.
TRAP 02
The Anti-Hijacking JSON Prefix: )]}',\n
Google protects against Cross-Site Script Inclusion (XSSI) attacks by prepending )]}',\n to raw API outputs. Calling standard response.json() immediately throws a fatal SyntaxError: Unexpected token ).
Solution: The proxy must read await response.text(), execute rawText.replace(/^\)\]\}',?\s*/, ''), and only then parse into JSON.
TRAP 03
Aggressive IP Rate-Limiting & CAPTCHAs
Google detects automated queries and triggers HTTP 429 Too Many Requests or intercepts traffic with reCAPTCHA v2 challenges when requests arrive without browser cookies or from shared cloud IP ranges.
Solution: Store queried results in a local cache (1-hour TTL). On 429 responses, seamlessly fail over to an algorithmic trend generator so the app never shows a broken UI.
TRAP 04
Relative 0–100 Index vs Absolute Volume
Developers often misinterpret Google Trends values as raw search query counts or percentage of the world population. In reality, a score of 100 represents the peak popularity for that specific term during that specific window.
Solution: Always label the axis as "Interest Over Time" and clarify to users that 100 is relative peak interest, while 50 represents half the maximum search intensity.
TRAP 05
The Two-Step Token Handshake
Unlike simple REST APIs, you cannot call /trends/api/widgetdata/multiline directly. Google generates cryptographically signed widget tokens per request session via the /explore endpoint.
Solution: The proxy must execute the two-phase handshake sequentially: query /explore first, extract the TIMESERIES widget token, and pass it to /widgetdata/multiline.