GNews API

https://docs.gnews.io/
Admin
GNews API is a REST news API providing access to current and historic news articles from over 60,000...
Tokens:7,575
Snippets:65
Trust Score:8.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### 401 Unauthorized Error Example

Source: https://docs.gnews.io/error-handling

Response returned when the provided API key is missing or invalid.

```json
{
  "errors": [
    "Your API key is invalid."
  ]
}
```

--------------------------------

### 403 Forbidden Error Example

Source: https://docs.gnews.io/error-handling

Response returned when the daily request quota has been exceeded.

```json
{
  "errors": [
    "You have reached your request limit for today, the next reset will be tomorrow at midnight UTC. If you need more requests, you can upgrade your subscription here: https://gnews.io/pricing"
  ]
}
```

--------------------------------

### 400 Bad Request Error Examples

Source: https://docs.gnews.io/error-handling

JSON responses indicating missing or malformed request parameters.

```json
{
  "errors": {
    "q": "The query is required."
  }
}
```

```json
{
  "errors": {
    "q": "The query has a syntax error (see https://docs.gnews.io/endpoints/search-endpoint#query-syntax)."
  }
}
```

--------------------------------

### Example API JSON Response

Source: https://docs.gnews.io/json-response

A sample JSON object showing the structure of the API response, including article metadata and source details.

```json
{
  "totalArticles": 54904,
  "articles": [
    {
      "id": "b961dade95c55b7f949ccd8e0234a356",
      "title": "M5 chip leak reveals Apple has big gains coming in key area",
      "description": "Apple’s forthcoming M5 chip has seemingly leaked as part of a new iPad Pro hardware leak. Here’s what its performance looks like in testing.",
      "content": "Today, Apple’s as-yet-unannounced M5 iPad Pro was seemingly leaked by the same YouTuber who last year leaked the M4 MacBook Pro. Thanks to the surprise reveal, we now have benchmarks for Apple’s forthcoming M5 chip, and they point to big gains coming... [1862 chars]",
      "url": "https://9to5mac.com/2025/09/30/m5-chip-leak-reveals-apple-has-big-gains-coming-in-key-area/",
      "image": "https://i0.wp.com/9to5mac.com/wp-content/uploads/sites/6/2024/12/M5-Pro-chip-could-separate-CPU-and-GPU-in-server-grade-chips.jpg?resize=1200%2C628&quality=82&strip=all&ssl=1",
      "publishedAt": "2025-09-30T19:38:25Z",
      "lang": "en",
      "source": {
        "id": "92f73865e835e33ed68c11447777c939",
        "name": "9to5Mac",
        "url": "https://9to5mac.com",
        "country": "us"
      }
    }
  ]
}
```

--------------------------------

### Handle API Responses with Fetch

Source: https://docs.gnews.io/error-handling

Example of checking HTTP status codes and handling errors using the Fetch API.

```javascript
fetch(url)
    .then(response => {
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return response.json();
    })
    .then(data => {
        // Handle successful response
    })
    .catch(error => {
        // Handle error
        console.error('API Error:', error);
    });
```

--------------------------------

### GET /api/v4/top-headlines

Source: https://docs.gnews.io/endpoints/top-headlines-endpoint

Retrieves the top news headlines from the GNews API.

```APIDOC
## GET /api/v4/top-headlines

### Description
Retrieves the latest top news headlines based on specified parameters.

### Method
GET

### Endpoint
https://gnews.io/api/v4/top-headlines

### Parameters
#### Query Parameters
- **category** (string) - Optional - The category of news to retrieve (e.g., general).
- **lang** (string) - Optional - The language of the news articles (e.g., en).
- **country** (string) - Optional - The country code for the news (e.g., us).
- **max** (integer) - Optional - The maximum number of articles to return.
- **apikey** (string) - Required - Your unique API key for authentication.

### Response
#### Success Response (200)
- **articles** (array) - A list of article objects containing details like title and description.
```

--------------------------------

### 429 Too Many Requests Error Example

Source: https://docs.gnews.io/error-handling

Response returned when the rate limit for requests per second is exceeded.

```json
{
  "errors": [
    "This request was blocked because you made too many requests on the API in a short period of time."
  ]
}
```

--------------------------------

### GET /search

Source: https://docs.gnews.io/

Search for articles matching specific keywords with advanced filtering options.

```APIDOC
## GET /search

### Description
Search for articles matching specific keywords, supporting date range filtering, language, and country targeting.

### Method
GET

### Endpoint
https://gnews.io/api/v4/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Keywords to search for
- **lang** (string) - Optional - Language code
- **max** (integer) - Optional - Maximum number of articles to return
- **apikey** (string) - Required - Your API key
```

--------------------------------

### GET /api/v4/search

Source: https://docs.gnews.io/endpoints/search-endpoint

Retrieves a list of news articles matching the specified search query.

```APIDOC
## GET /api/v4/search

### Description
Searches for news articles based on a query string and optional filters.

### Method
GET

### Endpoint
https://gnews.io/api/v4/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query to filter articles.
- **lang** (string) - Optional - The language of the articles to return.
- **max** (integer) - Optional - The maximum number of articles to return.
- **apikey** (string) - Required - Your unique API key for authentication.
```

--------------------------------

### GET /api/v4/top-headlines

Source: https://docs.gnews.io/endpoints/top-headlines-endpoint

Retrieves the top news headlines based on specified query parameters.

```APIDOC
## GET /api/v4/top-headlines

### Description
Retrieves the latest top headlines from the GNews API. Users can filter results by category, language, country, and limit the number of articles returned.

### Method
GET

### Endpoint
https://gnews.io/api/v4/top-headlines

### Parameters
#### Query Parameters
- **apikey** (string) - Required - Your API key for authentication.
- **category** (string) - Optional - The category of news to retrieve (e.g., general).
- **lang** (string) - Optional - The language of the articles (e.g., en).
- **country** (string) - Optional - The country code for the news (e.g., us).
- **max** (integer) - Optional - The maximum number of articles to return.

### Response
#### Success Response (200)
- **totalArticles** (integer) - The total number of articles found.
- **articles** (array) - A list of article objects containing title, description, content, url, image, publishedAt, lang, and source information.
```

--------------------------------

### GET /api/v4/top-headlines

Source: https://docs.gnews.io/endpoints/top-headlines-endpoint

Retrieves current trending articles based on Google News ranking.

```APIDOC
## GET /api/v4/top-headlines

### Description
This endpoint allows you to search for current trending articles, the articles that are selected to be returned by this endpoint are based on the Google News ranking.

### Method
GET

### Endpoint
https://gnews.io/api/v4/top-headlines

### Parameters
#### Query Parameters
- **category** (string) - Optional - The category for the request. Available: general, world, nation, business, technology, entertainment, sports, science, health. Default: general.
- **lang** (string) - Optional - The 2-letter language code to filter articles.
- **country** (string) - Optional - The 2-letter country code to filter articles.
- **max** (integer) - Optional - Number of articles to return (1-100). Default: 10.
- **nullable** (string) - Optional - Attributes allowed to return null values (description, content, image).
- **from** (string) - Optional - Filter articles with publication date >= specified ISO 8601 date.
- **to** (string) - Optional - Filter articles with publication date <= specified ISO 8601 date.
- **q** (string) - Optional - Search keywords (max 200 characters).
- **page** (integer) - Optional - Pagination control. Default: 1.
- **truncate** (string) - Optional - Set to 'content' to truncate the content attribute.
```

--------------------------------

### GET /top-headlines

Source: https://docs.gnews.io/

Retrieve trending articles based on Google News rankings across various categories.

```APIDOC
## GET /top-headlines

### Description
Get trending articles based on Google News rankings across 9 categories including General, World, Nation, Business, Technology, Entertainment, Sports, Science, and Health.

### Method
GET

### Endpoint
https://gnews.io/api/v4/top-headlines

### Parameters
#### Query Parameters
- **apikey** (string) - Required - Your API key
```

--------------------------------

### GET /api/v4/search

Source: https://docs.gnews.io/endpoints/search-endpoint

Retrieve news articles based on search keywords and various filtering parameters.

```APIDOC
## GET /api/v4/search

### Description
This endpoint allows you to search for news articles through a combination of keywords.

### Method
GET

### Endpoint
/api/v4/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search keywords to find news articles.
- **lang** (string) - Optional - 2-letter language code to filter articles.
- **country** (string) - Optional - 2-letter country code to filter articles.
- **max** (integer) - Optional - Number of articles to return (1-100).
- **in** (string) - Optional - Attributes to search in (title, description, content).
- **nullable** (string) - Optional - Attributes allowed to return null values (description, content, image).
- **from** (string) - Optional - Start date in ISO 8601 format.
- **to** (string) - Optional - End date in ISO 8601 format.
- **sortby** (string) - Optional - Sorting type (publishedAt, relevance).
- **page** (integer) - Optional - Pagination control.
- **truncate** (string) - Optional - Truncate the content attribute.
```

--------------------------------

### Fetch top headlines with Bash

Source: https://docs.gnews.io/endpoints/top-headlines-endpoint

Requires the jq package to parse the JSON response from the API.

```bash
# Please note that you must have the package jq: https://stedolan.github.io/jq/  
#!/bin/bash  
# TODO: replace API_KEY with your API key.  
apikey='API_KEY'  
category='general'  
url="https://gnews.io/api/v4/top-headlines?category=$category&lang=en&country=us&max=10&apikey=$apikey"  
  
data=$(curl -s $url)  
articles=$(echo $data | jq '.articles')  
articles_length=$(echo $articles | jq length)  
echo $articles_length  
  
for ((i = 0; i < $articles_length; i++)); do  
  echo $i  
  # articles[i].title  
  title=$(echo $articles | jq ".[i].title")  
  echo "Title: $title"  
  # articles[i].description  
  description=$(echo $articles | jq ".[i].description")  
  echo "Description: $description"  
  # You can replace {property} below with any of the article properties returned by the API.  
  # articles[i].{property}  
  # {property}=$(echo $articles | jq ".[i].{property}")  
  # echo "${property}"  
  
  # Delete this line to display all the articles returned by the request. Currently only the first article is displayed.  
  break  
done  
```

--------------------------------

### Fetch Top Headlines with C#

Source: https://docs.gnews.io/endpoints/top-headlines-endpoint

Uses HttpClient and Newtonsoft.Json to handle API requests and data deserialization.

```csharp
// https://www.newtonsoft.com/json  
// dotnet add package Newtonsoft.Json  
// This library will be used to parse the JSON data returned by the API.  
using Newtonsoft.Json;  
  
// TODO: replace API_KEY with your API key.  
const string API_KEY = "API_KEY";  
const string CATEGORY = "general";  
const string URL = $"https://gnews.io/api/v4/top-headlines?category={CATEGORY}&lang=en&country=us&max=10&apikey={API_KEY}";  
  
HttpClient client = new HttpClient();  
HttpResponseMessage response = await client.GetAsync(URL);  
response.EnsureSuccessStatusCode();  
string responseBody = await response.Content.ReadAsStringAsync();  
var data = JsonConvert.DeserializeObject<ApiResponse>(responseBody);  
List<Article> articles = data.Articles;  
  
for (int i = 0; i < articles.Count; i++)  
{  
  // articles[i].title  
  Console.WriteLine($"Title: {articles[i].Title}");  
  // articles[i].description  
  Console.WriteLine($"Description: {articles[i].Description}");  
  // You can replace {property} below with any of the article properties returned by the API.  
  // articles[i].{property}  
  // Console.WriteLine($"{articles[i].{property}}");  
  // Note that {property} must be compliant with the definition of class Article.  
  
  // Delete this line to display all the articles returned by the request. Currently only the first article is displayed.  
  break;  
}  
  
class ApiResponse  
{  
  public int TotalArticles { get; set; }  
  public List<Article> Articles { get; set; } = new List<Article>();  
}  
  
class Article  
{  
  public string Id { get; set; } = "";  
  public string Title { get; set; } = "";  
  public string Description { get; set; } = "";  
  public string Content { get; set; } = "";  
  public string Url { get; set; } = "";  
  public string Image { get; set; } = "";  
  public string PublishedAt { get; set; } = "";  
  public string Lang { get; set; } = "";  
  public Source Source { get; set; } = new Source();  
}  
  
class Source  
{  
  public string Id { get; set; } = "";  
  public string Name { get; set; } = "";  
  public string Url { get; set; } = "";  
  public string Country { get; set; } = "";  
}
```

--------------------------------

### Make a Basic API Request

Source: https://docs.gnews.io/

The standard pattern for all API requests using the base URL, endpoint, parameters, and API key.

```HTTP
GEThttps://gnews.io/api/v4/{endpoint}?{parameters}&apikey=YOUR_API_KEY
```

```HTTP
GEThttps://gnews.io/api/v4/search?q=Google&lang=en&max=5&apikey=YOUR_API_KEY
```

--------------------------------

### Fetch Top Headlines with Python

Source: https://docs.gnews.io/endpoints/top-headlines-endpoint

Uses urllib.request and the json library to fetch and parse API responses.

```python
# https://docs.python.org/3/library/json.html  
# This library will be used to parse the JSON data returned by the API.  
import json  
# https://docs.python.org/3/library/urllib.request.html#module-urllib.request  
# This library will be used to fetch the API.  
import urllib.request  
  
# TODO: replace API_KEY with your API key.  
apikey = "API_KEY"  
category = "general"  
url = f"https://gnews.io/api/v4/top-headlines?category={category}&lang=en&country=us&max=10&apikey={apikey}"  
  
with urllib.request.urlopen(url) as response:  
    data = json.loads(response.read().decode("utf-8"))  
    articles = data["articles"]  
  
    for i in range(len(articles)):  
        # articles[i].title  
        print(f"Title: {articles[i]['title']}")  
        # articles[i].description  
        print(f"Description: {articles[i]['description']}")  
        # You can replace {property} below with any of the article properties returned by the API.  
        # articles[i].{property}  
        # print(f"{articles[i]['{property}']}")  
  
        # Delete this line to display all the articles returned by the request. Currently only the first article is displayed.  
        break
```

--------------------------------

### Search Articles with JavaScript

Source: https://docs.gnews.io/endpoints/search-endpoint

Uses the fetch API to retrieve search results and log article titles and descriptions to the console.

```javascript
// TODO: replace API_KEY with your API key.  
apikey = 'API_KEY';  
url = 'https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey=' + apikey;  
  
fetch(url)  
  .then(function (response) {  
    return response.json();  
  })  
  .then(function (data) {  
    articles = data.articles;  
  
    for (i = 0; i < articles.length; i++) {  
      // articles[i].title  
      console.log("Title: " + articles[i]['title']);  
      // articles[i].description  
      console.log("Description: " + articles[i]['description']);  
      // You can replace {property} below with any of the article properties returned by the API.  
      // articles[i].{property}  
      // console.log(articles[i]['{property}']);  
  
      // Delete this line to display all the articles returned by the request. Currently only the first article is displayed.  
      break;  
    }  
  });
```

--------------------------------

### Fetch top headlines with PHP

Source: https://docs.gnews.io/endpoints/top-headlines-endpoint

Uses cURL to request headlines and iterates through the articles array.

```php
<?php  
// TODO: replace API_KEY with your API key.  
$apikey = 'API_KEY';  
$category = 'general';  
$url = "https://gnews.io/api/v4/top-headlines?category=$category&lang=en&country=us&max=10&apikey=$apikey";  
  
$ch = curl_init();  
curl_setopt($ch, CURLOPT_URL, $url);  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);  
$data = json_decode(curl_exec($ch), true);  
curl_close($ch);  
$articles = $data['articles'];  
  
for ($i = 0; $i < count($articles); $i++) {  
    // articles[i].title  
    echo "Title: " . $articles[$i]['title'] . "\n";  
    // articles[i].description  
    echo "Description: " . $articles[$i]['description'] . "\n";  
    // You can replace {property} below with any of the article properties returned by the API.  
    // articles[i].{property}  
    // echo $articles[$i]['{property}'] . "\n";  
  
    // Delete this line to display all the articles returned by the request. Currently only the first article is displayed.  
    break;  
}  
```

--------------------------------

### Search API request in Bash

Source: https://docs.gnews.io/endpoints/search-endpoint

Requires the jq package to parse JSON responses from the API.

```bash
# Please note that you must have the package jq: https://stedolan.github.io/jq/  
#!/bin/bash  
# TODO: replace API_KEY with your API key.  
apikey='API_KEY'  
url="https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey=$apikey"  
  
data=$(curl -s $url)  
articles=$(echo $data | jq '.articles')  
articles_length=$(echo $articles | jq length)  
echo $articles_length  
  
for ((i = 0; i < $articles_length; i++)); do  
  echo $i  
  # articles[i].title  
title=$(echo $articles | jq ".[ $i].title")  
  echo "Title: $title"  
  # articles[i].description  
description=$(echo $articles | jq ".[ $i].description")  
  echo "Description: $description"  
  # You can replace {property} below with any of the article properties returned by the API.  
  # articles[i].{property}  
  # {property}=$(echo $articles | jq ".[ $i].{property}")  
  # echo "${property}"  
  
  # Delete this line to display all the articles returned by the request. Currently only the first article is displayed.  
  break  
done  
```

--------------------------------

### Search Articles with C#

Source: https://docs.gnews.io/endpoints/search-endpoint

Uses HttpClient and Newtonsoft.Json to fetch and deserialize GNews API search results into strongly-typed objects.

```csharp
// https://www.newtonsoft.com/json  
// dotnet add package Newtonsoft.Json  
// This library will be used to parse the JSON data returned by the API.  
using Newtonsoft.Json;  
  
// TODO: replace API_KEY with your API key.  
const string API_KEY = "API_KEY";  
const string URL = $"https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey={API_KEY}";  
  
HttpClient client = new HttpClient();  
HttpResponseMessage response = await client.GetAsync(URL);  
response.EnsureSuccessStatusCode();  
string responseBody = await response.Content.ReadAsStringAsync();  
var data = JsonConvert.DeserializeObject<ApiResponse>(responseBody);  
List<Article> articles = data.Articles;  
  
for (int i = 0; i < articles.Count; i++)  
{  
  // articles[i].title  
  Console.WriteLine($"Title: {articles[i].Title}");  
  // articles[i].description  
  Console.WriteLine($"Description: {articles[i].Description}");  
  // You can replace {property} below with any of the article properties returned by the API.  
  // articles[i].{property}  
  // Console.WriteLine($"{articles[i].{property}}");  
  // Note that {property} must be compliant with the definition of class Article.  
  
  // Delete this line to display all the articles returned by the request. Currently only the first article is displayed.  
  break;  
}  
  
class ApiResponse  
{  
  public int TotalArticles { get; set; }  
  public List<Article> Articles { get; set; } = new List<Article>();  
}  
  
class Article  
{  
  public string Id { get; set; } = "";  
  public string Title { get; set; } = "";  
  public string Description { get; set; } = "";  
  public string Content { get; set; } = "";  
  public string Url { get; set; } = "";  
  public string Image { get; set; } = "";  
  public string PublishedAt { get; set; } = "";  
  public string Lang { get; set; } = "";  
  public Source Source { get; set; } = new Source();  
}  
  
class Source  
{  
  public string Id { get; set; } = "";  
  public string Name { get; set; } = "";  
  public string Url { get; set; } = "";  
  public string Country { get; set; } = "";  
}
```

--------------------------------

### Fetch Top Headlines with JavaScript

Source: https://docs.gnews.io/endpoints/top-headlines-endpoint

Uses the Fetch API to retrieve and parse JSON data from the top-headlines endpoint.

```javascript
// TODO: replace API_KEY with your API key.  
apikey = 'API_KEY';  
category = 'general';  
url = 'https://gnews.io/api/v4/top-headlines?category=' + category + '&lang=en&country=us&max=10&apikey=' + apikey;  
  
fetch(url)  
  .then(function (response) {  
    return response.json();  
  })  
  .then(function (data) {  
    articles = data.articles;  
  
    for (i = 0; i < articles.length; i++) {  
      // articles[i].title  
      console.log("Title: " + articles[i]['title']);  
      // articles[i].description  
      console.log("Description: " + articles[i]['description']);  
      // You can replace {property} below with any of the article properties returned by the API.  
      // articles[i].{property}  
      // console.log(articles[i]['{property}']);  
  
      // Delete this line to display all the articles returned by the request. Currently only the first article is displayed.  
      break;  
    }  
  });
```

--------------------------------

### Authentication Methods

Source: https://docs.gnews.io/authentication

The GNews API supports authentication via query parameter or HTTP header.

```APIDOC
## Authentication

### Description
All requests to the GNews API must be authenticated using an API key obtained from your dashboard.

### Authentication Methods
- **Query Parameter**: Include the key in the URL using the `apikey` parameter (e.g., `GET https://gnews.io/api/v4/{endpoint}?apikey=YOUR_API_KEY`).
- **HTTP Header**: Include the key in the request header using `X-Api-Key`.

### Error Handling
- **401 Unauthorized**: Returned if the API key is missing or invalid.
```

--------------------------------

### Search API request in PHP

Source: https://docs.gnews.io/endpoints/search-endpoint

Uses cURL to fetch search results and iterates through the articles array.

```php
<?php  
// TODO: replace API_KEY with your API key.  
$apikey = 'API_KEY';  
$url = "https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey=$apikey";  
  
$ch = curl_init();  
curl_setopt($ch, CURLOPT_URL, $url);  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);  
$data = json_decode(curl_exec($ch), true);  
curl_close($ch);  
$articles = $data['articles'];  
  
for ($i = 0; $i < count($articles); $i++) {  
    // articles[i].title  
    echo "Title: " . $articles[$i]['title'] . "\n";  
    // articles[i].description  
    echo "Description: " . $articles[$i]['description'] . "\n";  
    // You can replace {property} below with any of the article properties returned by the API.  
    // articles[i].{property}  
    // echo $articles[$i]['{property}'] . "\n";  
  
    // Delete this line to display all the articles returned by the request. Currently only the first article is displayed.  
    break;  
}  
```

--------------------------------

### Search Articles with Python

Source: https://docs.gnews.io/endpoints/search-endpoint

Uses urllib and json libraries to fetch and parse search results from the GNews API.

```python
# https://docs.python.org/3/library/json.html  
# This library will be used to parse the JSON data returned by the API.  
import json  
# https://docs.python.org/3/library/urllib.request.html#module-urllib.request  
# This library will be used to fetch the API.  
import urllib.request  
  
# TODO: replace API_KEY with your API key.  
apikey = "API_KEY"  
url = f"https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey={apikey}"  
  
with urllib.request.urlopen(url) as response:  
    data = json.loads(response.read().decode("utf-8"))  
    articles = data["articles"]  
  
    for i in range(len(articles)):  
        # articles[i].title  
        print(f"Title: {articles[i]['title']}")  
        # articles[i].description  
        print(f"Description: {articles[i]['description']}")  
        # You can replace {property} below with any of the article properties returned by the API.  
        # articles[i].{property}  
        # print(f"{articles[i]['{property}']}")  
  
        # Delete this line to display all the articles returned by the request. Currently only the first article is displayed.  
        break
```

--------------------------------

### API Error Response Formats

Source: https://docs.gnews.io/error-handling

Standard JSON structures returned by the API when a request fails.

```json
{
  "errors": [
    "<error message>"
  ]
}
```

```json
{
  "errors": {
    "attribute": "<error message>"
  }
}
```

--------------------------------

### Top Headlines Endpoint

Source: https://docs.gnews.io/category/endpoints

This endpoint allows you to search for current trending articles based on Google News ranking.

```APIDOC
## Top Headlines Endpoint

### Description
This endpoint allows you to search for current trending articles, the articles that are selected to be returned by this endpoint are based on the Google News ranking. There are 9 categories available, the default category is "general".
```

--------------------------------

### Search Endpoint

Source: https://docs.gnews.io/category/endpoints

This endpoint allows you to search for news articles through a combination of keywords.

```APIDOC
## Search Endpoint

### Description
This endpoint allows you to search for news articles through a combination of keywords.
```
Tokens:
Raw