Google News API reference

Live Google News. Home, named topics, geo sections, publisher pages, and Full Coverage stories are read from news.google.com. Keyword search (q) is read from Google Search’s News tab, which serves the same index with exact publish times; news.google.com’s own search page is blocked for scrapers. Every result has the publisher URL plus google_url. A blocked page returns 502 scrape_failed, never a delayed feed. Article bodies are not hydrated. This is not Google’s official News API. For a single publisher with body, use Reuters, Bloomberg, or Associated Press. See the Google News API: overview, pricing, and free tier.

Endpoint

GET /v1/google-news · 1 request

curl -G https://api.clair.im/v1/google-news \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "topic=WORLD" \
  --data-urlencode "language=en" \
  --data-urlencode "country=us"

Parameters

Parameter	Required	Contract
`q`	no	Search query, run on Google Search’s News tab. Omit for home, topic, or token listings.
`when`	no	With `q`: `1h`, `1d`, `7d`, or `1y`.
`topic`	no	`HEADLINES`, `WORLD`, `NATION`, `BUSINESS`, `TECHNOLOGY`, `ENTERTAINMENT`, `SPORTS`, `SCIENCE`, `HEALTH`.
`topic_token`	no	`/topics/<token>` from the listing.
`section_token`	no	Needs `topic_token` or `publication_token`.
`story_token`	no	Full Coverage cluster.
`publication_token`	no	Publisher page.
`location`	no	Geo section, for example `New York`.
`language`	no	ISO 639-1. Default `en`. Edition language.
`country`	no	ISO 3166-1 alpha-2. Default `us`. Edition country.
`page`	no	With `q`: 1–10, about 10 results a page. Listings must be 1.

With q, the request is a News tab search. Otherwise the listing is chosen in order: story_token, publication_token, topic_token, location, topic, else /home. Do not send limit, cursor, sources, or exclude_sources.

Response

Each result has title, publisher url, google_url, source (name, domain, icon, publication_token), published_at, optional image_url and authors, plus story and related[] when Google clusters coverage. Search results carry story.title when Google groups them, but no image, authors, icon, or tokens. Their publisher URL is read from Google’s redirect; if that fails for a result, url stays the Google link and source.domain is null. next_cursor is the next search page, or null on the last page and on listings. Auth, plans, rate limits, and error codes: Authentication.

​Endpoint

​Parameters

​Response

Endpoint

Parameters

Response