Search Endpoint

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

HTTP Request

GET https://gnews.io/api/v4/search?q=example&apikey=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.
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
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
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.
expand	None	This parameter will only work if you have a paid subscription activated on your account. This parameter allows you to return in addition to other data, the full content of the articles. To get the full content of the articles, the parameter must be set to content, as follows expand=content

Query Syntax

Things to know before you start:

In this section, the word query refers to the value of the q parameter and not to the HTTP request.
The query must be URL-encoded.
It is not possible to use special characters without putting quotes around them.

Example:

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

Phrase Search Operator

This operator allows you to make an exact search. Keywords surrounded by quotation marks are used to search for articles with the exact same keyword sequence. For example the query: "Apple iPhone" will return articles matching at least once this sequence of keywords.

Logical AND Operator

This operator allows you to make sure that several keywords are all used in the article search. By default the space character acts as an AND operator, it is possible to replace the space character by AND to obtain the same result. For example the query: Apple Microsoft is equivalent to Apple AND Microsoft

Logical OR Operator

This operator allows you to retrieve articles matching the keyword a or the keyword b. It is important to note that this operator has a higher precedence than the AND operator. For example the query: Apple OR Microsoft will return all articles matching the keyword Apple as well as all articles matching the keyword Microsoft

Due to the higher precedence of the operator OR the following query will not work as expected: Apple AND iPhone OR Microsoft. Normally, articles matching the keywords Apple and iPhone are returned first and then articles matching the keyword Microsoft are returned. Because of the precedence of the OR operator, in practice the query will return articles matching Apple AND iPhone or Apple AND Microsoft. To have a normal behavior, it is necessary to add brackets. The query Apple AND iPhone OR Microsoft will behave normally when it is in this form: (Apple AND iPhone) OR Microsoft

Logical NOT Operator

This operator allows you to remove from the results the articles corresponding to the specified keywords. To use it, you need to add NOT in front of each word or phrase surrounded by quotes. For example the query: Apple NOT iPhone will return all articles matching the keyword Apple but not the keyword iPhone

Examples of Valid Queries

Query
Microsoft Windows 10
Apple OR Microsoft
Apple AND NOT iPhone
(Windows 7) AND (Windows 10)
"Apple iPhone 13" AND NOT "Apple iPhone 14"
Intel AND (i7 OR i9)
(Intel AND (i7 OR "i9-14900K")) AND NOT AMD AND NOT "i7-14700K"

Code Examples

JavaScript
Python
C#
PHP
Bash

// TODO: replace API_KEY with your API key.
apikey = 'API_KEY';
url = 'https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey=' + apikey;

fetch(url)
  .then(function (response) {
    return response.json();
  })
  .then(function (data) {
    articles = data.articles;

    for (i = 0; i < articles.length; i++) {
      // articles[i].title
      console.log("Title: " + articles[i]['title']);
      // articles[i].description
      console.log("Description: " + articles[i]['description']);
      // You can replace {property} below with any of the article properties returned by the API.
      // articles[i].{property}
      // console.log(articles[i]['{property}']);

      // Delete this line to display all the articles returned by the request. Currently only the first article is displayed.
      break;
    }
  });

# https://docs.python.org/3/library/json.html
# This library will be used to parse the JSON data returned by the API.
import json
# https://docs.python.org/3/library/urllib.request.html#module-urllib.request
# This library will be used to fetch the API.
import urllib.request

# TODO: replace API_KEY with your API key.
apikey = "API_KEY"
url = f"https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey={apikey}"

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode("utf-8"))
    articles = data["articles"]

    for i in range(len(articles)):
        # articles[i].title
        print(f"Title: {articles[i]['title']}")
        # articles[i].description
        print(f"Description: {articles[i]['description']}")
        # You can replace {property} below with any of the article properties returned by the API.
        # articles[i].{property}
        # print(f"{articles[i]['{property}']}")

        # Delete this line to display all the articles returned by the request. Currently only the first article is displayed.
        break

// https://www.newtonsoft.com/json
// dotnet add package Newtonsoft.Json
// This library will be used to parse the JSON data returned by the API.
using Newtonsoft.Json;

// TODO: replace API_KEY with your API key.
const string API_KEY = "API_KEY";
const string URL = $"https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey={API_KEY}";

HttpClient client = new HttpClient();
HttpResponseMessage response = await client.GetAsync(URL);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();
var data = JsonConvert.DeserializeObject<ApiResponse>(responseBody);
List<Article> articles = data.Articles;

for (int i = 0; i < articles.Count; i++)
{
  // articles[i].title
  Console.WriteLine($"Title: {articles[i].Title}");
  // articles[i].description
  Console.WriteLine($"Description: {articles[i].Description}");
  // You can replace {property} below with any of the article properties returned by the API.
  // articles[i].{property}
  // Console.WriteLine($"{articles[i].{property}}");
  // Note that {property} must be compliant with the definition of class Article.

  // Delete this line to display all the articles returned by the request. Currently only the first article is displayed.
  break;
}

class ApiResponse
{
  public int TotalArticles { get; set; }
  public List<Article> Articles { get; set; } = new List<Article>();
}

class Article
{
  public string Id { get; set; } = "";
  public string Title { get; set; } = "";
  public string Description { get; set; } = "";
  public string Content { get; set; } = "";
  public string Url { get; set; } = "";
  public string Image { get; set; } = "";
  public Source Source { get; set; } = new Source();
}

class Source
{
  public string Id { get; set; } = "";
  public string Name { get; set; } = "";
  public string Url { get; set; } = "";
}

<?php
// TODO: replace API_KEY with your API key.
$apikey = 'API_KEY';
$url = "https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey=$apikey";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
$articles = $data['articles'];

for ($i = 0; $i < count($articles); $i++) {
    // articles[i].title
    echo "Title: " . $articles[$i]['title'] . "\n";
    // articles[i].description
    echo "Description: " . $articles[$i]['description'] . "\n";
    // You can replace {property} below with any of the article properties returned by the API.
    // articles[i].{property}
    // echo $articles[$i]['{property}'] . "\n";

    // Delete this line to display all the articles returned by the request. Currently only the first article is displayed.
    break;
}

# Please note that you must have the package jq: https://stedolan.github.io/jq/
#!/bin/bash
# TODO: replace API_KEY with your API key.
apikey='API_KEY'
url="https://gnews.io/api/v4/search?q=example&lang=en&max=10&apikey=$apikey"

data=$(curl -s $url)
articles=$(echo $data | jq '.articles')
articles_length=$(echo $articles | jq length)
echo $articles_length

for ((i = 0; i < $articles_length; i++)); do
  echo $i
  # articles[i].title
  title=$(echo $articles | jq ".[$i].title")
  echo "Title: $title"
  # articles[i].description
  description=$(echo $articles | jq ".[$i].description")
  echo "Description: $description"
  # You can replace {property} below with any of the article properties returned by the API.
  # articles[i].{property}
  # {property}=$(echo $articles | jq ".[$i].{property}")
  # echo "${property}"

  # Delete this line to display all the articles returned by the request. Currently only the first article is displayed.
  break
done

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

Supported Languages

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

Supported Countries

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

HTTP Request​

Query Parameters​

Query Syntax​

Phrase Search Operator​

Logical AND Operator​

Logical OR Operator​

Logical NOT Operator​

Examples of Valid Queries​

Code Examples​

Supported Languages​

Supported Countries​