> ## 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.

# Migration guide

> Migrate between Google News API versions with before/after code examples

> [!NOTE]
>
> **Familiar with v1 or v2?** The date-based versions map to: v1 = `2022-01-01`, v2 = `2024-01-01`, v3 = `2026-05-25`. This guide uses both naming schemes.

## Version comparison

| | v1 (`2022-01-01`) | v2 (`2024-01-01`) | v3 (`2026-05-25`) |
| - | - | - | - |
| **Envelope** | `{ success, total, data }` | `{ success, totalHits, articles }` | `{ metadata, parameters, news_articles }` |
| **Search endpoint** | `/search` | `/search` | `/search` |
| **Article `type` discriminator** | No | No | Yes |
| **Error format** | `{ success: false, code }` | `{ success: false, code }` | `{ metadata, errors }` |
| **Pagination** | `total` | `totalHits`, `pageSize`, `totalPages` | `total_hits`, `hits_per_page`, `total_pages` |

## Migrating from v1 to v2

### What changed

* **Response envelope**: `{ success, total, data }` → `{ success, totalHits, articles }`
* **Pagination**: `total` → `totalHits`, `pageSize`, `totalPages`
* **Article fields**: Added `thumbnail`, `description`, `keywords`

### Before (v1)

```bash theme={null}
curl --request GET \
  --url "https://api.bonai.io/google-news/search?q=technology&country=us&language=en" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "api-version: 2022-01-01"
```

```json theme={null}
{
  "success": true,
  "total": 842,
  "data": [
    {
      "title": "Example headline",
      "url": "https://example.com/story",
      "date": "2026-07-30T08:00:00Z"
    }
  ]
}
```

### After (v2)

```bash theme={null}
curl --request GET \
  --url "https://api.bonai.io/google-news/search?q=technology&country=us&language=en" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "api-version: 2024-01-01"
```

```json theme={null}
{
  "success": true,
  "totalHits": 842,
  "size": 10,
  "pageSize": 10,
  "page": 1,
  "totalPages": 85,
  "articles": [
    {
      "title": "Example headline",
      "url": "https://example.com/story",
      "date": "2026-07-30T08:00:00Z",
      "thumbnail": "https://example.com/image.jpg",
      "description": "A short description.",
      "authors": ["Jane Doe"],
      "source": {
        "name": "Example Publishing",
        "url": "https://example.com"
      }
    }
  ]
}
```

### Code changes

**Before (v1):**

```javascript theme={null}
const res = await fetch('https://api.bonai.io/google-news/search?q=technology');
const data = await res.json();
// data.success === true
// data.total
// data.data[0].title
```

**After (v2):**

```javascript theme={null}
const res = await fetch('https://api.bonai.io/google-news/search?q=technology');
const data = await res.json();
// data.success === true
// data.totalHits
// data.articles[0].title
// data.articles[0].thumbnail // new
// data.articles[0].description // new
// data.articles[0].authors // new
// data.articles[0].source // new
```

## Migrating from v2 to v3

### What changed

* **Response envelope**: `{ success, totalHits, articles }` → `{ metadata, parameters, news_articles }`
* **Article `type` discriminator**: Added `type` field to distinguish articles, stories, storylines, social posts
* **Error format**: `{ success: false, code }` → `{ metadata, errors }`
* **Pagination**: `totalHits` → `total_hits`, `pageSize` → `hits_per_page`

### Before (v2)

```json theme={null}
{
  "success": true,
  "totalHits": 842,
  "size": 10,
  "pageSize": 10,
  "page": 1,
  "totalPages": 85,
  "articles": [
    {
      "title": "Example headline",
      "url": "https://example.com/story",
      "date": "2026-07-30T08:00:00Z"
    }
  ]
}
```

### After (v3)

```json theme={null}
{
  "metadata": {
    "id": "c1a2b3d4-e5f6-4789-8abc-def012345678",
    "total_hits": 842,
    "took_ms": 96,
    "timestamp": "2026-07-30T09:00:00Z"
  },
  "parameters": {
    "query": "technology",
    "country": "us",
    "language": "en"
  },
  "news_articles": [
    {
      "type": "article",
      "title": "Example headline",
      "url": "https://example.com/story",
      "date": "2026-07-30T08:00:00Z"
    }
  ]
}
```

### Code changes

**Before (v2):**

```javascript theme={null}
const res = await fetch('https://api.bonai.io/google-news/search?q=technology');
const data = await res.json();
// data.success === true
// data.totalHits
// data.articles[0].title
```

**After (v3):**

```javascript theme={null}
const res = await fetch('https://api.bonai.io/google-news/search?q=technology');
const data = await res.json();
// data.metadata.id
// data.pagination.total_hits
// data.news_articles[0].type // new: 'article', 'story', 'storyline', 'social_post'
// data.news_articles[0].title
```

## Migrating from v1 to v3 (skip v2)

If you're on v1 and want to go directly to v3, combine both migrations:

1. Update response parsing: `{ success, total, data }` → `{ metadata, parameters, news_articles }`
2. Handle new `type` discriminator on `news_articles` items
3. Update error handling: `{ success: false, code }` → `{ metadata, errors }`
4. Update pagination: `total` → `total_hits`

## Testing checklist

After migrating, verify:

* [ ] Requests include the `api-version` header with the target version
* [ ] Response parsing uses the new envelope structure
* [ ] Article field names match the new schema
* [ ] Error handling uses the new error format
* [ ] Pagination uses the new field names
* [ ] New `type` discriminator on `news_articles` is handled correctly

## Need help?

If you run into issues during migration, check the [API versions page](/google-news-api/api-version) for more details or reach out to support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.