Introduction (V3 Documentation)
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. 2025-07-01). |
maxdate | None | Filters articles where their published date are less or equal than max date.
Format Y-m-d (e.g. 2025-07-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.
Operator NOT
To use the NOT operator add before each keyword this character ! the following search : "example !test" will match all articles that contain example but not test.
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. Note that you cannot mix this operator with AND, OR and NOT.
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 |
Azerbaijani | az |
Basque | eu |
Belarusian | be |
Bengali | bn |
Bihari | bh |
Bosnian | bs |
Bulgarian | bg |
Catalan | ca |
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 |
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 |
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. |
403 | Forbidden -- You have reached your daily request limit, the next reset is at 00:00 UTC. |
429 | Too Many Requests -- You make too many requests in too short a period of time. |
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. |