Top Headlines Endpoint

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

HTTP Request

GET https://gnews.io/api/v4/top-headlines?category=general&apikey=API_KEY

Query Parameters

Parameter Name	Default Value	Description
category	general	This parameter allows you to change the category for the request. The available categories are : general, world, nation, business, technology, entertainment, sports, science and health.
lang	Any	This parameter allows you to specify the language of the news articles returned by the API. You have to set as value the 2 letters code of the language you want to filter. See the list of supported languages.
country	Any	This setting allows you to filter articles by country. Most articles will come from sources originating in that country, and the others will be relevant to that country. You have to set as value the 2 letters code of the country you want to filter. See the list of supported countries.
max	10	This parameter allows you to specify the number of news articles returned by the API. The minimum value of this parameter is 1 and the maximum value is 100. The value you can set depends on your subscription. See the pricing for more information.
nullable	None	This parameter allows you to specify the attributes that you allow to return null values. The attributes that can be set are description, content and image. It is possible to combine several attributes by separating them with a comma. For example: description,content
from	None	This parameter allows you to filter the articles that have a publication date greater than or equal to the specified value. The date must comply with ISO 8601 format. For example: 2025-07-18T21:32:58.500Z
to	None	This parameter allows you to filter the articles that have a publication date smaller than or equal to the specified value. The date must comply with ISO 8601 format. For example: 2025-07-18T21:32:58.500Z
q	None	This parameter allows you to specify your search keywords to find the news articles you are looking for. The keywords will be used to return the most relevant articles. It is possible to use logical operators with keywords, see the section on query syntax. Maximum 200 characters.
page	1	This parameter allows you to control the pagination of the results returned by the API. The paging behavior is closely related to the value of the max parameter. The first page is page 1, then you have to increment by 1 to go to the next page. Let's say that the value of the max parameter is 10, then the first page will contain the first 10 articles returned by the API (articles 1 to 10), page 2 will return the next 10 articles (articles 11 to 20), etc. For performance reasons, it is not possible to paginate more than 1000 articles.
expand	None	This parameter will only work if you have a paid subscription activated on your account. This parameter allows you to return in addition to other data, the full content of the articles. To get the full content of the articles, the parameter must be set to content, as follows expand=content

Code Examples

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;
    }
  });

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

C#

// 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; } = "";
}

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;
}

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

Alternatively, you can use our official libraries available at gnews.io/libraries.

Supported Languages

Name	Code
Arabic	ar
Bengali	bn
Bulgarian	bg
Catalan	ca
Chinese	zh
Dutch	nl
English	en
Estonian	et
Finnish	fi
French	fr
German	de
Greek	el
Gujarati	gu
Hebrew	he
Hindi	hi
Hungarian	hu
Indonesian	id
Italian	it
Japanese	ja
Korean	ko
Latvian	lv
Lithuanian	lt
Malayalam	ml
Marathi	mr
Norwegian	no
Polish	pl
Portuguese	pt
Punjabi	pa
Romanian	ro
Russian	ru
Serbian	sl
Slovak	sk
Spanish	es
Swedish	sv
Tamil	ta
Telugu	te
Thai	th
Turkish	tr
Ukrainian	uk
Vietnamese	vi

Supported Countries

Name	Code
Argentina	ar
Australia	au
Austria	at
Bangladesh	bd
Belgium	be
Brazil	br
Bulgaria	bg
Canada	ca
Chile	cl
China	cn
Colombia	co
Cuba	cu
Czech Republic	cz
Egypt	eg
Estonia	ee
Ethiopia	et
Finland	fi
France	fr
Germany	de
Ghana	gh
Greece	gr
Hong Kong	hk
Hungary	hu
India	in
Indonesia	id
Ireland	ie
Israel	il
Italy	it
Japan	jp
Kenya	ke
Lebanon	lb
Lithuania	lt
Latvia	lv
Malaysia	my
Mexico	mx
Morocco	ma
Namibia	na
Netherlands	nl
New Zealand	nz
Nigeria	ng
Norway	no
Pakistan	pk
Peru	pe
Philippines	ph
Poland	pl
Portugal	pt
Romania	ro
Russia	ru
Saudi Arabia	sa
Senegal	sn
Serbia	si
Singapore	sg
Slovakia	sk
South Africa	za
South Korea	kr
Spain	es
Sweden	se
Switzerland	ch
Taiwan	tw
Tanzania	tz
Thailand	th
Turkey	tr
Uganda	ug
Ukraine	ua
United Arab Emirates	ae
United Kingdom	gb
United States	us
Venezuela	ve
Vietnam	vn
Zimbabwe	zw