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.
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.
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
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
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.
authors
Authors
The person who produced a piece of content.
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
publishertoyahoo.comby stripping out the subdomains. - We set the
domaintouk.finance.yahoo.combecause that’s what we decided to track in the first place. - We set the
domainstoyahoo.com,finance.yahoo.com, anduk.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.