NAV Navbar Icon
php javascript shell

Introduction

Data returned by the API

{
    "totalArticles": 4,
    "articles": [
        {
            "title": "Nick Leeder appointed as latest head of Google Ireland",
            "description": "Google has announced that Nick Leeder will replace Fionnuala Meehan as the head of its Irish operation starting in April.",
            "content": "Google has announced that Nick Leeder will replace Fionnuala Meehan as the head of its Irish operation starting in April.\nWhile its staff continue to work from home in the midst of the coronavirus pandemic, Google Ireland will have a new person leadi... [1514 chars]",
            "url": "https://www.siliconrepublic.com/companies/nick-leeder-google-ireland",
            "image": "https://www.siliconrepublic.com/wp-content/uploads/2020/03/BOO_3353_2.jpg",
            "publishedAt": "2020-03-23T13:58:53Z",
            "source": {
                "name": "Silicon Republic",
                "url": "https://www.siliconrepublic.com/"
            }
        }
    ]
}

GNews is an API to search for articles from a variety of sources, including Google News. We also provide top headlines from which you can filter by topic such as world, business, sports...

Description of data returned by the API:

Property Description
totalArticles The total number of articles found by your query
articles[i].title The title of the article
articles[i].description The description of the article
articles[i].content The full content of the article
articles[i].url The URL to the article
articles[i].image The main article image
articles[i].publishedAt The publish 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/v4/{endpoint}?token=API-Token');
$data = curl_exec($ch);
curl_close($ch);

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

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

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

If you do not have an API Token yet, you must first create an account. Once you have created your account you will find your API Token in your dashboard.

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

Search Endpoint

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://gnews.io/api/v4/search?q=example&token=API-Token');
$data = curl_exec($ch);
curl_close($ch);

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

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

The above command returns JSON structured like this:

{
    "totalArticles": 4,
    "articles": [
        {
            "title": "Nick Leeder appointed as latest head of Google Ireland",
            "description": "Google has announced that Nick Leeder will replace Fionnuala Meehan as the head of its Irish operation starting in April.",
            "content": "Google has announced that Nick Leeder will replace Fionnuala Meehan as the head of its Irish operation starting in April.\nWhile its staff continue to work from home in the midst of the coronavirus pandemic, Google Ireland will have a new person leadi... [1514 chars]",
            "url": "https://www.siliconrepublic.com/companies/nick-leeder-google-ireland",
            "image": "https://www.siliconrepublic.com/wp-content/uploads/2020/03/BOO_3353_2.jpg",
            "publishedAt": "2020-03-23T13:58:53Z",
            "source": {
                "name": "Silicon Republic",
                "url": "https://www.siliconrepublic.com/"
            }
        }
    ]
}

This endpoint allows you to search articles from keywords.

HTTP Request

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

Query Parameters

Parameter Default Description
q None This is the purpose of your search. Articles returned are filtered by the given keywords.
lang Any Set the language of returned articles (list of supported languages).
country Any Set the country of returned articles (list of supported countries).
max 10 Set the maximum number of articles returned per request. 100 is the maximum value. The maximum value allowed depend on your plan (see pricing for more information).
page 1 Use this parameter to paginate results (Only for subscribers).
in title,description Set the attributes of the articles in which your query will be searched. The attributes are title, description and content. You can specify several attributes by separating them with commas (e.g. title,description)
nullable None Set the article attributes where you allow null values. The attributes are description, content and image. You can specify several attributes by separating them with commas (e.g. description,image)
from None Keep articles with a publication date greater than or equal to the given date. ISO 8601 format (e.g. 2022-01-19T14:08:37Z)
to None Keep articles with a publication date less than or equal to the given date. ISO 8601 format (e.g. 2022-01-19T14:08:37Z)
sortby publishedAt Set the order in which the items are sorted. (publishedAt: sort articles first according to the most recent date of publication, relevance: sort articles that most closely match the query)
expand None Set this parameter with content and you will be able to get the full article content (Only for subscribers).

Search Operators

Note

1. The query must be URL-encoded.

2. You cannot use other characters than alphabetic characters outside of quotes context.

e.g.

Invalid Valid
Hello! "Hello!"
Left - Right "Left - Right"
Question? "Question?"

Phrase search operator (Exact match)

To use the phrase search operator surrounds your phrase with quotes like so "Apple iPhone".

Operator AND

There are two ways to use the AND operator.

  1. Add this  AND  between each word or phrase (e.g. Apple AND Microsoft)
  2. Add a space between each word or phrase (e.g. Apple Microsoft)

Operator OR

First of all, note that the operator OR has a higher precedence than the operator AND. To use the OR operator add this  OR  between each word or phrase (e.g. Apple OR Microsoft).

Due to the higher precedence of the operator OR the following query will not work as expected Apple AND iPhone OR Microsoft. When we read this expression we thought that the query will look first for articles that contain the word Apple and iPhone and then if no article found, look for articles that contain Microsoft. Actually this is not what is going to happen the OR will be executed first so the result will make no sense because the query will look for Apple AND iPhone or Apple AND Microsoft. To fix this query we have to add parenthesises, like so (Apple AND iPhone) OR Microsoft.

Operator NOT

To use the NOT operator add this NOT  before each word or phrase (e.g. Apple AND NOT iPhone). Articles that contain the word iPhone will be removed from the results.

Examples of queries

Query
Microsoft Windows 10
Apple OR Microsoft
Apple AND NOT iPhone
(Windows 7) AND (Windows 10)
"Apple iPhone X" AND NOT "Apple iPhone 7"
Intel AND (i7 OR i9)
(Intel AND (i7 OR "i9-10900K")) AND NOT AMD AND NOT "i7-9700K"

Top Headlines Endpoint

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

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

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

The above command returns JSON structured like this:

{
    "totalArticles": 4,
    "articles": [
        {
            "title": "Nick Leeder appointed as latest head of Google Ireland",
            "description": "Google has announced that Nick Leeder will replace Fionnuala Meehan as the head of its Irish operation starting in April.",
            "content": "Google has announced that Nick Leeder will replace Fionnuala Meehan as the head of its Irish operation starting in April.\nWhile its staff continue to work from home in the midst of the coronavirus pandemic, Google Ireland will have a new person leadi... [1514 chars]",
            "url": "https://www.siliconrepublic.com/companies/nick-leeder-google-ireland",
            "image": "https://www.siliconrepublic.com/wp-content/uploads/2020/03/BOO_3353_2.jpg",
            "publishedAt": "2020-03-23T13:58:53Z",
            "source": {
                "name": "Silicon Republic",
                "url": "https://www.siliconrepublic.com/"
            }
        }
    ]
}

This endpoint allows you to find the top headlines and breaking news, you can also specify a topic and use keywords. Articles are sorted by the most recent publish date first.

HTTP Request

GET https://gnews.io/api/v4/top-headlines?token=API-Token

Query Parameters

Parameter Default Description
topic breaking-news Set the articles topic. Topics available are breaking-news, world, nation, business, technology, entertainment, sports, science and health.
lang Any Set the language of returned articles (list of supported languages).
country Any Set the country of returned articles (list of supported countries).
max 10 Set the maximum number of articles returned per request. 100 is the maximum value. The maximum value allowed depend on your plan (see pricing for more information).
page 1 Use this parameter to paginate results (Only for subscribers).
nullable None Set the article attributes where you allow null values. Attributes are description, content and image. You can specify several attributes by separating them with commas (e.g. description,image)
from None Keep articles with a publication date greater than or equal to the given date. ISO 8601 format (e.g. 2022-01-19T14:08:37Z)
to None Keep articles with a publication date less than or equal to the given date. ISO 8601 format (e.g. 2022-01-19T14:08:37Z)
q None Keep articles that matched keywords.
expand None Set this parameter with content and you will be able to get the full article content (Only for subscribers).

Note

Spain (es) is not supported as value of parameter "country" for the top headlines endpoint.

Languages

Arabic ar
German de
Greek el
English en
Spanish es
French fr
Hebrew he
Hindi hi
Italian it
Japanese ja
Malayalam ml
Marathi mr
Dutch nl
Norwegian no
Portuguese pt
Romanian ro
Russian ru
Swedish sv
Tamil ta
Telugu te
Ukrainian uk
Chinese zh

Countries

Australia au
Brazil br
Canada ca
Switzerland ch
China cn
Germany de
Egypt eg
Spain es
France fr
United Kingdom gb
Greece gr
Hong Kong hk
Ireland ie
Israel il
India in
Italy it
Japan jp
Netherlands nl
Norway no
Peru pe
Philippines ph
Pakistan pk
Portugal pt
Romania ro
Russian Federation ru
Sweden se
Singapore sg
Taiwan, Province of China tw
Ukraine ua
United States us

Errors

The API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is not valid.
401 Unauthorized -- Your API key is incorrect.
403 Forbidden -- You have reached your daily request limit, the next reset is at 00:00 UTC.
429 Too Many Requests -- You have made more requests per second than you are allowed.
500 Internal Server Error -- We had a problem with our server. Try again later.
php javascript shell