NAV Navbar
php javascript shell

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