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
orfloat
(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",
)