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.
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. See languages list. |
country | Any | Set the country of returned articles. See countries list. |
max | 10 | Set the maximum number of articles returned per query. 100 is the maximum value. The maximum value allowed depend on your plan (FREE has 10, PLUS has 30 and PRO has 100). |
page | 1 | Use this parameter to paginate results (Only for PRO and PLUS subscribers). |
in | title,description | Set the attributes of the articles in which your query will be searched. The attributes are title, description and content. |
nullable | None | Set the article attributes where you allow null values. The attributes are description, content and image. |
from | None | Keep articles with a publication date greater than or equal to the given date. ISO 8601 format (e.g. 2021-03-05T07:13:55Z) |
to | None | Keep articles with a publication date less than or equal to the given date. ISO 8601 format (e.g. 2021-03-05T07:13:55Z) |
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 PRO and PLUS 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.
- Add this AND between each word or phrase (e.g. Apple AND Microsoft)
- 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. See languages list. |
country | Any | Set the country of returned articles. See countries list. |
max | 10 | Set the maximum number of articles returned per query. 100 is the maximum value. The maximum value allowed depend on your plan (FREE has 10, PLUS has 30 and PRO has 100). |
page | 1 | Use this parameter to paginate results (Only for PRO and PLUS subscribers). |
nullable | None | Set the article attributes where you allow null values. Attributes are description, content and image. |
from | None | Keep articles with a publication date greater than or equal to the given date. ISO 8601 format (e.g. 2021-03-05T07:13:55Z) |
to | None | Keep articles with a publication date less than or equal to the given date. ISO 8601 format (e.g. 2021-03-05T07:13:55Z) |
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 PRO and PLUS 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 invalid. |
401 | Unauthorized -- Your API key is wrong. |
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. |