Articles

Get trending top headlines

Returns the current trending articles of a category, based on the Google News ranking. See https://docs.gnews.io/endpoints/top-headlines-endpoint

get/top-headlines

Request

  • Base URL: https://gnews.io/api/v4
  • URL: https://gnews.io/api/v4/top-headlines
  • Auth: one of:
    • API key in header X-Api-Key
    • API key in query parameter apikey

Query parameters

category'general' | 'world' | 'nation' | 'business' | 'technology' | 'entertainment' | 'sports' | 'science' | 'health'
lang'ar' | 'bn' | 'bg' | 'ca' | 'zh' | 'cs' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'de' | 'el' | 'gu' | 'he' | 'hi' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lv' | 'lt' | 'ml' | 'mr' | 'no' | 'pl' | 'pt' | 'pa' | 'ro' | 'ru' | 'sk' | 'sl' | 'es' | 'sv' | 'ta' | 'te' | 'th' | 'tr' | 'uk' | 'vi'

2-letter code of the language of the articles. Supported values: ar (Arabic), bn (Bengali), bg (Bulgarian), ca (Catalan), zh (Chinese), cs (Czech), nl (Dutch), en (English), et (Estonian), fi (Finnish), fr (French), de (German), el (Greek), gu (Gujarati), he (Hebrew), hi (Hindi), hu (Hungarian), id (Indonesian), it (Italian), ja (Japanese), ko (Korean), lv (Latvian), lt (Lithuanian), ml (Malayalam), mr (Marathi), no (Norwegian), pl (Polish), pt (Portuguese), pa (Punjabi), ro (Romanian), ru (Russian), sk (Slovak), sl (Slovenian), es (Spanish), sv (Swedish), ta (Tamil), te (Telugu), th (Thai), tr (Turkish), uk (Ukrainian), vi (Vietnamese).

country'ar' | 'au' | 'at' | 'bd' | 'be' | 'bw' | 'br' | 'bg' | 'ca' | 'cl' | 'cn' | 'co' | 'cu' | 'cz' | 'eg' | 'ee' | 'et' | 'fi' | 'fr' | 'de' | 'gh' | 'gr' | 'hk' | 'hu' | 'in' | 'id' | 'ie' | 'il' | 'it' | 'jp' | 'ke' | 'lv' | 'lb' | 'lt' | 'my' | 'mx' | 'ma' | 'na' | 'nl' | 'nz' | 'ng' | 'no' | 'pk' | 'pe' | 'ph' | 'pl' | 'pt' | 'ro' | 'ru' | 'sa' | 'sn' | 'sg' | 'sk' | 'si' | 'za' | 'kr' | 'es' | 'se' | 'ch' | 'tw' | 'tz' | 'th' | 'tr' | 'ug' | 'ua' | 'ae' | 'gb' | 'us' | 've' | 'vn' | 'zw'

2-letter code of the country to get headlines for. Most articles come from sources based in that country, the others are relevant to it. Supported values: ar (Argentina), au (Australia), at (Austria), bd (Bangladesh), be (Belgium), bw (Botswana), br (Brazil), bg (Bulgaria), ca (Canada), cl (Chile), cn (China), co (Colombia), cu (Cuba), cz (Czechia), eg (Egypt), ee (Estonia), et (Ethiopia), fi (Finland), fr (France), de (Germany), gh (Ghana), gr (Greece), hk (Hong Kong), hu (Hungary), in (India), id (Indonesia), ie (Ireland), il (Israel), it (Italy), jp (Japan), ke (Kenya), lv (Latvia), lb (Lebanon), lt (Lithuania), my (Malaysia), mx (Mexico), ma (Morocco), na (Namibia), nl (Netherlands), nz (New Zealand), ng (Nigeria), no (Norway), pk (Pakistan), pe (Peru), ph (Philippines), pl (Poland), pt (Portugal), ro (Romania), ru (Russia), sa (Saudi Arabia), sn (Senegal), sg (Singapore), sk (Slovakia), si (Slovenia), za (South Africa), kr (South Korea), es (Spain), se (Sweden), ch (Switzerland), tw (Taiwan), tz (Tanzania), th (Thailand), tr (Turkey), ug (Uganda), ua (Ukraine), ae (United Arab Emirates), gb (United Kingdom), us (United States), ve (Venezuela), vn (Vietnam), zw (Zimbabwe).

maxinteger

Number of articles returned, from 1 to 100. The maximum depends on your plan (10 on the Free plan).

nullablestring

Attributes allowed to be null, comma-separated: description, content, image. By default these attributes are never null.

fromstring date-time

Minimum publication date (included), ISO 8601, e.g. 2025-07-18T21:32:58.500Z. Bounded by your plan, see https://docs.gnews.io/article-availability

tostring date-time

Maximum publication date (included), ISO 8601, e.g. 2025-07-18T21:32:58.500Z. Bounded by your plan, see https://docs.gnews.io/article-availability

qstring

Optional keywords to filter the headlines. Keywords to search for, 200 characters at most. Supports exact phrases in quotes, AND, OR, NOT and parentheses; OR takes precedence over AND. Special characters must be inside quotes. See https://docs.gnews.io/query-syntax

pageinteger

Page number, starting at 1. Pages hold max articles each, and pagination stops at the first 1,000 articles.

truncate'content'

Set to content to truncate the content attribute. Content is always truncated on the Free plan.

Response

Top headlines. source.country is not returned by this endpoint.

totalArticlesinteger required

Total number of articles matching the request, not the number returned.

Changes

No recorded changes to this operation across all 1 revision of this API.