Welcome: Documentation for newsapi-python

This is documentation for version 0.2.7 of newsapi-python, a Python client for the News API.

The project source repository is hosted on GitHub.

Documentation Contents

Example NewsApiClient Usage

This page is a tutorial-by-example for using the NewsApiClient class.

Basic Usage

The top-level NewsApiClient class allows you to access News API endpoints. Initialize the client with your API key:

import os
from newsapi import NewsApiClient

# An API key; for example: "74f9e72a4bfd4dbaa0cbac8e9a17d34a"
key = os.environ["news_api_secret"]

api = NewsApiClient(api_key=key)

The only required parameter is an API key. You can also pass a persistent session object; see Using a Dedicated Session.

Accessing the /top-headlines Endpoint

Use newsapi.NewsApiClient.get_top_headlines() to pull from the /top-headlines endpoint:

api.get_top_headlines()
api.get_top_headlines(q="hurricane")
api.get_top_headlines(category="sports")
api.get_top_headlines(sources="abc-news,ars-technica", page_size=50)

Accessing the /everything Endpoint

Use newsapi.NewsApiClient.get_everything() to pull from the /everything endpoint:

api.get_everything("hurricane OR tornado", sort_by="relevancy", language="en")
api.get_everything("(hurricane OR tornado) AND FEMA", sort_by="relevancy")

Accessing the /sources Endpoint

Use newsapi.NewsApiClient.get_sources() to pull from the /sources endpoint:

api.get_sources()
api.get_sources(category="technology")
api.get_sources(country="ru")
api.get_sources(category="health", country="us")
api.get_sources(language="en", country="in")

Using a Dedicated Session

By default, each method call from NewsApiClient uses a new TCP session (and requests.Session instance). This is not ideal if you’d like to call endpoints multiple times, whereas using a single session can provide connection-pooling and cookie persistence.

To use a single session across multiple method calls, pass the session object to NewsApiClient:

import requests

with requests.Session() as session:
    # Use a single session for multiple requests.  Using a 'with'
    # context manager closes the session and TCP connection after use.
    api = NewsApiClient(api_key=key, session=session)
    data1 = api.get_top_headlines(category="technology")
    data2 = api.get_everything(q="facebook", domains="mashable.com,wired.com")

Date Inputs

The optional parameters from_param and to used in newsapi.NewsApiClient.get_everything() allow you to constrain the result set to articles published within a given span.

You can pass a handful of different types:

• datetime.date
• datetime.datetime (assumed to be in UTC time)
• str formated as either %Y-%m-%d (e.g. 2019-09-07) or %Y-%m-%dT%H:%M:%S (e.g. 2019-09-07T13:04:15)
• int or float (assumed represents a Unix timestamp)
• None (the default, in which there is no constraint)

Here are a few valid examples:

import datetime as dt

api.get_everything(
    q="hurricane",
    from_param=dt.date(2019, 9, 1),
    to=dt.date(2019, 9, 3),
)

api.get_everything(
    q="hurricane",
    from_param=dt.datetime(2019, 9, 1, hour=5),
    to=dt.datetime(2019, 9, 1, hour=15),
)

api.get_everything(
    q="hurricane",
    from_param="2019-08-01",
    to="2019-09-15",
)

api.get_everything(
    q="hurricane",
    from_param="2019-08-01",
    to="2019-09-15",
)

api.get_everything(
    q="venezuela",
    from_param="2019-08-01T10:30:00",
    to="2019-09-15T14:00:00",
)

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.