Introduction

Data returned by the API

{
    "timestamp": 1561732525,
    "articleCount": 10,
    "articles": [
        {
            "title": "A Living Example",
            "description": "City Councilmember Dr. Shahid Shafi Exemplifies The American Dream.",
            "url": "https://www.southlakestyle.com/community/people/a-living-example/",
            "image": "https://lh6.googleusercontent.com/proxy/y6oUWR3-7B3gA3yE5gb6IQLnIUK5OePriC...",
            "publishedAt": "2019-06-28 09:32:37 UTC",
            "source": {
                "name": "Southlake Style",
                "url": "https://www.southlakestyle.com"
            }
        }
    ]
}

GNews is an API for searching articles from google news. We also provide the top headlines and the news from a specific topic like world, business, sports...

Description of data returned by the API:

Property	Description
timestamp	The timestamp where the server finished processing your request
articleCount	The count of returned articles
articles[i].title	The title of the article
articles[i].description	The short description of the article
articles[i].url	The URL to the article
articles[i].image	The main article image
articles[i].publishedAt	The published date of the article
articles[i].source.name	The name of the media or the source
articles[i].source.url	The source website URL

Authentication

To authorize, use this code:

<?php
$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, 'https://gnews.io/api/v3/{endpoint}?token=API-Token'); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); 
$data = curl_exec($ch); 
curl_close($ch); 

curl "https://gnews.io/api/v3/{endpoint}?token=API-Token"

fetch('https://gnews.io/api/v3/{endpoint}?token=API-Token');

Make sure to replace API-Token with your API token.

Authentication is handled by your API token. You must pass your token as GET parameter. https://gnews.io/api/v3/{endpoint}?token=API-Token

Search News

<?php
$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, 'https://gnews.io/api/v3/search?token=API-Token'); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); 
$data = curl_exec($ch); 
curl_close($ch); 

curl "https://gnews.io/api/v3/search?q=example&token=API-Token"

fetch('https://gnews.io/api/v3/search?q=example&token=API-Token')
    .then(function (response) {
        return response.json();
    })
    .then(function (data) {
        console.log(data);
    });

The above code returns JSON structured like this:

{
    "timestamp": 1561732525,
    "articleCount": 10,
    "articles": [
        {
            "title": "A Living Example",
            "description": "City Councilmember Dr. Shahid Shafi Exemplifies The American Dream.",
            "url": "https://www.southlakestyle.com/community/people/a-living-example/",
            "image": "https://lh6.googleusercontent.com/proxy/y6oUWR3-7B3gA3yE5gb6IQLnIUK5OePriC...",
            "publishedAt": "2019-06-28 09:32:37 UTC",
            "source": {
                "name": "Southlake Style",
                "url": "https://www.southlakestyle.com"
            }
        }
    ]
}

This endpoint search news from keywords.

HTTP Request

GET https://gnews.io/api/v3/search?q=example&token=API-Token

Query Parameters

Parameter	Default	Description
q	None	This is the purpose of your search. Articles returned are based on given keywords.
lang	en	The language of the returned articles. See languages list.
country	us	The based country where articles are searched. See countries list.
max	10	The maximum number of articles returned. 100 is the maximum.
image	optional	Filters articles that have an image or not. Values are required or optional.
mindate	None	Filters articles where their published date are higher or equal than min date. Format Y-m-d (e.g. 2020-01-01).
maxdate	None	Filters articles where their published date are less or equal than max date. Format Y-m-d (e.g. 2020-01-01).
in	all	Search from keywords in specific article section. Sections are all or title.

Search Operators

Operator AND

The space between each keyword is by default consider as an AND, the following search : example test will match all articles that contain both keywords.

Operator OR

To use the OR operator, replace the space between two keyword by this | the following search : example | test will match all articles that contain at least one of those two keywords.

Phrase search operator (Exact match)

To use the phrase search operator surrounds your query by quotes "{query}", the following search : "example test" will match all articles that contain exactly the same keywords in the same order.

Operator NOT

To use the NOT operator add before each keyword this - or this ! the following search : "example !test" will match all articles that contain example but not test.

Top News

<?php
$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, 'https://gnews.io/api/v3/top-news?token=API-Token'); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); 
$data = curl_exec($ch); 
curl_close($ch); 

curl "https://gnews.io/api/v3/top-news?token=API-Token"

fetch('https://gnews.io/api/v3/top-news?&token=API-Token')
    .then(function (response) {
        return response.json();
    })
    .then(function (data) {
        console.log(data);
    });

The above code returns JSON structured like this:

{
    "timestamp": 1561732525,
    "articleCount": 10,
    "articles": [
        {
            "title": "A Living Example",
            "description": "City Councilmember Dr. Shahid Shafi Exemplifies The American Dream.",
            "url": "https://www.southlakestyle.com/community/people/a-living-example/",
            "image": "https://lh6.googleusercontent.com/proxy/y6oUWR3-7B3gA3yE5gb6IQLnIUK5OePriC...",
            "publishedAt": "2019-06-28 09:32:37 UTC",
            "source": {
                "name": "Southlake Style",
                "url": "https://www.southlakestyle.com"
            }
        }
    ]
}

This endpoint retrieves top news.

HTTP Request

GET https://gnews.io/api/v3/top-news?token=API-Token

Query Parameters

Parameter	Default	Description
lang	en	The language of the returned articles. See languages list.
country	us	The based country where articles are searched. See countries list.
max	10	The maximum number of articles returned. 100 is the maximum.
image	optional	Filters articles that have an image or not. Values are required or optional.

News from Topic

<?php
$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, 'https://gnews.io/api/v3/topics/{topic}?token=API-Token'); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); 
$data = curl_exec($ch); 
curl_close($ch); 

curl "https://gnews.io/api/v3/topics/{topic}?token=API-Token"

fetch('https://gnews.io/api/v3/topics/{topic}?&token=API-Token')
    .then(function (response) {
        return response.json();
    })
    .then(function (data) {
        console.log(data);
    });

The above code returns JSON structured like this:

{
    "timestamp": 1561732525,
    "articleCount": 10,
    "articles": [
        {
            "title": "A Living Example",
            "description": "City Councilmember Dr. Shahid Shafi Exemplifies The American Dream.",
            "url": "https://www.southlakestyle.com/community/people/a-living-example/",
            "image": "https://lh6.googleusercontent.com/proxy/y6oUWR3-7B3gA3yE5gb6IQLnIUK5OePriC...",
            "publishedAt": "2019-06-28 09:32:37 UTC",
            "source": {
                "name": "Southlake Style",
                "url": "https://www.southlakestyle.com"
            }
        }
    ]
}

This endpoint retrieves news from topic.

HTTP Request

GET https://gnews.io/api/v3/topics/{topic}?token=API-Token

Topics List

Topic	URL
world	https://gnews.io/api/v3/topics/world
nation	https://gnews.io/api/v3/topics/nation
business	https://gnews.io/api/v3/topics/business
technology	https://gnews.io/api/v3/topics/technology
entertainment	https://gnews.io/api/v3/topics/entertainment
sports	https://gnews.io/api/v3/topics/sports
science	https://gnews.io/api/v3/topics/science
health	https://gnews.io/api/v3/topics/health

Query Parameters

Parameter	Default	Description
lang	en	The language of the returned articles. See languages list.
country	us	The based country where articles are searched. See countries list.
max	10	The maximum number of articles returned. 100 is the maximum.
image	optional	Filters articles that have an image or not. Values are required or optional.

Languages

Language	Code
Afrikaans	af
Albanian	sq
Amharic	sm
Arabic	ar
Azerbaijani	az
Basque	eu
Belarusian	be
Bengali	bn
Bihari	bh
Bosnian	bs
Bulgarian	bg
Catalan	ca
Chinese (Simplified)	zh-CN
Chinese (Traditional)	zh-TW
Croatian	hr
Czech	cs
Danish	da
Dutch	nl
English	en
Esperanto	eo
Estonian	et
Faroese	fo
Finnish	fi
French	fr
Frisian	fy
Galician	gl
Georgian	ka
German	de
Greek	el
Gujarati	gu
Hebrew	iw
Hindi	hi
Hungarian	hu
Icelandic	is
Indonesian	id
Interlingua	ia
Irish	ga
Italian	it
Japanese	ja
Javanese	jw
Kannada	kn
Korean	ko
Latin	la
Latvian	lv
Lithuanian	lt
Macedonian	mk
Malay	ms
Malayam	ml
Maltese	mt
Marathi	mr
Nepali	ne
Norwegian	no
Norwegian (Nynorsk)	nn
Occitan	oc
Persian	fa
Polish	pl
Portuguese (Brazil)	pt-BR
Portuguese (Portugal)	pt-PT
Punjabi	pa
Romanian	ro
Russian	ru
Scots Gaelic	gd
Serbian	sr
Sinhalese	si
Slovak	sk
Slovenian	sl
Spanish	es
Sudanese	su
Swahili	sw
Swedish	sv
Tagalog	tl
Tamil	ta
Telugu	te
Thai	th
Tigrinya	ti
Turkish	tr
Ukrainian	uk
Urdu	ur
Uzbek	uz
Vietnamese	vi
Welsh	cy
Xhosa	xh
Zulu	zu

Countries

Country	Code
Afghanistan	af
Albania	al
Algeria	dz
American Samoa	as
Andorra	ad
Angola	ao
Anguilla	ai
Antarctica	aq
Antigua and Barbuda	ag
Argentina	ar
Armenia	am
Aruba	aw
Australia	au
Austria	at
Azerbaijan	az
Bahamas	bs
Bahrain	bh
Bangladesh	bd
Barbados	bb
Belarus	by
Belgium	be
Belize	bz
Benin	bj
Bermuda	bm
Bhutan	bt
Bolivia	bo
Bosnia and Herzegovina	ba
Botswana	bw
Bouvet Island	bv
Brazil	br
British Indian Ocean Territory	io
Brunei Darussalam	bn
Bulgaria	bg
Burkina Faso	bf
Burundi	bi
Cambodia	kh
Cameroon	cm
Canada	ca
Cape Verde	cv
Cayman Islands	ky
Central African Republic	cf
Chad	td
Chile	cl
China	cn
Christmas Island	cx
Cocos (Keeling) Islands	cc
Colombia	co
Comoros	km
Congo	cg
Congo, the Democratic Republic of the	cd
Cook Islands	ck
Costa Rica	cr
Cote D'ivoire	ci
Croatia	hr
Cuba	cu
Cyprus	cy
Czech Republic	cz
Denmark	dk
Djibouti	dj
Dominica	dm
Dominican Republic	do
Ecuador	ec
Egypt	eg
El Salvador	sv
Equatorial Guinea	gq
Eritrea	er
Estonia	ee
Ethiopia	et
Falkland Islands (Malvinas)	fk
Faroe Islands	fo
Fiji	fj
Finland	fi
France	fr
French Guiana	gf
French Polynesia	pf
French Southern Territories	tf
Gabon	ga
Gambia	gm
Georgia	ge
Germany	de
Ghana	gh
Gibraltar	gi
Greece	gr
Greenland	gl
Grenada	gd
Guadeloupe	gp
Guam	gu
Guatemala	gt
Guinea	gn
Guinea-Bissau	gw
Guyana	gy
Haiti	ht
Heard Island and Mcdonald Islands	hm
Holy See (Vatican City State)	va
Honduras	hn
Hong Kong	hk
Hungary	hu
Iceland	is
India	in
Indonesia	id
Iran, Islamic Republic of	ir
Iraq	iq
Ireland	ie
Israel	il
Italy	it
Jamaica	jm
Japan	jp
Jordan	jo
Kazakhstan	kz
Kenya	ke
Kiribati	ki
Korea, Democratic People's Republic of	kp
Korea, Republic of	kr
Kuwait	kw
Kyrgyzstan	kg
Lao People's Democratic Republic	la
Latvia	lv
Lebanon	lb
Lesotho	ls
Liberia	lr
Libyan Arab Jamahiriya	ly
Liechtenstein	li
Lithuania	lt
Luxembourg	lu
Macao	mo
Macedonia, the Former Yugosalv Republic of	mk
Madagascar	mg
Malawi	mw
Malaysia	my
Maldives	mv
Mali	ml
Malta	mt
Marshall Islands	mh
Martinique	mq
Mauritania	mr
Mauritius	mu
Mayotte	yt
Mexico	mx
Micronesia, Federated States of	fm
Moldova, Republic of	md
Monaco	mc
Mongolia	mn
Montserrat	ms
Morocco	ma
Mozambique	mz
Myanmar	mm
Namibia	na
Nauru	nr
Nepal	np
Netherlands	nl
Netherlands Antilles	an
New Caledonia	nc
New Zealand	nz
Nicaragua	ni
Niger	ne
Nigeria	ng
Niue	nu
Norfolk Island	nf
Northern Mariana Islands	mp
Norway	no
Oman	om
Pakistan	pk
Palau	pw
Palestinian Territory, Occupied	ps
Panama	pa
Papua New Guinea	pg
Paraguay	py
Peru	pe
Philippines	ph
Pitcairn	pn
Poland	pl
Portugal	pt
Puerto Rico	pr
Qatar	qa
Reunion	re
Romania	ro
Russian Federation	ru
Rwanda	rw
Saint Helena	sh
Saint Kitts and Nevis	kn
Saint Lucia	lc
Saint Pierre and Miquelon	pm
Saint Vincent and the Grenadines	vc
Samoa	ws
San Marino	sm
Sao Tome and Principe	st
Saudi Arabia	sa
Senegal	sn
Serbia and Montenegro	cs
Seychelles	sc
Sierra Leone	sl
Singapore	sg
Slovakia	sk
Slovenia	si
Solomon Islands	sb
Somalia	so
South Africa	za
South Georgia and the South Sandwich Islands	gs
Spain	es
Sri Lanka	lk
Sudan	sd
Suriname	sr
Svalbard and Jan Mayen	sj
Swaziland	sz
Sweden	se
Switzerland	ch
Syrian Arab Republic	sy
Taiwan, Province of China	tw
Tajikistan	tj
Tanzania, United Republic of	tz
Thailand	th
Timor-Leste	tl
Togo	tg
Tokelau	tk
Tonga	to
Trinidad and Tobago	tt
Tunisia	tn
Turkey	tr
Turkmenistan	tm
Turks and Caicos Islands	tc
Tuvalu	tv
Uganda	ug
Ukraine	ua
United Arab Emirates	ae
United Kingdom	uk
United States	us
United States Minor Outlying Islands	um
Uruguay	uy
Uzbekistan	uz
Vanuatu	vu
Venezuela	ve
Viet Nam	vn
Virgin Islands, British	vg
Virgin Islands, U.S.	vi
Wallis and Futuna	wf
Western Sahara	eh
Yemen	ye
Zambia	zm
Zimbabwe	zw

Errors

The API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
408	Request Timeout -- You're making too many query. Maximum is 3 requests per second.
429	Too Many Requests -- You're reach your daily limit.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.