google-trends-research

Compare search interest, regional patterns, seasonality, and rising queries through Crawlora's Google Trends endpoints. Use for topic-demand briefs, keyword comparisons, and trending-topic research with correctly interpreted relative indices.

Produce a search-interest comparison with explicit terms, geography, time range, and search property. Trends measures relative search interest, not sales, population opinion, or absolute search volume.

Setup

Set CRAWLORA_API_KEY to your key from crawlora.net. Run the bundled scripts/crawlora.sh from this skill directory or by absolute path. It sends x-api-key to https://api.crawlora.net/api/v1 and prints JSON. Keep the key in the environment. Read reference/endpoints.md for all eleven Trends tools.

Choose the right query

1. Specify the terms, geography, time range, and purpose. Discover supported values with /google/trends/enums, /locations, and /categories. Explore categories and Trending Now categories are different accepted sets; use the relevant discovery response instead of transferring IDs between them.
2. For a comparison, POST to /google/trends/explore/interest-over-time with flat fields: keywords (1–5 strings), geo, time_range, and type. Do not nest them inside the catalog's request body label. Prefer type (web, image, news, youtube, shopping) over the legacy property.
3. Compare the terms in the same request. Hold geography, period, category, property, locale, and timezone constant. Use returned keyword labels to align values rather than assuming array positions across responses.
4. For a broader brief, /google/trends/explore combines the timeline with optional region/query/topic widgets. Use the specific /interest-by-region, /top-queries, /rising-queries, or /related-topics endpoint when only one component is needed. Omitted optional widgets in Explore are unavailable, not zero demand. A regional query can legitimately return an empty array.
5. For current events, GET /google/trends/trending with geo, window (4h, 24h, 48h, 7d), and limit (max 100). Then POST a returned term as query to /google/trends/trending/detail. Explore uses different time strings, such as today 12-m or now 7-d; discover rather than mixing them.

sh

scripts/crawlora.sh /google/trends/enums
scripts/crawlora.sh -X POST /google/trends/explore/interest-over-time \
  '{"keywords":["coffee","tea"],"geo":"US","time_range":"today 12-m","type":"web"}'

Interpret and report

• Interest scores are normalized 0–100 within the query context. Scores from independently scaled requests are not directly comparable. For more than five terms, present separate labeled panels or use an explicit shared-anchor method and describe its sampling/rounding limitations; never simply concatenate scores.
• A zero or has_data=false can reflect insufficient data. Preserve missing flags and partial periods when supplied instead of substituting zeros or declaring demand absent. Equal regional scores do not imply equal search counts.
• Distinguish a literal keyword from a related-topic entity. Do not silently replace one with the other. Preserve Breakout labels instead of inventing a precise growth percentage.
• Use a sufficiently long series before claiming seasonality. A single spike cannot establish a recurring pattern or its cause. Describe correlations and possible explanations separately from measured observations.

Return a chart/table or brief as requested, with terms, filters, collection time, query/source URL where available, interpretation, and missing components. Label the axis as a relative index. See Google's data FAQ for normalization and sampling context.

The service already retries throttled widgets. On 503/429, honor Retry-After when available and use a bounded retry; avoid rapid repeated calls or concurrent widget fan-out. Stop on 401/403 and check application code. Report missing results rather than fabricating a completed comparison.