Welcome to the NewsWhip Developer Hub!

NewsWhip APIs give you raw access to the world’s largest and fastest human engagement database; real time data trends, aggregated data, statistics, and social engagement metrics for hundreds of millions of stories, tracked since January 1, 2014.

Use the power of NewsWhip data to create and customize your own solutions, perfectly suited to your company’s goals. In the hub you'll find the information you need to be successful with our API.

Data dictionary

This page lists the different pieces of data that may be used in queries or returned in the API response, along with a description of what they are.

Fields in API response

We provide the results of several calculations that summarise the social performance of a piece of content, or predict it.

Field
Name
Description

author

Author

The author of the content, when available. This field is available when searching for YouTube content.

authors

Authors

A list of the author(s) of the content, when available.

avg

Average

In the stats endpoint, the average engagement for the posts that match your search query.

comments

Facebook Comments

The number of comments made on posts relating to a piece of content.

channel

Channel

The URL of the YouTube channel.

count

Count

In the stats endpoint, the total number of posts that match your search query.

country

Country

The human-readable country name for the publisher.

country_code

Country Code

The ISO 3166 country code that represents the country of the publisher.

created_at

Created At

The date and time that an Instagram post was published. A UNIX timestamp in milliseconds.

delta_period

Delta Period

The frequency at which we are checking for social engagements for a piece of content. This takes place for a maximum of 7 days.

If 7 days has been reached, you can assume that we are no longer refreshing the data.

delta_period_unit

Delta Period Unit

The value is always m, representing minutes. This is the unit for the delta_period.

delta_time

Delta Time

The same as delta_period.

entities

Entities

The proper nouns extracted from a piece of content.

excerpt

Excerpt

A short extract of the content, when available.

external_link

External Link

If a Facebook post contains a link to an external piece of content (eg. a news article), this is that URL.

favourite_count

Twitter Likes Count

The number of likes that the specified post has received. These used to be called ‘favourites’ in the Twitter world, and this field has retained that name to prevent making a breaking change to our API.

fb_data

Facebook Data

This is a collection of different data points that relate to Facebook.

fb_overperforming

Facebook Overperforming

A calculation of how a piece of content's performance on Facebook compares to its usual average performance.

fb_predicted_interactions

Facebook Predicted Interactions

The total number of Facebook engagements that we predict a piece of content will achieve.

fb_sponsor_tags

Facebook Sponsor Tags

Sponsors of the Facebook post, if available.

fb_story

Facebook Story

A description generated by Facebook about an event. For example, Tom shared 3 photos or Jane shared a link.

fb_total

Facebook Stats

For the /stats endpoint, a grouping of statistics for your chosen aggregation that relate to Facebook engagement.

fb_total_interactions

Facebook Total Interactions

The total number of engagements (reactions, shares, comments) a piece of content has had on Facebook. The naming of this field differs between the fbPosts endpoint (total_engagement_count) and the fbInfluencers endpoint (fb_total_interactions).

followers_count

Facebook or Twitter Followers Count

The number of people following a given Facebook page or Twitter account.

following_count

Twitter Following Count

The number of other Twitter accounts followed by a given Twitter account.

has_video

Video Flag

A flag to show whether we detected video in the content.

headline

Headline

The heading of the content.

id

Instagram Unique Identifier

As with uuid, this is an alphanumeric string that uniquely identifies a piece of Instagram content in the NewsWhip database.

ig_comments

Instagram Comments

The number of comments that have been made on an Instagram post.

ig_filter

Instagram Filter

On Instagram, if a filter was applied to the image, the name of that filter appears here.

ig_full_user_name

Instagram Full Username

The human-readable (eg. with spaces) name of an Instagram user.

ig_likes

Instagram Likes

The number of likes that have been made on an Instagram post.

ig_link

Instagram Link

The URL of an Instagram post.

ig_post_text

Instagram Post Text

The written text associated with the original Instagram post.

ig_post_type

Instagram Post Type

The type of Instagram post the content is. For example, image or carousel.

ig_profile_image

Instagram Profile Image

The URL of the Instagram user's avatar.

ig_tags

Instagram Tags

The hashtags used in an Instagram post.

ig_user_name

Instagram Username

The handle of an Instagram user.

image_link

Image Link

If we have detected an important image for the content, this is the link to it.

instagram_id

Instagram ID

A unique identifier for the Instagram post, provided by Instagram.

is_live_video

Live Video Flag

A flag to show whether the content is a Facebook Live Video.

keywords

Keywords

A list of keywords sometimes provided by the publisher. These are provided verbatim, and so may not be consistent from publisher to publisher.

li_count

LinkedIn Count

The number of engagements a piece of content has had on LinkedIn.

See Known issues for updates on the availability of LinkedIn data.

li_data

LinkedIn Data

This is a collection of different data points that relate to LinkedIn.

likes_count

Facebook or Twitter Likes Count

For Facebook, the number of posts for which this user has left a like, love, wow, haha, sad, or angry reaction. For Twitter, the number of posts that this user has liked.

key

Stats Key

In the stats endpoint, each entry for the aggregation option that you have chosen.

likes

Facebook Likes

The number of likes of posts relating to a piece of content.

link

Link

The URL of the content.

linkedin

LinkedIn Stats

For the /stats endpoint, a grouping of statistics for your chosen aggregation that relate to LinkedIn engagement.

max

Maximum Engagement

In the stats endpoint, the maximum number of engagements that any post that matches your search query had.

max_fb_interactions

Maximum Facebook Interactions

For Facebook, the number of interactions on the user’s most influenced story.

max_nw_score

Maximum Velocity

The maximum social velocity of a piece of content so far.

This is a score that we give to stories based on how fast they are spreading on Facebook, Twitter, and LinkedIn. The scores tell you which articles and videos are captivating the most attention today, in whatever niche or sector you’re interested in. The higher the score, the more engagement we are seeing the content getting.

max_retweet_value

Maximum Retweets

For Twitter, the number of retweets on this user’s most influenced article.

min

Minimum Engagement

In the stats endpoint, the minimum (lowest) number of engagements that any post that matches your search query had.

nw_max_score

Maximum Velocity

The maximum social velocity of a piece of content so far.

This is a score that we give to stories based on how fast they are spreading on Facebook, Twitter, and LinkedIn. The scores tell you which articles and videos are captivating the most attention today, in whatever niche or sector you’re interested in. The higher the score, the more engagement we are seeing the content getting.

nw_score

Current Velocity

The current social velocity of a piece of content.

page_id

Facebook Page ID

The unique identifier for a Facebook page.

page_name

Facebook Page Name

The name of a Facebook page.

pi_count

Pinterest Count

The number of pins a piece of content has had on Pinterest.

pi_data

Pinterest Data

This is a collection of different data points that relate to Pinterest.

pinterest

Pinterest Stats

For the /stats endpoint, a grouping of statistics for your chosen aggregation that relate to Pinterest engagement.

post_type

Facebook Post Type

The type of Facebook post the content is. For example, a status.

predicted_interactions

Predicted Interactions

The total number of Facebook engagements and Twitter Influencer Shares (combined) that we predict a piece of content will achieve.

predicted_timestamp

Predicted Interactions Timestamp

The date and time that we calculate the Predicted Interactions number will be reached.

publication_timestamp

Publication Timestamp

The date and time that the content was published. It is a UNIX timestamp in milliseconds.

publisher

Publisher

The name, usually the domain, of the publisher of the content.

reactions

Facebook Reactions

A breakdown of the types of reactions that have been made on a post, and the number of each. Reactions could be: comments, likes, shares, loves, wows, hahas, sads, or angrys.

recent_fb_counts

Facebook Total Count Delta

This is the same as total_count_delta for Facebook. This is a legacy field that may be removed in a future update.

recent_tw_counts

Twitter Total Count Delta

This is the same as total_count_delta for Twitter. This is a legacy field that may be removed in a future update.

relatedStories

Related Stories

A list of stories similar to the parent story.

This works by looking for headlines with 4 or more words in common, excluding stop words (eg. and, or, but etc), within the query result. So, if you run a query that returns 3000 results, and within that you have several headlines that are similar, these will appear in the related stories section of the response.

rt_count

Twitter Retweets Count

The number of posts this user has retweeted.

shares

Facebook Shares

The number of times posts relating to a piece of content were shared on Facebook.

source

Source

This is a collection of different data points that relate to the publisher.

stats

Stats

In the stats endpoint, a group of social engagement metrics for a given aggregation.

statuses_count

Twitter Posts Count

The number of Tweets the user has made.

std_deviation

Standard Deviation

In the stats endpoint, the amount of variation of engagement of the posts that match your search query.

sum

Sum

In the stats endpoint, the sum total of all engagements for the posts that match your search query.

sum_of_squares

Sum of Squares

The sum, over all observations, of the squared differences of each observation from the overall mean. In the stats endpoint, this refers to the engagement of the posts that match your search query.

thumbnail

Thumbnail

The URL of the video thumbnail for YouTube content.

topics

Topics (sometimes referred to as Categories)

The theme associated with the content's source, based on Topics.

total

Stats Engagement Total

In the stats endpoint, the total engagement across all available social networks the posts that match your search query.

total_count_delta

Total Count Delta

The difference between the current number of engagement and the number at the time of our previous check.

total_engagement_count

Facebook Total Engagement Count

The total number of engagements (reactions, shares, comments) a piece of content has had on Facebook.

tw_count

Twitter Count

The number of Influencer Shares a piece of content has had on Twitter.

tw_data

Twitter Data

This is a collection of different data points that relate to Twitter.

tw_overperforming

Twitter Overperforming

A calculation of how a piece of content's performance on Twitter compares to its usual average performance.

tw_predicted_interactions

Twitter Predicted Interactions

The total number of Twitter Influencer Shares that we predict a piece of content will achieve.

twitter

Twitter Stats

For the /stats endpoint, a grouping of statistics for your chosen aggregation that relate to Twitter engagement.

uuid

Unique Identifier

An alphanumeric string that uniquely identifies a piece of content in the NewsWhip database.

variance

Variance

The expectation of the squared deviation of a random variable from its mean. In the stats endpoint, this refers to the engagement of the posts that match your search query.

videos

Embedded Videos

A list of URLs to videos embedded in a piece of content. For example, a YouTube video embedded in a blog post.

youtube_post

YouTube Post

The written content that is associated with a YouTube video.

ytComments

YouTube Comments

The number of comments that have been made on a YouTube video.

ytDislikes

YouTube Dislikes

The number of times that people have disliked (thumb down) a YouTube video.

ytLikes

YouTube Likes

The number of times that people have liked (thumb up) a YouTube video.

ytTotal

YouTube Engagement Total

The sum of views, likes, dislikes, and comments for a YouTube video.

ytViews

YouTube Views

The number of views a YouTube video has.

Sorting options

This table lists common options that may be available for sorting data for different endpoints. It also provides a brief definition of what those sort options mean.

Note that not all endpoints support all sorting options. Check the documentation for the endpoint you are using to be sure.

Field
Name
Description

created_at

Created At

The published date of the matched article

fb_total_engagement

Facebook Total Engagement

fb_tw_overperforming

Facebook and Twitter Overperforming

The sum of Facebook and Twitter Overperforming scores

fb_tw_and_li

Facebook, Twitter, and LinkedIn

The sum of Facebook, Twitter, and LinkedIn engagements

fb_tw_li_and_pi

Facebook, Twitter, LinkedIn, and Pinterest

The sum of Facebook, Twitter, LinkedIn, and Pinterest engagements

linkedin

LinkedIn

The equivalent of li_count

nw_max_score

NewsWhip Maximum Score

The highest velocity the content has achieved so far.

nw_score

NewsWhip Score

The current velocity of the content.

predicted_interactions

Predicted Interactions

The sum of the number of interactions we predict that the content will have on Facebook and Twitter combined.

twitter

Twitter

The equivalent of tw_count

v1/stats aggregation options

In the v1/stats API it is required that you aggregate the results on a field of your choosing. The definitions of the available fields are listed below.

Field
Name
Description

authors

Authors

The person who produced a piece of content.

categories

Categories

The topic of the content, as defined in Topics.

country_code

Country Code

The country associated with the publication. A two letter country code, as defined in the ISO 3166 standard.

domain

Domain

See below.

domains

Domains

See below.

language

Language

The language associated with the publication. A two letter code, as described in Supported Languages.

publisher

Publisher

See below.

For domain, domains, and publisher an understanding of our data gathering methodology is needed to make a decision on which may be appropriate. Here's a walkthrough of how we populate these fields:

  • Let’s suppose we decide to start tracking content for uk.finance.yahoo.com. We add that to our database.
  • We set the publisher to yahoo.com by stripping out the subdomains.
  • We set the domain to uk.finance.yahoo.com because that’s what we decided to track in the first place.
  • We set the domains to yahoo.com, finance.yahoo.com, and uk.finance.yahoo.com, as these are all the possible combinations of the domain and subdomain.

So, when you choose to aggregate on one of these three, you’re choosing from one of those methodologies.