Quickstart - Bonai Docs

This guide gets you from zero to your first Google News API request. You’ll need an API key from the Bonai console. See getting started if you don’t have one yet.

Search for news

The GET /search endpoint returns search results with clustering:

curl --request GET \
  --url "https://api.bonai.io/google-news/search?query=technology" \
  --header "Authorization: Bearer YOUR_API_KEY"

The response uses the standard envelope:

{
  "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 technology headline",
      "url": "https://example.com/story",
      "date": "2026-07-30T08:00:00Z",
      "image": "https://example.com/image.jpg",
      "source": {
        "name": "Example Publishing",
        "url": "https://example.com",
        "favicon": "https://example.com/favicon.ico",
        "publication_id": "CAAq..."
      },
      "authors": ["Jane Doe"]
    }
  ]
}

This response shape is for version 2026-05-25. If you’re using 2024-01-01 or earlier, the response uses a flat camelCase envelope (success, size, totalHits) and articles don’t have a type discriminator. See API versions for details.

Get news by topic

curl --request GET \
  --url "https://api.bonai.io/google-news/topics?topic_id=TECHNOLOGY&country=us&language=en" \
  --header "Authorization: Bearer YOUR_API_KEY"

Pass a CAAq... ID as topic_id to target a specific topic or subtopic.

Get the frontpage

curl --request GET \
  --url "https://api.bonai.io/google-news/frontpage?country=us&language=en" \
  --header "Authorization: Bearer YOUR_API_KEY"

Full coverage of a story

curl --request GET \
  --url "https://api.bonai.io/google-news/stories?story_id=STORY_ID&country=us&language=en" \
  --header "Authorization: Bearer YOUR_API_KEY"

Next steps

Explore all endpoints in the API Reference.
Understand API versions, rate limits, and errors.