Scavio Google Trends

Query Google Trends for interest-over-time, by-region, and related queries for a keyword, and pull real-time trending searches for a country — as structured JSON. v2 engine, 1 credit per request.

Google Trends via Scavio (v2)

Measure search interest for a keyword over time and geography, and pull the real-time trending searches for a country — all as structured JSON. Two endpoints, each 1 credit.

When to trigger

Use this skill when the user asks to:

• Measure interest in a keyword over time or compare terms
• See where a term is most searched (by region)
• Find related or rising queries for a topic
• Get what's trending right now in a country

Setup

Get a free API key at https://scavio.dev (50 free credits to get started, no card required):

bash

export SCAVIO_API_KEY=sk_live_your_key

Endpoints

Endpoint	Credits	Description
POST https://api.scavio.dev/api/v2/google/trends	1	Interest-over-time, by-region, and related data for a keyword
POST https://api.scavio.dev/api/v2/google/trending	1	Real-time trending searches for a country

text

Authorization: Bearer $SCAVIO_API_KEY

Workflow

1. Keyword interest: call /trends with query. Scope with geo and date (e.g. today 12-m). Pick a data_type to get the widget you need (defaults to TIMESERIES + GEO_MAP).
2. Read interest_over_time.timeline_data[] for the time series and interest_by_region[] for geography. Use data_type: RELATED_QUERIES / RELATED_TOPICS for rising terms.
3. Trending now: call /trending with a required geo country code. Filter with hours, cat, sort, and status. Read trends[].

Trends Parameters

Parameter	Type	Default	Description
query	string	required	Search keyword (1-500 chars)
geo	string	--	Location code (US, GB, US-CA). Worldwide when empty
date	string	--	Time range (e.g. today 12-m, now 7-d)
data_type	string	TIMESERIES+GEO_MAP	TIMESERIES, GEO_MAP, GEO_MAP_0, RELATED_QUERIES, RELATED_TOPICS
cat	string	--	Category id (e.g. 71)
gprop	string	--	Google property: images, news, youtube, froogle (empty = web)
region	string	--	Geo granularity: COUNTRY, REGION, DMA, CITY
hl	string	--	UI language
tz	string	--	Timezone offset in minutes

Trending Parameters

Parameter	Type	Default	Description
geo	string	required	Country code (e.g. US)
hours	number	--	Window: 4, 24, 48, or 168
cat	number	--	Category id (0 = all, up to 20)
sort	string	--	relevance, search_volume, recency, title
status	string	--	all or active
hl	string	--	UI language

Example

python

import os, requests

BASE = "https://api.scavio.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['SCAVIO_API_KEY']}"}

# 1. Interest over the last 12 months in the US
trends = requests.post(f"{BASE}/api/v2/google/trends", headers=HEADERS,
    json={"query": "bitcoin", "geo": "US", "date": "today 12-m"}).json()
for point in trends["interest_over_time"]["timeline_data"]:
    print(point["date"], point["values"][0]["value"])

# 2. What's trending in the US right now
trending = requests.post(f"{BASE}/api/v2/google/trending", headers=HEADERS,
    json={"geo": "US", "hours": 24, "sort": "search_volume"}).json()
for t in trending["trends"]:
    print(t.get("query"), t.get("search_volume"))

Responses

/trends returns interest_over_time.timeline_data[] and/or interest_by_region[] (and related queries/topics per data_type). /trending returns trends[]. Each also includes response_time, credits_used, credits_remaining, and cached.

json

{
  "interest_over_time": {
    "timeline_data": [
      { "date": "May 2026", "values": [{ "query": "bitcoin", "value": "72" }] }
    ]
  },
  "interest_by_region": [
    { "location": "El Salvador", "value": "100" }
  ],
  "response_time": 1220,
  "credits_used": 1,
  "credits_remaining": 992,
  "cached": false
}

Guardrails

• Each call costs 1 credit.
• Never fabricate interest values, regions, or trending terms. Only return API data.
• Trends value is a relative 0-100 index, not an absolute search count — describe it as relative interest.
• /trending requires a geo country code.

Failure handling

• 400 means an invalid parameter (e.g. /trending without geo) — fix and retry.
• 401 means the API key is invalid or missing. Check SCAVIO_API_KEY.
• 429 means rate or usage limit exceeded. Wait before retrying. See https://scavio.dev/docs/rate-limits.
• 502 / 503 mean upstream is temporarily unavailable. Wait a few seconds before retrying.
• If a widget is empty, try a different data_type, a broader date, or drop geo for worldwide.
• If SCAVIO_API_KEY is not set, prompt the user to export it before continuing.