{
"openapi": "3.0.3",
"info": {
"title": "Google News API",
"version": "2026-05-25",
"description": "API for fetching news from Google News with clustering, topics, and frontpage support."
},
"servers": [
{
"url": "https://api.bonai.io/google-news",
"description": "Production"
}
],
"paths": {
"/search": {
"get": {
"summary": "Search news",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"name": "query",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Search query string"
},
{
"name": "country",
"in": "query",
"schema": {
"type": "string",
"default": "us"
},
"description": "Country code (e.g., us, gb)"
},
{
"name": "language",
"in": "query",
"schema": {
"type": "string",
"default": "en"
},
"description": "Language code (e.g., en, fr)"
},
{
"name": "publisher",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by publisher domain"
},
{
"name": "from",
"in": "query",
"schema": {
"type": "string",
"format": "date"
},
"description": "Published date from (YYYY-MM-DD)"
},
{
"name": "to",
"in": "query",
"schema": {
"type": "string",
"format": "date"
},
"description": "Published date to (YYYY-MM-DD)"
}
],
"responses": {
"200": {
"description": "Successful search results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"apiKey": []
}
],
"x-mint": {
"href": "/api-reference/google-news-api/search-news",
"content": "**Polymorphic response.** `news_articles` items vary by `type` \u2014 `article`, `story`, `storyline`, or `social_post`."
}
}
},
"/topics": {
"get": {
"summary": "News topics",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"name": "topic_id",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Topic ID (e.g., TECHNOLOGY, BUSINESS or CAAq...)"
},
{
"name": "subtopic_id",
"in": "query",
"schema": {
"type": "string"
},
"description": "Subtopic ID (CAAq...)"
},
{
"name": "country",
"in": "query",
"schema": {
"type": "string",
"default": "US"
}
},
{
"name": "language",
"in": "query",
"schema": {
"type": "string",
"default": "en"
}
}
],
"responses": {
"200": {
"description": "Successful topic headlines",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TopicResponse"
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"apiKey": []
}
],
"x-mint": {
"href": "/api-reference/google-news-api/news-topics",
"content": "**Polymorphic response.** `news_articles` items vary by `type` \u2014 `article`, `story`, `storyline`, or `social_post`."
}
}
},
"/frontpage": {
"get": {
"summary": "News frontpage",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"name": "country",
"in": "query",
"schema": {
"type": "string",
"default": "US"
}
},
{
"name": "language",
"in": "query",
"schema": {
"type": "string",
"default": "en"
}
}
],
"responses": {
"200": {
"description": "Successful frontpage data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FrontpageResponse"
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"apiKey": []
}
],
"x-mint": {
"href": "/api-reference/google-news-api/news-frontpage",
"content": "**Polymorphic response.** `news_articles` is an array of `section` objects. Each section's `news_articles` is polymorphic \u2014 `article`, `story`, `storyline`, `social_post`, or a nested `section`."
}
}
},
"/stories": {
"get": {
"summary": "Story coverage",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"name": "story_id",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "country",
"in": "query",
"schema": {
"type": "string",
"default": "US"
}
},
{
"name": "language",
"in": "query",
"schema": {
"type": "string",
"default": "en"
}
}
],
"responses": {
"200": {
"description": "Successful story results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoryResponse"
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"apiKey": []
}
],
"x-mint": {
"href": "/api-reference/google-news-api/story-coverage",
"content": "**Polymorphic response.** `news_articles` items vary by `type` \u2014 `article`, `story`, `storyline`, or `social_post`."
}
}
},
"/publications": {
"get": {
"summary": "Publication news",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"name": "publication_id",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Publication ID (CAAq...)"
},
{
"name": "country",
"in": "query",
"schema": {
"type": "string",
"default": "US"
}
},
{
"name": "language",
"in": "query",
"schema": {
"type": "string",
"default": "en"
}
}
],
"responses": {
"200": {
"description": "Successful publication headlines",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicationResponse"
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"apiKey": []
}
],
"x-mint": {
"href": "/api-reference/google-news-api/publication-news",
"content": "**Polymorphic response.** `news_articles` items vary by `type` \u2014 `article`, `story`, `storyline`, or `social_post`."
}
}
},
"/retrieve/{id}": {
"get": {
"summary": "Request result",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Retrieved result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"apiKey": []
}
],
"x-mint": {
"href": "/api-reference/google-news-api/request-result"
}
}
},
"/ping": {
"get": {
"summary": "Ping",
"parameters": [
{
"$ref": "#/components/parameters/ApiVersionHeader"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PingResponse"
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"description": "Simple endpoint to test API connectivity",
"x-mint": {
"href": "/api-reference/google-news-api/ping"
}
}
}
},
"components": {
"parameters": {
"ApiVersionHeader": {
"name": "api-version",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"2026-05-25",
"2024-01-01",
"2022-01-01"
]
},
"description": "API version to consume. Defaults to the latest version (2026-05-25)."
}
},
"schemas": {
"Metadata": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"total_hits": {
"type": "integer",
"description": "Total number of matching items. Omitted when unknown."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Request start time (ISO 8601)"
},
"took_ms": {
"type": "number",
"format": "float",
"description": "Query execution time in milliseconds"
}
},
"required": [
"id",
"took_ms",
"timestamp"
]
},
"Publisher": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"favicon": {
"type": "string",
"description": "Publisher favicon, or a {origin}/favicon.ico fallback."
},
"publication_id": {
"type": "string",
"nullable": true
}
},
"required": [
"name",
"url"
]
},
"Article": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"article"
]
},
"title": {
"type": "string"
},
"url": {
"type": "string"
},
"date": {
"type": "string",
"format": "date-time"
},
"image": {
"type": "string",
"nullable": true
},
"source": {
"$ref": "#/components/schemas/Publisher",
"description": "The publishing source of the article"
},
"authors": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"Story": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"story"
]
},
"story_id": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"news_articles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Article"
}
}
}
},
"Storyline": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"storyline"
]
},
"title": {
"type": "string",
"nullable": true
},
"news_articles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Article"
}
}
}
},
"Section": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"section"
]
},
"title": {
"type": "string"
},
"topic_id": {
"type": "string",
"nullable": true
},
"news_articles": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Article"
},
{
"$ref": "#/components/schemas/Story"
},
{
"$ref": "#/components/schemas/Storyline"
},
{
"$ref": "#/components/schemas/SocialPost"
},
{
"$ref": "#/components/schemas/Section"
}
]
},
"description": "Polymorphic list. Each item's `type` is `article`, `story`, `storyline`, `social_post`, or nested `section`."
}
}
},
"SearchResponse": {
"type": "object",
"required": [
"metadata",
"parameters",
"news_articles",
"navigation_links"
],
"properties": {
"metadata": {
"$ref": "#/components/schemas/Metadata"
},
"parameters": {
"type": "object",
"description": "The query parameters used for this request"
},
"news_articles": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Article"
},
{
"$ref": "#/components/schemas/Story"
},
{
"$ref": "#/components/schemas/Storyline"
},
{
"$ref": "#/components/schemas/SocialPost"
}
]
},
"description": "Polymorphic list. Each item's `type` is `article`, `story`, `storyline`, or `social_post`."
},
"navigation_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"topic_id"
],
"properties": {
"name": {
"type": "string"
},
"topic_id": {
"type": "string"
}
}
}
},
"related_topics": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"topic_id"
],
"properties": {
"name": {
"type": "string"
},
"topic_id": {
"type": "string"
}
}
}
},
"related_publications": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"publication_id"
],
"properties": {
"name": {
"type": "string"
},
"publication_id": {
"type": "string"
},
"favicon": {
"type": "string",
"nullable": true
}
}
}
}
}
},
"TopicResponse": {
"type": "object",
"required": [
"metadata",
"parameters",
"news_articles",
"navigation_links"
],
"properties": {
"metadata": {
"$ref": "#/components/schemas/Metadata"
},
"parameters": {
"type": "object",
"description": "The query parameters used for this request"
},
"news_articles": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Article"
},
{
"$ref": "#/components/schemas/Story"
},
{
"$ref": "#/components/schemas/Storyline"
},
{
"$ref": "#/components/schemas/SocialPost"
}
]
},
"description": "Polymorphic list. Each item's `type` is `article`, `story`, `storyline`, or `social_post`."
},
"navigation_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"topic_id"
],
"properties": {
"name": {
"type": "string"
},
"topic_id": {
"type": "string"
}
}
}
},
"title": {
"type": "string"
},
"subtopic_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"subtopic_id"
],
"properties": {
"name": {
"type": "string"
},
"subtopic_id": {
"type": "string"
}
}
}
}
}
},
"FrontpageResponse": {
"type": "object",
"required": [
"metadata",
"parameters",
"news_articles",
"navigation_links"
],
"properties": {
"metadata": {
"$ref": "#/components/schemas/Metadata"
},
"parameters": {
"type": "object",
"description": "The query parameters used for this request"
},
"news_articles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Section"
},
"description": "Array of section objects. Each section's `news_articles` is polymorphic (`article`, `story`, `storyline`, `social_post`, or nested `section`)."
},
"navigation_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"topic_id"
],
"properties": {
"name": {
"type": "string"
},
"topic_id": {
"type": "string"
}
}
}
},
"related_topics": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"topic_id"
],
"properties": {
"name": {
"type": "string"
},
"topic_id": {
"type": "string"
}
}
}
},
"related_publications": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"publication_id"
],
"properties": {
"name": {
"type": "string"
},
"publication_id": {
"type": "string"
},
"favicon": {
"type": "string",
"nullable": true
}
}
}
}
}
},
"StoryResponse": {
"type": "object",
"required": [
"metadata",
"parameters",
"news_articles",
"navigation_links"
],
"properties": {
"metadata": {
"$ref": "#/components/schemas/Metadata"
},
"parameters": {
"type": "object",
"description": "The query parameters used for this request"
},
"news_articles": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Article"
},
{
"$ref": "#/components/schemas/Story"
},
{
"$ref": "#/components/schemas/Storyline"
},
{
"$ref": "#/components/schemas/SocialPost"
}
]
},
"description": "Polymorphic list. Each item's `type` is `article`, `story`, `storyline`, or `social_post`."
},
"navigation_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"topic_id"
],
"properties": {
"name": {
"type": "string"
},
"topic_id": {
"type": "string"
}
}
}
},
"title": {
"type": "string"
}
}
},
"PublicationResponse": {
"type": "object",
"required": [
"metadata",
"parameters",
"news_articles",
"navigation_links"
],
"properties": {
"metadata": {
"$ref": "#/components/schemas/Metadata"
},
"parameters": {
"type": "object",
"description": "The query parameters used for this request"
},
"news_articles": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/Article"
},
{
"$ref": "#/components/schemas/Story"
},
{
"$ref": "#/components/schemas/Storyline"
},
{
"$ref": "#/components/schemas/SocialPost"
}
]
},
"description": "Polymorphic list. Each item's `type` is `article`, `story`, `storyline`, or `social_post`."
},
"navigation_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"topic_id"
],
"properties": {
"name": {
"type": "string"
},
"topic_id": {
"type": "string"
}
}
}
},
"title": {
"type": "string"
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"metadata",
"errors"
],
"properties": {
"metadata": {
"type": "object",
"required": [
"id",
"took_ms",
"timestamp"
],
"properties": {
"id": {
"type": "string"
},
"took_ms": {
"type": "number",
"description": "Request execution time in milliseconds"
},
"timestamp": {
"type": "string",
"format": "date-time"
}
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code",
"example": "INVALID_PARAMETER"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
}
}
}
}
}
},
"PingResponse": {
"type": "object",
"required": [
"id",
"message",
"version",
"timestamp"
],
"properties": {
"id": {
"type": "string",
"description": "Request ID"
},
"message": {
"type": "string",
"example": "pong"
},
"version": {
"type": "string",
"description": "Resolved API version",
"example": "2026-05-25"
},
"timestamp": {
"type": "integer",
"description": "Server timestamp in milliseconds"
}
}
},
"SocialPost": {
"type": "object",
"required": [
"type",
"text",
"url",
"published_at",
"image",
"author"
],
"properties": {
"type": {
"type": "string",
"enum": [
"social_post"
]
},
"text": {
"type": "string"
},
"url": {
"type": "string"
},
"published_at": {
"type": "string",
"format": "date-time"
},
"image": {
"type": "string",
"nullable": true
},
"author": {
"type": "object",
"required": [
"username",
"display_name",
"avatar"
],
"properties": {
"username": {
"type": "string"
},
"display_name": {
"type": "string",
"nullable": true
},
"avatar": {
"type": "string",
"nullable": true
}
}
}
}
}
},
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"name": "api-key",
"in": "header",
"description": "Your Bonai API key. Create one in the Bonai console (https://console.bonai.io)."
}
}
}
}