> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> The Google News API provides search, topics, stories, and frontpage data from Google News

The Google News API gives you standardized access to Google News data: search results, topic headlines, full-coverage stories, publication feeds, and the frontpage, in a consistent, enriched format.

## Capabilities

* **Search**: search Google News with clustering into stories and storylines.
* **Topics**: get headlines for a topic or subtopic.
* **Frontpage**: retrieve the Google News frontpage, including dynamic sections.
* **Stories**: deep-dive into a story to see how different publishers cover the same event.
* **Publications**: get the latest headlines from a specific publication.
* **Retrieve**: fetch a past request result by ID.

## Base URL

All requests use the `api.bonai.io/google-news` base URL:

```
https://api.bonai.io/google-news
```

## Authentication

Every request except `GET /ping` requires your API key in the `api-key` header. Keys are product-scoped and created in the [Bonai console](https://console.bonai.io). See [authentication](/google-news-api/authentication).

## Versioning

The API uses header-based versioning with the `api-version` header. The latest version is `2026-05-25`, which is also the default when the header is omitted. See [API versions](/google-news-api/api-version).

## Response format

Responses use a `metadata` / `parameters` / `news_articles` envelope:

```json theme={null}
{
  "metadata": {
    "id": "uuid",
    "total_hits": 100,
    "took_ms": 120,
    "timestamp": "2026-07-30T09:00:00Z"
  },
  "parameters": {
    "country": "us",
    "language": "en"
  },
  "news_articles": []
}
```

The `news_articles` array is polymorphic. Each item carries a `type` field that tells you what it is:

* **`article`**: a standard news article.
* **`story`**: a collection of articles covering the same event.
* **`storyline`**: a chronological series of articles about an evolving story.
* **`social_post`**: content from social media platforms.
* **`section`**: a group of articles or stories with a common title (frontpage only).

<Tip>
  **Polymorphic responses.** `news_articles` items are not all the same shape. Always check the `type` field of each item before handling it.
</Tip>

## Next steps

* [Quickstart](/google-news-api/quickstart): make your first request.
* [API Reference](/openapi/google-news-api.json): explore every endpoint interactively.