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 asession
instance,NewsApiClient
will not close the session for you. Remember to callsession.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.
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"
.- category (str or None) – Find sources that display news of this category.
See
-
get_top_headlines
(q=None, qintitle=None, sources=None, language='en', 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 thecountry
orcategory
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 thesources
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 thesources
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"
.- q (str or None) –
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.
-
newsapi.const.
languages
= {'ar', 'cn', 'de', 'en', 'es', 'fr', 'he', 'it', 'nl', 'no', 'pt', 'ru', 'se', 'sv', 'ud', 'zh'}¶ The 2-letter ISO-639-1 code of the language you want to get articles for. If not specified, the results span all languages.
-
newsapi.const.
countries
= {'ae', 'ar', 'at', 'au', 'be', 'bg', 'br', 'ca', 'ch', 'cn', 'co', 'cu', 'cz', 'de', 'eg', 'es', 'fr', 'gb', 'gr', 'hk', 'hu', 'id', 'ie', 'il', 'in', 'is', 'it', 'jp', 'kr', 'lt', 'lv', 'ma', 'mx', 'my', 'ng', 'nl', 'no', 'nz', 'ph', 'pk', 'pl', 'pt', 'ro', 'rs', 'ru', 'sa', 'se', 'sg', 'si', 'sk', 'th', 'tr', 'tw', 'ua', 'us', 've', 'za', 'zh'}¶ The 2-letter ISO 3166-1 code of the country you want to get headlines for. If not specified, the results span all countries.
-
newsapi.const.
categories
= {'business', 'entertainment', 'general', 'health', 'science', 'sports', 'technology'}¶ The category you want to get articles for. If not specified, the results span all categories.
-
newsapi.const.
sort_method
= {'popularity', 'publishedAt', 'relevancy'}¶ The order to sort article results in. If not specified, the default is
"publishedAt"
.