Media monitoring

1. 01Write the search terms

   Google News search accepts quoted phrases, so "Acme Corp" does not match every story with acme in it. Add the CEO's name with a qualifier, and your domain for stories that link to you. when=1h limits results to the last hour.

   GET /v1/search?engine=google_news&topic=WORLD&country=nz · query

   {
     "q": null,
     "when": null,
     "topic": "WORLD",
     "language": "en",
     "country": "nz",
     "page": 1
   }

2. 02Keep the publisher URL

   Each result has the publisher's own url next to google_url, with the outlet's name and domain and the publish time. Deduplicate on url: the same story shows up for several terms and markets.

   GET /v1/search?engine=google_news&topic=WORLD&country=nz · results.0

   {
     "position": 1,
     "title": "North Korean operative posing as IT contractor hired by NZ business",
     "url": "https://www.1news.co.nz/2026/09/24/north-korean-operative-posing-as-it-contractor-hired-by-nz-business/",
     "google_url": "https://news.google.com/read/CBMiEXAMPLE",
     "source": {
       "name": "1News",
       "domain": "1news.co.nz"
     },
     "published_at": "2026-09-24T17:03:04.000Z",
     "authors": [
       "Ed O'driscoll"
     ]
   }

3. 03Cover each market

   country and language pick the Google News edition. A story in a British outlet may appear only in the gb edition, so search every market you care about.

   GET /v1/search?engine=google_news&topic=WORLD&country=nz · query.country

   "nz"

# Hourly media monitoring: new Google News headlines for brand terms,
# deduplicated by publisher URL. Keeps seen URLs in seen.json.
import json, os, pathlib, requests

API = "https://api.clair.im"
HEADERS = {"Authorization": f"Bearer {os.environ['CLAIR_API_KEY']}"}
TERMS = ['"Acme Corp"', '"Jane Doe" CEO', "acme.com"]
MARKETS = [("en", "us"), ("en", "gb")]
STATE = pathlib.Path("seen.json")
seen = set(json.loads(STATE.read_text())) if STATE.exists() else set()

def headlines(q, language, country):
    r = requests.get(f"{API}/v1/search", headers=HEADERS, timeout=60, params={
        "engine": "google_news", "q": q, "when": "1h",
        "language": language, "country": country})
    r.raise_for_status()
    return r.json()["results"]

for term in TERMS:
    for language, country in MARKETS:
        for item in headlines(term, language, country):
            if item["url"] in seen:
                continue
            seen.add(item["url"])
            print(f"[{item['source']['name']}] {item['title']}\n  {item['url']}")

STATE.write_text(json.dumps(sorted(seen)))

Set CLAIR_API_KEY to a key subscribed to the Google News API. Each call is one request against that API's monthly quota.

• Headlines only. Google News links to the publisher; for article text, read Reuters, AP, or Bloomberg stories with their APIs, or fetch the publisher page yourself.
• One listing page per search, which Google caps. A very common term returns the most relevant stories, not all of them; make terms specific.
• When Google blocks the HTML search page, search falls back to RSS: the response says format=rss, and results then carry only the Google link.
• Google News covers outlets it indexes. Trade blogs, newsletters, and social posts are mostly not there.