Python: Get articles and show in command line

📘

About this tutorial

What you'll learn
How to make a POST API call to our Historical API using Python.
How filters work in the v1/articles endpoint.

What you'll need

• Access to the Command Prompt (Windows) or Terminal (macOS).
• Python 3 installed on your machine.
• A text editor.

Step 1: Check for Python

Before we get started, we'll check that we have Python 3 installed on our machine.

Open the Command Prompt or Terminal and enter the following command:

python --version

If you have Python installed, the version will be printed on the screen. For example, Python 3.6.4.

If you do not have a 3.x.x version installed, or if you see an error, you should upgrade to/install version 3 if you wish to proceed with this tutorial. You can do this from the Python website.

Step 2: Import the libraries we need

Open your text editor and create a new file. This is where we'll write our Python script. This script is a set of instructions that your computer will know how to run using Python. You'll learn how to run it later in this tutorial.

There are a number of libraries available in Python that will make our lives easier. A library is pre-written code that lets us perform common tasks more quickly. In this tutorial, we'll be making API calls and handling JSON, so we'll use libraries for those things.

At the top of your file, add the following to import the requests and json libraries.

import requests, json

Step 3: Set our endpoint and API key details

We want to have an easy place to store things like our API key and the details of the endpoint we're using. We'll want to add the API key to the endpoint URL as a query parameter as well.

We'll do that by defining two variables:

• api_key for our key
• api_endpoint for the full URL of the endpoint, using the api_key as well

In your file, add the following on its own line:

api_key = 'YOUR_API_KEY'
api_endpoint = 'https://api.newswhip.com/v1/articles?key=%s' % api_key

Step 4: Define our query

Next up, we're going to tell our script what parameters we want to send when we make our request.

The article endpoint lets us filter the results on all kinds of things (you'll find the full reference in the /articles documentation). In this example, we're going to

• search for happiness
• order the results to find the articles with the most engagement
• restrict our result to just one entry

We'll write the query that we'll need to run, and assign that to a variable called data. We do that so that we can reuse the query whenever we like, just by referring to the data variable.

In your file, add the following on its own line:

data = json.dumps({'filters':["happiness"], 'sort_by':'fb_tw_and_li', 'size':1})

Step 5: Run the API query

Next, we'll run the query. We'll use the requests library that we imported at the start to do this, and then we'll assign the output of the request to a variable that we'll call r.

r = requests.post(url = api_endpoint, data = data)

Step 6: Extracting the response text

So far, we've written the code to define an API query and execute it. Now we need to show the output in the command prompt.

To do this, we'll do two things:

• We'll transform the value stored in r into text, and assign that to a new variable called response.
• We'll print that text to the command prompt you're using.

response = r.text
print(response)

Step 7: Run the script

Save your file, and call it articles.py. You can check out our version of the script at the bottom of this page.

Open the command prompt, making sure that it is pointing to the same directory (folder) as your script. You can change the directory using the cd command, followed by the path of the directory.

Type the following into the command prompt, and hit enter. This command tells Python to run the script called articles.py.

python articles.py

Step 8: Result!

The script will run, and the result will appear on the screen. It's in JSON format.

I've used JSON Pretty Print to make the result example easier to read below. When you do this in the command prompt, it will appear flat (as a single line).

When I wrote this tutorial the piece of content with the most engagement was a lovely post by someone wishing their friends and family a happy Easter. It had over 19k Facebook engagements.

{
  "articles": [
    {
      "delta_time": 1032,
      "recent_fb_counts": 9,
      "recent_tw_counts": 0,
      "relatedStories": [
        
      ],
      "fb_data": {
        "total_engagement_count": 19139,
        "total_count_delta": 9,
        "delta_period": 1032,
        "delta_period_unit": "m",
        "fb_overperforming": 15.110787789121
      },
      "tw_data": {
        "tw_count": 0,
        "total_count_delta": 0,
        "delta_period": 1032,
        "delta_period_unit": "m"
      },
      "li_data": {
        "li_count": 0,
        "total_count_delta": 0,
        "delta_period": 1032,
        "delta_period_unit": "m"
      },
      "pi_data": {
        "pi_count": 0,
        "delta_period": 1032,
        "delta_period_unit": "m"
      },
      "predicted_interactions": 19156,
      "predicted_timestamp": 1522984950051,
      "uuid": "ca056d50-3571-11e8-a52e-a128b18e226e",
      "publication_timestamp": 1522540565000,
      "link": "http://www.daveswordsofwisdom.com/2018/03/wishing-you-happy-easter.html",
      "headline": "Wishing you a Happy Easter.",
      "excerpt": "Happy Easter Wishing all of my family & friends a very Happy Easter. May it bring you smiles, happiness and memories you can treasure. ...",
      "keywords": "",
      "source": {
        "publisher": "daveswordsofwisdom.com",
        "link": "http://daveswordsofwisdom.com",
        "country": "",
        "country_code": ""
      },
      "image_link": "https://3.bp.blogspot.com/-aCiF_S6Go0A/VvVyyD6rFzI/AAAAAAAAW6I/FE5vk4XcRKIjQFAVVA_5EeAzF9kpgGdfA/w1200-h630-p-k-no-nu/happy%2Beaster%2Blink.jpg",
      "has_video": false,
      "nw_score": 0.22496734328218,
      "max_nw_score": 689.10374114225,
      "topics": [
        
      ],
      "authors": null,
      "entities": [
        
      ]
    }
  ]
}

The end

There you go! You've just made an API call and wrote the result to the screen.

Resources

Useful documentation

• /articles
• Data dictionary

Next steps

Why not try:

• Changing the search term?
• Changing the filters you use?
• Getting more results?

The full script

# importing the requests and json libraries
import requests, json
 
# defining the api key and endpoint
api_key = 'YOUR_API_KEY'
api_endpoint = 'https://api.newswhip.com/v1/articles?key=%s' % api_key

# put together the query parameters
data = json.dumps({'filters':["happiness"], 'sort_by':'fb_tw_and_li', 'size':1})

# make the request
r = requests.post(url = api_endpoint, data = data)
 
# extracting response text 
response = r.text
print(response)