google-news-api

Google News API

The News tab of a Google search as structured JSON: which articles ranked for a query, who published them, and when. One credit per page.

Endpoint

GET/v1/news

bash

curl "https://api.serpix.io/v1/news?q=nvidia&hl=en&gl=us" \
  -H "Authorization: Bearer $SERPIX_API_KEY"

The same parameters are accepted as a JSON body on POST /v1/news:

post variant

curl -X POST "https://api.serpix.io/v1/news" \
  -H "Authorization: Bearer $SERPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "nvidia", "hl": "en", "gl": "us"}'

Parameters

Parameters
field	type	default	description
qrequired	string	–	The search query. Google's operators work inside it.
gl	string	–	Country to search as, two letters. Defaults to the country of `location` when one is set, otherwise `us`.
hl	string	en	Interface language, two letters.
device	desktop \| mobile	desktop	Which layout Google serves.
page	integer	1	1-based page number. Page 2 is the next ten articles.
location	string	–	City-level place the search is made from, like `Austin`. The canonical name it resolves to is echoed back as `search_parameters.location_used`.
time_range	h \| d \| w \| m \| y	–	Only articles from the past hour, day, week, month, or year.

Operators

Google's search operators work inside q. To follow one outlet, put a site: on it:

one outlet

# one outlet
curl "https://api.serpix.io/v1/news?q=nvidia+site:reuters.com" \
  -H "Authorization: Bearer $SERPIX_API_KEY"

Unknown parameters are never silently ignored. A request carrying one is rejected with 422 before any search runs, so a typo can't bill you for results you didn't ask for. Parameters from other SERP APIs get a pointed message naming the equivalent here:

Rejected aliases
field	type	default	description
topic	422	–	Not supported. This endpoint answers a query.
publication	422	–	Put it in the query: `q=nvidia site:reuters.com`.
story_token	422	–	Not supported.
ceid	422	–	Use `gl` and `hl`.
when	422	–	Use `time_range`.
num	422	–	One page of about ten articles per request. Paginate with `page`.
start	422	–	Use `page`, a 1-based page number, instead of a result offset.
tbm	422	–	Not needed. This endpoint is the News tab.
google_domain	422	–	Searches run on google.com. Set the country and language with `gl` and `hl`.
api_key	422	–	Authenticate with the `Authorization: Bearer` header.

422 · rejected parameter

HTTP/1.1 422 Unprocessable Entity

{
  "detail": "`topic` is not supported: not supported — this endpoint answers a query, not a feed"
}

Response

A search returns one JSON object: two envelope objects that are always present, then the articles. A field Google didn't serve is omitted entirely, never null, never [].

Top level
field	type	default	description
search_metadata	object	–	Request id, status, timing, parser version, and the exact Google URL fetched.
search_parameters	object	–	The vantage point this capture was taken from, so it can be run again the same way.
news_results	array	–	The articles, in the order Google ranked them.
pagination	object	–	The current page and the URL of the next one.

GET /v1/news?q=nvidia

{
  "search_metadata": {
    "id": "srx_6-Z531iRST1L67tZ",
    "status": "success",
    "created_at": "2026-08-13T14:22:07Z",
    "took_ms": 794,
    "parser_version": "2026.08.19",
    "google_url": "https://www.google.com/search?q=nvidia&tbm=nws&hl=en&gl=us"
  },
  "search_parameters": {
    "q": "nvidia",
    "gl": "us",
    "hl": "en",
    "device": "desktop",
    "page": 1
  },
  "news_results": [
    {
      "position": 1,
      "title": "Nvidia lines up $500 billion in financing as CEO Jensen Huang tells CNBC his chips are 'investable asset'",
      "link": "https://www.cnbc.com/2026/08/10/nvidia-wall-street-asset-managers-500-billion-ai-push.html",
      "source": "CNBC",
      "date": "2 days ago"
    },
    {
      "position": 2,
      "title": "India's Larsen and Toubro secures AI data centre order worth up to $1.57 billion",
      "link": "https://www.reuters.com/world/india/indias-larsen-toubro-secures-order-build-ai-factory-nvidia-2026-08-13/",
      "source": "Reuters",
      "snippet": "India's Larsen and Toubro on Thursday said it had secured an order worth up to 150 billion rupees ($1.57 billion) from a US-based cloud...",
      "date": "8 hours ago"
    }
  ],
  "pagination": {
    "current": 1,
    "next": "https://www.google.com/search?q=nvidia&tbm=nws&hl=en&gl=us&start=10"
  }
}

Articles

One entry per ranked article. link is the publisher's own URL, not a Google redirect, so it can be fetched or stored directly.

NewsArticle
field	type	default	description
position	integer	–	Rank on this page, starting at 1.
title	string	–	The headline, as displayed.
link	string	–	The article on the publisher's site.
source	string	–	The publisher, as the card names it.
snippet	string	–	The article's description. Present on a standalone article, absent on one Google has grouped into a story cluster.
date	string	–	How long ago it was published, as displayed (`2 days ago`, `21 minutes ago`).

Pagination

Ask for page 2 with page=2. next is absent on the last page.

NewsPagination
field	type	default	description
current	integer	–	The page this response is for.
next	string	–	Google's URL for the following page. Absent on the last page.

Nothing matched

A query Google has no articles for returns 200 with news_results absent. It is a real answer and it is charged as one.

200 · no articles

{
  "search_metadata": { "id": "srx_9pQ2mK4vTn8x", "status": "success", "...": "..." },
  "search_parameters": { "q": "zzqxwv nonexistent", "gl": "us", "hl": "en", "device": "desktop", "page": 1 },
  "pagination": { "current": 1 }
}

Envelope

SearchMetadata
field	type	default	description
id	string	–	Request id. Quote it in support.
status	string	–	Always `success` on a 200.
created_at	string	–	When the search ran, ISO 8601 UTC.
took_ms	integer	–	Total time for the fetch and parse.
parser_version	string	–	The parser build that produced this response.
google_url	string	–	The exact URL fetched.
html_url	string	–	Archived raw HTML for this search, when archiving is on.
json_url	string	–	Archived JSON for this search, when archiving is on.

NewsParameters
field	type	default	description
q	string	–	The query that was searched.
gl	string	–	The country actually used, after defaults were applied.
hl	string	–	The interface language used.
device	string	–	The layout requested.
page	integer	–	The page requested.
location_requested	string	–	The place name as you sent it.
location_used	string	–	The canonical place it resolved to.

Errors

You are charged for results, not for failures. A blocked page, a transport error, or a page we captured but could not read all cost nothing.

Status codes
field	type	default	description
200	charged	–	Articles returned, or Google matched none.
402	free	–	Not enough credits. Nothing was fetched.
422	free	–	The request was rejected before any search ran.
502	free	–	The page was captured but could not be read.
503	free	–	Google blocked the capture. Retry, a different session is used.

502 · charged nothing

HTTP/1.1 502 Bad Gateway
X-Serpix-Credits-Charged: 0

{
  "error": { "code": "search_failed", "message": "the page could not be parsed" }
}