API Reference

GNews

class GNews(
    language: str = "en",
    country: str = "US",
    max_results: int = 100,
    period: str | None = None,
    start_date: tuple | datetime | None = None,
    end_date: tuple | datetime | None = None,
    exclude_websites: list[str] | None = None,
    proxy: dict | None = None,
    searchapi_key: str | None = None,
)

Methods

get_news(key, page=1)

Search news by keyword.

articles = g.get_news("OpenAI")
articles = g.get_news("Python", page=2)  # pagination (SearchApi only)

Returns: list[dict]

get_top_news()

Get current top headlines.

articles = g.get_top_news()

Returns: list[dict]

get_news_by_topic(topic)

Get news for a major topic.

articles = g.get_news_by_topic("TECHNOLOGY")

Returns: list[dict]

get_news_by_location(location)

Get news for a city, state, or country.

articles = g.get_news_by_location("Pakistan")

Returns: list[dict]

get_news_by_site(site)

Get news from a specific domain.

articles = g.get_news_by_site("bbc.com")

Returns: list[dict]

get_full_article(url)

Extract full article text. Requires pip install gnews[fulltext].

article = g.get_full_article("https://example.com/article")
# {"text": "...", "url": "..."}

Returns: dict with keys text, url

Raises: ImportError if trafilatura not installed, NetworkError on failure

get_news_async(key, page=1)

Async version of get_news().

articles = await g.get_news_async("OpenAI")
articles = await g.get_news_async("Python", page=2)

get_top_news_async()

Async version of get_top_news().

get_news_by_topic_async(topic)

Async version of get_news_by_topic().

get_news_by_location_async(location)

Async version of get_news_by_location().

get_news_by_site_async(site)

Async version of get_news_by_site().

save_to_json(articles, path)

Save articles to a JSON file.

g.save_to_json(articles, "news.json")

Returns: str — the output path

save_to_csv(articles, path)

Save articles to a CSV file.

g.save_to_csv(articles, "news.csv")

Returns: str — the output path

Article Properties

RSS backend fields

Field	Type	Description
`title`	str	Article title
`description`	str	Short summary
`published date`	str	RFC 2822 date
`url`	str	Article URL
`publisher`	str/dict	Publisher info

SearchApi extra fields

Field	Type	Description
`iso_date`	str	ISO 8601 date
`thumbnail`	str	Article image (base64)
`favicon`	str	Publisher logo (base64)
`rank`	int	Position in results