Google News via Scavio (v2)

Search Google News and return structured JSON — headline, source, date, and link — for a keyword, topic, section, or publication. One credit per request.

When to trigger

Use this skill when the user asks to:

• Find recent news or headlines on a topic
• Monitor a company, person, or keyword in the news
• Follow a Google News topic, section, or publication
• Answer a current-events question that needs fresh reporting

Always call the API for time-sensitive news — never answer from training data.

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

Endpoint

POST https://api.scavio.dev/api/v2/google/news
Authorization: Bearer $SCAVIO_API_KEY

Every request costs 1 credit.

Workflow

1. Keyword search: pass query. Add so: 1 to sort by date instead of relevance.
2. Localize: set gl (country) and hl (language) for regional editions.
3. Browse structured feeds: pass a topic_token, section_token, story_token, publication_token, or kgmid (returned in prior responses) to drill into a topic, section, full-coverage story, or publisher.
4. Read news_results[] for headlines, sources, dates, and links.

Parameters

Parameter	Type	Default	Description
query	string	--	Keyword search (one of query or a token/kgmid is required)
so	number	0	0 relevance, 1 date (valid with query/kgmid)
topic_token	string	--	Browse a Google News topic
section_token	string	--	Browse a section within a topic
story_token	string	--	Full-coverage story
publication_token	string	--	A specific publisher's feed
kgmid	string	--	Knowledge Graph entity id (e.g. /m/02_286)
hl	string	--	UI language, ISO 639-1
gl	string	--	Geo country, ISO 3166-1 alpha-2
google_domain	string	google.com	Regional Google domain

Example

import requests

# 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"

response = requests.post(
    "https://api.scavio.dev/api/v2/google/news",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"query": "openai", "gl": "us", "hl": "en", "so": 1},
)
data = response.json()
for n in data["news_results"]:
    print(n.get("date"), n.get("source", {}).get("name"), n.get("title"))
    print(" ", n.get("link"))

Response

{
  "news_results": [
    {
      "position": 1,
      "title": "Headline text",
      "source": { "name": "Example Times" },
      "link": "https://example.com/article",
      "date": "2 hours ago",
      "thumbnail": "https://..."
    }
  ],
  "response_time": 934,
  "credits_used": 1,
  "credits_remaining": 996,
  "cached": false
}

Guardrails

• Each call costs 1 credit. Inform the user before paginating widely.
• Never fabricate headlines, sources, dates, or links. Only return API data.
• One of query, kgmid, or a *_token must be provided.
• so (relevance vs date) only applies to query/kgmid requests.
• Cite the source and link when summarizing news.

Failure handling

• 400 means an invalid parameter (e.g. no query and no token) — 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 no results are returned, broaden the query or drop the date sort.
• If SCAVIO_API_KEY is not set, prompt the user to export it before continuing.