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 scavio.dev (50 free credits to get started, no card required):

export SCAVIO_API_KEY=sk_live_your_key

Endpoints

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

Trending Parameters

Example

import requests

BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {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.

{
  "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.