How we use the API to put together monthly publisher rankings

Customers and friends of NewsWhip look forward to our monthly rankings, showing which publishers are getting the most engagement. It often results in lively debate and a little friendly rivalry between journalists at different publications. This month, we started to use our Stats API to generate the report.

In this post I’d like to show you how you could do the same thing. Use these simple steps to build your own rankings using the API. With a few small tweaks you could be gaining insight into the performance of your competitors in no time!

August 2018 Rankings

You’ll find our August 2018 rankings here. Based on the data, we uncovered some interesting insights:

• LAD bible and UNILAD continued their rise in the rankings, to first and fourth, respectively
• Overall, the top 25 publishers saw more engagements than last month, including hyperpartisan sites
• Viral content farms also appeared a few times in the rankings

How we do it

Getting the ranked list is super straightforward with the Stats API. To get started, let’s first understand what we need to generate the report.

• We’re reporting on English language publications.
• We care only about content that was published in August.
• We want to group results by domain.
• We want to order results by total Facebook engagements.
• We’re looking for the top 25 domains.

With that in mind, we can build out our API query. It looks like this:

{
    "filters": [],
    "from": 1533081600000,
    "to": 1535759999000,
    "size": 25,
    "language":"en",
    "sort_by":"fb_total.sum",
    "aggregate_by":"domain"
}

Here’s what everything means:

• Filters: this is a required field, and you’d usually use it to refine your results. We don’t need to do that here, so it’s empty.
• From/To: These define the period of time from which we’re drawing our data. These are UNIX timestamps in milliseconds, and represent the start and end of August 2018.
• Size: We only need the top 25 results, so we set that here.
• Language: A two letter code for English, to limit down the publications we’re including.
• Sort By: We’ve chosen to sort by the total number of Facebook engagements.
• Aggregate By: We’re grouping our results by domain. You could also choose do this using a number of different options, such as language code.

For CNN and Fox News, we also include edition.cnn.com, money.cnn.com, and insider.foxnews.com as part of their totals. This doesn't impact the ranking (their position didn't change because of this), but does give a more realistic view of how those two publishers perform.

Adapting this for competitor analysis

If you’d like to do this for a specific set of competitors, it’s as easy as adding a domain filter to the query. That way you’ll get results only for those publications that interest you. For example:

{
    "filters": ["domain:(bbc.com OR rte.ie OR cnn.com"],
    "from": 1533081600000,
    "to": 1535759999000,
    "language":"en",
    "sort_by":"fb_total.sum",
    "aggregate_by":"domain"
}

You could also use our Articles API to get the top posts for each of those domains, and start really building your understanding of your competitors’ content strategy.

I hope that little insight into the way we do things is interesting and helpful! If you’d like to learn more, head to our Developer Hub to learn about our APIs, or maybe check out our Python tutorial. If you have questions or feedback on this post, drop us a line on Twitter. We’re @NewsWhip.