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-Tokenwith 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-09-01). |
| maxdate | None | Filters articles where their published date are less or equal than max date. Format Y-m-d (e.g. 2020-09-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 |
| 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've reached 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. |