API Reference

This page is a technical reference to the public classes, exceptions, and data defined in newsapi-python.

While newsapi-python makes every effort to keep up with the API, please consider the official News API docs as the canonical News API reference.

Classes

class newsapi.NewsApiClient(api_key, session=None)

The core client object used to fetch data from News API endpoints.

Parameters:
  • api_key (str) – Your API key, a length-32 UUID string provided for your News API account. You must register for a News API key.
  • session (requests.Session or None) – An optional requests.Session instance from which to execute requests. Note: If you provide a session instance, NewsApiClient will not close the session for you. Remember to call session.close(), or use the session as a context manager, to close the socket and free up resources.
get_everything(q=None, qintitle=None, sources=None, domains=None, exclude_domains=None, from_param=None, to=None, language=None, sort_by=None, page=None, page_size=None)

Call the /everything endpoint.

Search through millions of articles from over 30,000 large and small news sources and blogs.

Parameters:
  • q (str or None) – Keywords or a phrase to search for in the article title and body. See the official News API documentation for search syntax and examples.
  • qintitle –

    Keywords or a phrase to search for in the article title and body. See the official News API documentation for search syntax and examples.

  • sources (str or None) – A comma-seperated string of identifiers for the news sources or blogs you want headlines from. Use NewsApiClient.get_sources() to locate these programmatically, or look at the sources index.
  • domains (str or None) – A comma-seperated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to restrict the search to.
  • exclude_domains (str or None) – A comma-seperated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to remove from the results.
  • from_param (str or datetime.datetime or datetime.date or int or float or None) – A date and optional time for the oldest article allowed. If a str, the format must conform to ISO-8601 specifically as one of either %Y-%m-%d (e.g. 2019-09-07) or %Y-%m-%dT%H:%M:%S (e.g. 2019-09-07T13:04:15). An int or float is assumed to represent a Unix timestamp. All datetime inputs are assumed to be UTC.
  • to (str or datetime.datetime or datetime.date or int or float or None) – A date and optional time for the newest article allowed. If a str, the format must conform to ISO-8601 specifically as one of either %Y-%m-%d (e.g. 2019-09-07) or %Y-%m-%dT%H:%M:%S (e.g. 2019-09-07T13:04:15). An int or float is assumed to represent a Unix timestamp. All datetime inputs are assumed to be UTC.
  • language (str or None) – The 2-letter ISO-639-1 code of the language you want to get headlines for. See newsapi.const.languages for the set of allowed values.
  • sort_by (str or None) – The order to sort articles in. See newsapi.const.sort_method for the set of allowed values.
  • page (int or None) – The number of results to return per page (request). 20 is the default, 100 is the maximum.
  • page_size (int or None) – Use this to page through the results if the total results found is greater than the page size.
Returns:

JSON response as nested Python dictionary.
Return type:

dict
Raises:

NewsAPIException – If the "status" value of the response is "error" rather than "ok".
get_sources(category=None, language=None, country=None)

Call the /sources endpoint.

Fetch the subset of news publishers that /top-headlines are available from.

Parameters:
  • category (str or None) – Find sources that display news of this category. See newsapi.const.categories for the set of allowed values.
  • language (str or None) – Find sources that display news in a specific language. See newsapi.const.languages for the set of allowed values.
  • country (str or None) – Find sources that display news in a specific country. See newsapi.const.countries for the set of allowed values.
Returns:

JSON response as nested Python dictionary.
Return type:

dict
Raises:

NewsAPIException – If the "status" value of the response is "error" rather than "ok".
get_top_headlines(q=None, qintitle=None, sources=None, language=None, country=None, category=None, page_size=None, page=None)

Call the /top-headlines endpoint.

Fetch live top and breaking headlines.

This endpoint provides live top and breaking headlines for a country, specific category in a country, single source, or multiple sources. You can also search with keywords. Articles are sorted by the earliest date published first.

Parameters:
  • q (str or None) –

    Keywords or a phrase to search for in the article title and body. See the official News API documentation for search syntax and examples.

  • qintitle –

    Keywords or a phrase to search for in the article title and body. See the official News API documentation for search syntax and examples.

  • sources (str or None) –

    A comma-seperated string of identifiers for the news sources or blogs you want headlines from. Use NewsApiClient.get_sources() to locate these programmatically, or look at the sources index. Note: you can’t mix this param with the country or category params.

  • language (str or None) – The 2-letter ISO-639-1 code of the language you want to get headlines for. See newsapi.const.languages for the set of allowed values. The default for this method is "en" (English). Note: this parameter is not mentioned in the /top-headlines documentation as of Sep. 2019, but is supported by the API.
  • country (str or None) – The 2-letter ISO 3166-1 code of the country you want to get headlines for. See newsapi.const.countries for the set of allowed values. Note: you can’t mix this parameter with the sources param.
  • category (str or None) – The category you want to get headlines for. See newsapi.const.categories for the set of allowed values. Note: you can’t mix this parameter with the sources param.
  • page_size (int or None) – Use this to page through the results if the total results found is greater than the page size.
  • page (int or None) – The number of results to return per page (request). 20 is the default, 100 is the maximum.
Returns:

JSON response as nested Python dictionary.
Return type:

dict
Raises:

NewsAPIException – If the "status" value of the response is "error" rather than "ok".

Exceptions

exception newsapi.newsapi_exception.NewsAPIException(exception)

Represents an error response status value from News API.

Constants

The newsapi.const module holds constants and allowed parameter values specified in the official News API documentation.