Migration guide

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)

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"

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

After (v2)

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"

{
  "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):

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):

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)

{
  "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)

{
  "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):

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):

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:

Update response parsing: { success, total, data } → { metadata, parameters, news_articles }
Handle new type discriminator on news_articles items
Update error handling: { success: false, code } → { metadata, errors }
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 for more details or reach out to support.

Guides

API Reference

Version comparison

Migrating from v1 to v2

What changed

Before (v1)

After (v2)

Code changes

Migrating from v2 to v3

What changed

Before (v2)

After (v3)

Code changes

Migrating from v1 to v3 (skip v2)

Testing checklist

Need help?

​Version comparison

​Migrating from v1 to v2

​What changed

​Before (v1)

​After (v2)

​Code changes

​Migrating from v2 to v3

​What changed

​Before (v2)

​After (v3)

​Code changes

​Migrating from v1 to v3 (skip v2)

​Testing checklist

​Need help?

Version comparison

Migrating from v1 to v2

What changed

Before (v1)

After (v2)

Code changes

Migrating from v2 to v3

What changed

Before (v2)

After (v3)

Code changes

Migrating from v1 to v3 (skip v2)

Testing checklist

Need help?