> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/google-news.md).

# Google News

Google News lets you list articles by category or run a free-text search. All endpoints are read-only `GET` requests and return public Google News data.

**Base URL:** `https://api.pullbay.com/`

## Endpoints

| Endpoint                    | Description                                  | Pagination          |
| --------------------------- | -------------------------------------------- | ------------------- |
| `GET /google-news/category` | List top articles for a Google News category | —                   |
| `GET /google-news/search`   | Search Google News articles by query         | maxItems (one-shot) |

***

## Get News By Category

Returns top news articles for a given Google News category. `languageCode` selects the locale edition (e.g. `US:en`, `GB:en`).

**Request**

```http
GET /google-news/category
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter      | Type   | Required | Description                                                                                                      |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `category`     | string | Yes      | News category. One of `business`, `entertainment`, `health`, `latest`, `science`, `sport`, `technology`, `world` |
| `languageCode` | string | No       | Locale edition code, e.g. `US:en`, `GB:en`, `DE:de`, `JP:ja`                                                     |

**Example**

```bash
curl -G "https://api.pullbay.com/google-news/category" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d category=technology \
  -d languageCode=US:en
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "title": "The next phase of the Microsoft-OpenAI partnership",
      "articleUrl": "https://news.google.com/read/CBMimwFBVV95cUxNakYwXzBZNG85QlRVd01tNzEwaEM3djQxWnMya0FN",
      "publishedAt": "2026-04-27T13:07:55Z",
      "imageUrl": "/api/attachments/CC8iK0NnNXdhR2hQYWxjeGIxSmpNMEpOVFJDZkF4ampCU2dLTWdZQm9KVEVQQWM=-w64-h64-p-df-rw",
      "source": "The Official Microsoft Blog",
      "sourceIconUrl": "https://encrypted-tbn0.gstatic.com/faviconV2?url=https://blogs.microsoft.com",
      "author": "By Brendan Morrow"
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of articles returned, not the number of requests.

***

## Search News

Returns articles matching `query`. Set `resolveUrl=yes` to follow Google's redirect and return the publisher's direct URL instead of the `news.google.com` link.

**Request**

```http
GET /google-news/search
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter      | Type    | Required | Description                                                                  |
| -------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `query`        | string  | Yes      | Search query, 1–500 characters                                               |
| `languageCode` | string  | No       | Locale edition code, e.g. `US:en`, `GB:en`, `DE:de`, `JP:ja`                 |
| `resolveUrl`   | boolean | No       | `true` to resolve the publisher URL instead of the Google News redirect link |
| `maxItems`     | integer | No       | One-shot bulk pull, 1–100 results                                            |

**Example**

```bash
curl -G "https://api.pullbay.com/google-news/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d query="OpenAI partnership" \
  -d languageCode=US:en \
  -d resolveUrl=true \
  -d maxItems=20
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "title": "The next phase of the Microsoft-OpenAI partnership",
      "articleUrl": "https://news.google.com/read/CBMimwFBVV95cUxNakYwXzBZNG85QlRVd01tNzEwaEM3djQxWnMya0FN",
      "publishedAt": "2026-04-27T13:07:55Z",
      "imageUrl": "/api/attachments/CC8iK0NnNXdhR2hQYWxjeGIxSmpNMEpOVFJDZkF4ampCU2dLTWdZQm9KVEVQQWM=-w64-h64-p-df-rw",
      "source": "The Official Microsoft Blog",
      "sourceIconUrl": "https://encrypted-tbn0.gstatic.com/faviconV2?url=https://blogs.microsoft.com",
      "author": "By Brendan Morrow"
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Using `maxItems` to pull more results in one call costs proportionally more than a smaller pull.

***

## Object schemas

### GoogleNewsArticle object

| Field           | Type               | Description                                                                                     |
| --------------- | ------------------ | ----------------------------------------------------------------------------------------------- |
| `title`         | string             | Article headline                                                                                |
| `articleUrl`    | string             | Link to the article on `news.google.com` (or the resolved publisher URL when `resolveUrl=true`) |
| `publishedAt`   | string (date-time) | Publication timestamp                                                                           |
| `imageUrl`      | string, nullable   | Thumbnail image URL, often a relative `/api/attachments/...` path                               |
| `source`        | string             | Publisher/outlet name                                                                           |
| `sourceIconUrl` | string             | Favicon URL for the publisher                                                                   |
| `author`        | string, nullable   | Byline, when available                                                                          |

***

## Errors

All non-2xx responses share the same envelope:

```json
{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}
```

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `400`  | Bad request — missing/invalid parameters |
| `402`  | Insufficient credits                     |
| `404`  | No articles found                        |

## Category and Language Codes

* `category` accepts one of `business`, `entertainment`, `health`, `latest`, `science`, `sport`, `technology`, `world`.
* `languageCode` combines a 2-letter country code and a language/locale tag, separated by a colon (e.g. `US:en`, `GB:en`, `BR:pt-419`, `JP:ja`). Pass the pair exactly as listed — country and language aren't independent fields here.
* If `languageCode` is omitted, results default to the `US:en` edition.

## Resolving Publisher URLs

* By default, `articleUrl` points to a `news.google.com/read/...` redirect link, not the original publisher page.
* Set `resolveUrl=true` on `/google-news/search` to have Pullbay follow that redirect server-side and return the final publisher URL instead.
* `/google-news/category` does not expose `resolveUrl` — its `articleUrl` is always the Google News redirect link.