Search Endpoint

This endpoint allows you to search for news articles through a combination of keywords.

HTTP Request

GEThttps://gnews.io/api/v4/search?q=example&apikey=YOUR_API_KEY

Query Parameters

Parameter Name	Default Value	Description
q	None	This parameter is mandatory. This parameter allows you to specify your search keywords to find the news articles you are looking for. The keywords will be used to return the most relevant articles. It is possible to use logical operators with keywords, see the section on query syntax. Maximum 200 characters.
lang	Any	This parameter allows you to specify the language of the news articles returned by the API. You have to set as value the 2 letters code of the language you want to filter. See the list of supported languages.
country	Any	This parameter allows you to specify the country where the news articles returned by the API were published, the contents of the articles are not necessarily related to the specified country. You have to set as value the 2 letters code of the country you want to filter. See the list of supported countries.
max	10	This parameter allows you to specify the number of news articles returned by the API. The minimum value of this parameter is 1 and the maximum value is 100. The value you can set depends on your subscription. See the pricing for more information.
in	title,description	This parameter allows you to choose in which attributes the keywords are searched. The attributes that can be set are title, description and content. It is possible to combine several attributes by separating them with a comma. For example: title,description
nullable	None	This parameter allows you to specify the attributes that you allow to return null values. The attributes that can be set are description, content and image. It is possible to combine several attributes by separating them with a comma. For example: description,content
from	None	This parameter allows you to filter the articles that have a publication date greater than or equal to the specified value. The date must comply with ISO 8601 format. For example: 2025-07-18T21:32:58.500Z How far back you can go depends on your subscription, see article availability.
to	None	This parameter allows you to filter the articles that have a publication date smaller than or equal to the specified value. The date must comply with ISO 8601 format. For example: 2025-07-18T21:32:58.500Z How recent an article can be depends on your subscription, see article availability.
sortby	publishedAt	This parameter allows you to choose with which type of sorting the articles should be returned. Two values are possible: publishedAt = sort by publication date, the articles with the most recent publication date are returned first relevance = sort by best match to keywords, the articles with the best match are returned first
page	1	This parameter allows you to control the pagination of the results returned by the API. The paging behavior is closely related to the value of the max parameter. The first page is page 1, then you have to increment by 1 to go to the next page. Let's say that the value of the max parameter is 10, then the first page will contain the first 10 articles returned by the API (articles 1 to 10), page 2 will return the next 10 articles (articles 11 to 20), etc. For performance reasons, it is not possible to paginate more than 1000 articles.
truncate	None	This parameter allows you to truncate the content attribute. To truncate the content attribute, the parameter must be set to content, as follows: truncate=content For users on the Free plan, the content attribute is automatically truncated. If you need to access the full content, you can upgrade your plan here: https://gnews.io/change-plan

Query Syntax

The q parameter supports exact phrase search and the logical operators AND, OR and NOT.

See Query Syntax for the full reference.

Code Examples

cURL

curl --get "https://gnews.io/api/v4/search" \
  --data-urlencode "q=example" \
  --data-urlencode "lang=en" \
  --data-urlencode "max=10" \
  --data-urlencode "apikey=YOUR_API_KEY"

Python

import requests

API_KEY = "YOUR_API_KEY"

response = requests.get(
    "https://gnews.io/api/v4/search",
    params={"q": "example", "lang": "en", "max": 10, "apikey": API_KEY},
    timeout=10,
)
response.raise_for_status()

for article in response.json()["articles"]:
    print(article["title"])

JavaScript

const API_KEY = "YOUR_API_KEY";

const params = new URLSearchParams({
    q: "example",
    lang: "en",
    max: "10",
    apikey: API_KEY,
});

const response = await fetch(`https://gnews.io/api/v4/search?${params}`);
if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
}

const { articles } = await response.json();
for (const article of articles) {
    console.log(article.title);
}

note

On the Free plan, browser requests only work from localhost. Paid plans accept requests from any website. Keep in mind that a key in front-end code is visible to anyone, so on a public site it is safer to call the API from your backend.

PHP

<?php

$apiKey = "YOUR_API_KEY";

$query = http_build_query([
    "q"      => "example",
    "lang"   => "en",
    "max"    => 10,
    "apikey" => $apiKey,
]);

$response = file_get_contents("https://gnews.io/api/v4/search?" . $query);
if ($response === false) {
    throw new RuntimeException("Request failed");
}

$data = json_decode($response, true);
foreach ($data["articles"] as $article) {
    echo $article["title"] . PHP_EOL;
}

C#

using System.Net.Http.Json;

const string ApiKey = "YOUR_API_KEY";

using var client = new HttpClient();

var url = $"https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey={ApiKey}";
var data = await client.GetFromJsonAsync<ApiResponse>(url)
           ?? throw new InvalidOperationException("Empty response");

foreach (var article in data.Articles)
{
    Console.WriteLine(article.Title);
}

record ApiResponse(List<Article> Articles);
record Article(string Title);

Alternatively, you can use our official libraries available at gnews.io/libraries.

Supported Languages

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

Supported Countries

Name	Code
Argentina	ar
Australia	au
Bangladesh	bd
Brazil	br
Canada	ca
China	cn
Colombia	co
Egypt	eg
France	fr
Germany	de
Greece	gr
Hong Kong	hk
India	in
Indonesia	id
Ireland	ie
Israel	il
Italy	it
Japan	jp
Malaysia	my
Mexico	mx
Netherlands	nl
Norway	no
Pakistan	pk
Peru	pe
Philippines	ph
Portugal	pt
Romania	ro
Russia	ru
Singapore	sg
Spain	es
Sweden	se
Switzerland	ch
Taiwan	tw
Turkey	tr
Ukraine	ua
United Kingdom	gb
United States	us