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_match`	Total Search Matches	The total number of matches identified for your 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.

NewsWhip Developer Hub

Welcome to the NewsWhip Developer Hub!

Data dictionary

Fields in API response

Sorting options

v1/stats aggregation options

Data dictionary

Suggested Edits are limited on API Reference Pages