LangChain

langchain-gnews gives LangChain and LangGraph agents two tools built on the GNews API. Web search tools return the most relevant pages; these tools return dated news articles with their source, filterable by country and language, including over past periods.

Tool	Name seen by the model	Use it for
GNewsTopHeadlines	gnews_top_headlines	Today's top headlines, ranked like Google News, by category, country and language: news briefings, digests
GNewsSearch	gnews_search	Articles about a topic, company or person, filtered by language, country and date, over an archive since 2020

Each tool call makes one API request with your key: it counts toward your daily quota and follows your plan (articles per request, historical archive and data freshness, see Article Availability).

Install

pip install langchain-gnews

Python 3.10+. The package depends on langchain-core 1.x and on the official Python SDK.

Get a free API key at gnews.io/register, then put it in the GNEWS_API_KEY environment variable, or pass it to the tools with api_key="YOUR_API_KEY".

export GNEWS_API_KEY="YOUR_API_KEY"

Use With an Agent

Requires langchain and a model integration, for example pip install langchain langchain-anthropic.

from langchain.agents import create_agent
from langchain_gnews import GNewsSearch, GNewsTopHeadlines

agent = create_agent("anthropic:claude-sonnet-5-5", tools=[GNewsTopHeadlines(), GNewsSearch()])
agent.invoke({"messages": [{"role": "user", "content": "Summarize this morning's top business headlines in France"}]})

The model picks the tool from its description: headlines for a briefing, search for a topic or a period.

Use Directly

from langchain_gnews import GNewsSearch, GNewsTopHeadlines

GNewsTopHeadlines().invoke({"category": "business", "country": "fr", "lang": "fr"})
GNewsSearch().invoke({"q": '"NVIDIA" AND earnings', "lang": "en", "from_date": "2025-01-01", "to_date": "2025-03-31"})

Both return {"total_articles": int, "articles": [...]}, each article with title, description, content, url, source and published_at.

Available Tools

gnews_search

Searches articles by keywords, like the Search endpoint.

Parameter	Default	Description
q	required	Keywords, with the query syntax (quotes, AND, OR, NOT, parentheses)
lang	any	2-letter language code, e.g. en
country	any	2-letter country code of the source, e.g. us
from_date	none	Oldest publication date, ISO 8601, e.g. 2025-03-01. The archive starts in 2020
to_date	none	Newest publication date, ISO 8601
sortby	publishedAt	publishedAt (most recent first) or relevance

gnews_top_headlines

Gets the current trending articles of a category, like the Top Headlines endpoint.

Parameter	Default	Description
category	general	general, world, nation, business, technology, entertainment, sports, science or health
lang	any	2-letter language code, e.g. en
country	any	2-letter country code, e.g. us
q	none	Optional keywords to narrow the headlines

Options

Both tools accept these keyword arguments when created, e.g. GNewsSearch(max_results=5, include_content=False).

Option	Default	Effect
api_key	GNEWS_API_KEY	GNews API key
max_results	10	Articles per call, up to the limit of your plan
include_content	True	Include the article text. Set to False to save tokens

API errors (invalid key, quota reached, rate limit) are returned to the model as tool errors instead of raising, so the agent can tell the user or try again.

What Your Plan Returns

Plan	Archive	Freshness	Article text
Free	last 30 days	12-hour delay	truncated
Paid	since 2020	real time	full

See Article Availability, JSON Response and the pricing page.

Source Code

The package is open source: github.com/gnews-io/langchain-gnews, published on PyPI.