# Google News: Search articles

`google_news/articles/search` · version 2.0.0 · pilot · 100 credits a call

The articles of a Google News search, up to 100, as Google ranks them, each with its publisher's URL.

Categories: News

## When to use

You need the news articles Google News shows for a query: title, the publisher's URL, publication time, publisher, authors, image, and the story Google groups it in. One call is one search of at most 100 articles, ranked by relevance, with no next page: narrow it by time (`when`, or `after`/`before` for days) or by `site`, and call once per period for more. Google News gives no summary of an article's text.

## Call

```bash
curl https://api.lobstr.io/v2/run \
  -H "Authorization: Bearer $LOBSTR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"source": "google_news", "operation": "articles/search", "options": {"query": "artificial intelligence", "when": "1d"}}'
```

The answer's `next` is the whole call for the following page: send it as it is. `null` on the last page.

Beside `options`, the call takes:

| Parameter | Type | Description |
|---|---|---|
| `fields` | array of string | The record fields to keep, by path (`title`, `address.city`); `object`, `id` and `position` always come. Left out: every field. |
| `limit` | integer | Only the first N records of this call (1 to 1000), in the call's order; the call costs the same, and `next` keeps the limit. Left out: every record. |

## Options

| Option | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | yes |  | The words to search, as typed in Google News' search box; its operators work ("exact words", OR, -word). |
| `edition` | `AU:en`, `BW:en`, `CA:en`, `ET:en`, `GH:en`, `IN:en`, `ID:en`, `IE:en`, `IL:en`, `KE:en`, `LV:en`, `MY:en`, `NA:en`, `NZ:en`, `NG:en`, `PK:en`, `PH:en`, `SG:en`, `ZA:en`, `TZ:en`, `UG:en`, `GB:en`, `US:en`, `ZW:en`, `ID:id`, `MY:ms`, `ES:ca`, `CZ:cs`, `DE:de`, `AT:de`, `CH:de`, `EE:et`, `AR:es-419`, `CL:es-419`, `CO:es-419`, `CU:es-419`, `ES:es`, `US:es-419`, `MX:es-419`, `PE:es-419`, `VE:es-419`, `BE:fr`, `CA:fr`, `FR:fr`, `MA:fr`, `SN:fr`, `CH:fr`, `IT:it`, `LV:lv`, `LT:lt`, `HU:hu`, `BE:nl`, `NL:nl`, `NO:no`, `PL:pl`, `BR:pt-419`, `PT:pt-150`, `RO:ro`, `SK:sk`, `SI:sl`, `FI:fi`, `SE:sv`, `VN:vi`, `TR:tr`, `GR:el`, `BG:bg`, `RU:ru`, `UA:ru`, `RS:sr`, `UA:uk`, `IL:he`, `AE:ar`, `SA:ar`, `LB:ar`, `EG:ar`, `IN:mr`, `IN:hi`, `BD:bn`, `IN:bn`, `IN:pa`, `IN:gu`, `IN:ta`, `IN:te`, `IN:ml`, `TH:th`, `CN:zh-Hans`, `TW:zh-Hant`, `HK:zh-Hant`, `JP:ja`, `KR:ko` |  | `"US:en"` | One of Google News' 90 editions, COUNTRY:language as Google writes it (its "Language & region" menu): US:en by default, GB:en, FR:fr, DE:de, IN:en, BR:pt-419... Google ranks and picks the articles for that edition's readers. |
| `site` | string |  |  | Only the articles of this publisher's domain (lemonde.fr, reuters.com). |
| `when` | `1h`, `1d`, `7d` |  |  | Only the articles of the last hour, day or week. Not with `after` or `before`. |
| `after` | string (date) |  |  | Only the articles published from this day (YYYY-MM-DD), which Google reads in US Pacific time. The articles of a search by day carry their day, not their hour (Google cuts their time to the day's midnight, Pacific). |
| `before` | string (date) |  |  | Only the articles published before this day (YYYY-MM-DD, US Pacific time). With `after`, a span of days. |

## Record

Each item of `results`. Every field is always present, `null` when the site gives nothing.

| Field | Type | Description |
|---|---|---|
| `object` | `"article"` |  |
| `id` | string | The article's id: 16 characters, the same for its publisher's URL in every search and edition. Google's own id is ids.article_id. |
| `position` | integer | Its place in Google's ranking; a story's articles in their story's place. |
| `title` | string | null | The title |
| `url` | string | null (uri) | The article at its publisher's (never Google's link). |
| `amp_url` | string | null (uri) | Its AMP page, when the publisher has one. |
| `published_at` | string | null (date-time) | When it was published, UTC (a day's midnight, Pacific, in a search by `after`/`before`). |
| `publisher` | object |  |
| `publisher.name` | string | null |  |
| `publisher.site` | string | null | The publisher's site: https://www.lemonde.fr. |
| `publisher.icon` | string | null | Its icon, as Google News shows it. |
| `publisher.id` | string | null | Google News' id of the publisher, the same on all its articles; null for some smaller ones. |
| `publisher.google_news_url` | string | null (uri) | The publisher's page on Google News. |
| `authors` | array | The authors Google News names (about half the articles), each with their Google News page when it has one. |
| `authors[].name` | string |  |
| `authors[].google_news_url` | string | null (uri) |  |
| `image` | object | null |  |
| `image.url` | string | null | The image at its publisher's. |
| `image.google_url` | string | null | Google's copy of it, as the page shows it. |
| `image.width` | integer | null |  |
| `image.height` | integer | null |  |
| `story` | object | null | The story Google groups the article in (three articles under its heading, in plain searches only); null for an article alone. |
| `story.title` | string | null | Google's heading of the story. |
| `story.position` | integer | The article's place in its story, 1 to 3. |
| `ids` | object | Every id Google News gives with the article. |
| `ids.article_id` | string | null | Google News' id of the article (CBMi...), the one in its own links: about 250 characters. |
| `google_news_url` | string | null (uri) | The article's link on Google News. |
| `source_url` | string (uri) | The search on news.google.com these values were read from. |
| `observed_at` | string (date-time) | When they were read |

Example:

```json
{
  "object": "article",
  "id": "3f9a1c27b84e5d06",
  "position": 1,
  "title": "An example article on artificial intelligence",
  "url": "https://www.example-news.com/2026/11/12/ai-example",
  "amp_url": null,
  "published_at": "2026-11-12T13:53:07Z",
  "publisher": {
    "name": "Example News",
    "site": "https://www.example-news.com",
    "icon": "https://encrypted-tbn0.gstatic.com/faviconV2?url=https://www.example-news.com",
    "id": "CAAqExamplePublisherId",
    "google_news_url": "https://news.google.com/publications/CAAqExamplePublisherId"
  },
  "authors": [
    {
      "name": "Jane Doe",
      "google_news_url": null
    }
  ],
  "image": {
    "url": "https://img.example-news.com/ai.jpg",
    "google_url": "https://news.google.com/api/attachments/CC8iExample",
    "width": 664,
    "height": 426
  },
  "story": null,
  "ids": {
    "article_id": "CBMiExampleArticleId"
  },
  "google_news_url": "https://news.google.com/read/CBMiExampleArticleId?hl=en-US&gl=US&ceid=US%3Aen",
  "source_url": "https://news.google.com/search?q=artificial%20intelligence%20when%3A1d&hl=en-US&gl=US&ceid=US%3Aen",
  "observed_at": "2026-11-12T16:00:00Z"
}
```

## Price

100 credits a call, whatever the search holds. An empty search and a failed call are free.

## Errors

| Code | Status | Retry | Message |
|---|---|---|---|
| `invalid_query` | 422 | no | `query` takes 1 to 500 characters. |
| `invalid_edition` | 422 | no | An edition is COUNTRY:language, as Google News writes it: US:en, FR:fr. |
| `invalid_site` | 422 | no | `site` is a domain: reuters.com. |
| `invalid_time` | 422 | no | `when` takes 1h, 1d or 7d; `after` and `before` are days (YYYY-MM-DD); not `when` with them. |
| `site_challenge` | 503 | yes | Google asked to prove a person is there; retry in a minute (not charged). |
| `site_unavailable` | 503 | yes | Google did not answer in time or refused the call; retry later (not charged). |
| `unexpected_answer` | 424 | no | Google answered in a shape we do not read yet; we are told and fix it, and it is not charged. |
| `missing_api_key` | 401 | no | No API key: send it as `Authorization: Bearer <key>`. |
| `invalid_api_key` | 401 | no | The key is not valid, or not anymore. |
| `insufficient_credits` | 402 | no | The call costs more credits than are left. |
| `unknown_operation` | 404 | no | No such source and operation in the catalog. |
| `timeout` | 408 | yes | The call did not finish within its deadline (not charged). |
| `invalid_body` | 422 | no | The body is not a call: source, operation, options. |
| `invalid_options` | 422 | no | An option is missing or out of its contract; `param` names it. |
| `invalid_idempotency_key` | 400 | no | The Idempotency-Key header is not printable ASCII, or too long. |
| `concurrency_limit` | 429 | yes | The plan's calls at a time are all in progress (Free 1, Starter 2, Pro 10, Team 50); retry when one has finished (not charged, never queued). |
| `service_busy` | 503 | yes | Too many calls at once on the account; retry in a few seconds. |
| `balance_unavailable` | 503 | yes | The balance could not be read; retry in a few seconds. |

## Changelog

- **2.0.0** (2026-11-13): `id` is now short: 16 characters, the same for an article's publisher URL in every search and edition. Google's own id (CBMi..., about 250 characters, 44 % of an answer) moves to `ids.article_id`. A search of 100 articles with a few `fields` now fits what an agent reads in one call.
- **1.0.0** (2026-11-12): First version on the API v2: one Google News search of up to 100 articles, as Google ranks them, each with its publisher's URL, time, publisher, authors, image and story; by edition, site, the last hour, day or week, or days.

Schema: https://api.lobstr.io/v2/catalog/google_news/articles/search · All operations: https://api.lobstr.io/v2/catalog.md
