Skip to content

Latest commit

 

History

History
117 lines (83 loc) · 3.74 KB

examples.rst

File metadata and controls

117 lines (83 loc) · 3.74 KB

Example :class:`NewsApiClient` Usage

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

Basic Usage

The top-level :class:`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 :meth:`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 :meth:`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 :meth:`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 :class:`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 :class:`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 :meth:`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",
)