Get report stats¶

Endpoint: {{statsRoute}}/:reportCode/stats.json

What it does: This endpoint is used to get the stats of a report. The report must be generated in oder to get the stats.

NOTE: The :reportCode is not the :reportId

Example: given this :reportId df688940-2bfd-4d15-bf55-fb3eebcd6c6d its :reportCode will be df688940 (the first chain of the :reportId)

Stats - Structure¶

The structure of a Tweet Binder stats JSON is the following:

Stats
- General stats
- Sentiment stats
- Contributor rankings
- Media rankings
- Influence rankings
Meta information

This is the main part of the JSON, its five sections show all the stats related to the analyzed hashtag.

General stats¶

In this section the client will receive the main stats of the hashtag or keyword he needs to analyze. It is shown this way in the JSON file:

We will explain one by one these stats:

since. Start of the report, this is the date of the first (oldest) tweet in the report. The client will be able to set a starting date, that will be the date Tweet Binder will start looking tweets from, the first tweet date may coincide or not. This value is expressed in milliseconds.
until. End of the report, this is the date of the last (newest) tweet in the report. The client will be able to set an ending date which will indicate the API when to stop collecting tweets. This value is expressed in milliseconds.
total. Total number of tweets analyzed in the report. This will include original tweets and retweets. All those tweets are processed in the API to create the rest of the stats.
images. Total number of tweets with images, vídeos or GIF in the report. This metric shows how many tweets include media, they can also contain a link or not.
links. Total number of tweets containing a link. This link can point to a website outside Twitter or to another tweet.
linksAndImages. Total number of tweets containing media and a link.
impact. Total number of potential impacts (impressions) generated by the hashtag. Impacts are calculated by multiplying the tweets of each user in the report by its followers and adding up the results. Example:

User 1: 10 tweets and 100 followers = 1000 potential impacts (impressions)

User 2: 5 tweets and 500 followers = 2500 potential impacts (impressions)

User 3: 1 tweet and 10000 followers = 10000 potential impacts (impressions)

TOTAL impacts = 1000 + 2500 + 10000 = 13500 potential impacts (impressions)
reach. Total number of users reached by the hashtag. Reach will always be less or equal than “impact”. The way Tweet Binder calculates this number is just by adding up the number of followers of each user in the report, the number of tweets here is not relevant. Using the same example than “impact”:

User 1: 100 followers

User 2: 500 followers

User 3: 10000 followers

TOTAL “reach” = 100 + 500 + 10000 = 10600 potential users reached (reach)
contributorsValue. Total economic value of the users who participated in the report. This unique metric by Tweet Binder shows how much the users of the report are worth translated to Twitter advertising investment. This metric, expressed by default in USD, is made combining other metrics of the user which are:
1. Number of followers
2. Number of following
3. Ratio followers/following
4. Number of lists the user is in
5. If the account is verified or not
6. Average Twitter impressions per tweet (given by Twitter, specialized blogs and experts)
7. Economic market value of an impact on Twitter (based on pay-per-tweet online platforms and CPMs by Twitter Ads)
economicValue. Total economic value of the hashtag the user analyzed. It is calculated using the “contributorsValue” and multiplying it by the type of tweets sent. Each type of tweet has an unique value.
clears. Total number of text tweets analyzed in the report. Tweets containing just text.
replies. Total number of replies analyzed in the report.
retweets. Total number of retweets analyzed in the report.
receivedRetweets. Total number of retweets received by the tweets in the report. This number can be different from “retweets” because it contains ALL the retweets received which can come from private accounts or just be outside the date range of the report. That’s why this number will always be equal or higher than “retweets”.
favorites. Total number of likes received by the tweets in the report.
Impressions. Number of actual impressions generated by the tweets of the report. This can be higher or lower than the potential impressions, but it is usually lower.
Quotes. Number of quotes generated by the tweets of the report.
totalReplies. Number of replies generated by the tweets of the report.
Bookmarks. Number of bookmars generated by the tweets of the report.
contributors. Total number of users who sent a tweet or a retweet using the hashtag of the report.
originalContributors. Total number of users who sent at least one original tweet. Original tweets are those which are not retweets.
originals. Total number of original tweets analyzed in the report. Original tweets are those which are no retweets.
tweetValueMean. Average value, expressed by default in USD, of each tweet of the report. This metric can also be used as a way of checking the influence of the users in the report.
influence. Average number of followers per user in the report. This metric is calculated by dividing “reach” by the number of “contributors”.
engagement. Average number of tweets sent per contributor. This metric is calculated by dividing “total” by contributors.
contributorValueMean. Average value of each contributor, expressed by default in USD. This metric is calculated by dividing “contributorsValue” by “contributors”.

Sentiment stats¶

Hashtag’s sentiment is calculated having several variables in consideration within each tweet and after that each tweet is given a value:

Positive
Negative
Neutral
Undefined

Untitled

Each value has its one metrics under an unique id “_positive” for example; the explanation for each metric is the same than in “general stats”. These metrics are:

total
images
links
linksAndImages
impact
reach
contributorsValue
economicValue
clears
replies
retweets
originalContributors
contributors
influence
engagement
originals
tweetValueMean
contributorValueMean

There is another metric for sentiment that is applied to the whole report:

score: the score shows how positive or negative is the hashtag. It shows a value between 0 and 100 where 0 is “very negative” and 100 is “very positive”.

Contributor rankings¶

Tweet Binder’s API provides a full range of contributor rankings showing contributors who have relation to the hashtag ordered by different variables. Each ranking shows:

10 users per ranking
And the fields for each user will be:
- _id: User ID on Twitter
- alias: Username on Twitter, example @tweetbinder
- name: the name the user shows on Twitter (different from alias)
- picture: url of the picture of the user on Twitter
- verified: it shows if the user is verified or not, true or false
- value: this value depends on the ranking, it can be tweets, impacts, etc. It is explained in each ranking below.

Rankings in this section of the API are:

mostActive: most active users using the hashtag of the report. It includes original tweets and retweets. Value: total tweets
mostFavorites: users with the highest number of likes in all their likes within the report. Value: likes
mostPopular: users with the highest number of followers. Value: followers.
mostRepliers: users with the highest number of replies sent in the report. ****Value: replies
highestImpact: users who have generated the highest number of impacts (impressions) in the report. This is calculated by multiplying the number of tweets sent (original or retweets) by the number of followers. Value: impacts
originalTweets: users who have sent the highest number of original tweets (no retweets). Value: original tweets.
retweeters: users who have sent the highest number of retweets. Value: retweets.
topPolite: users who have sent the highest number of positive tweets.
topTroll: users who have sent the highest number of negative tweets.
topPhotographers: users who have sent the highest number of tweets with media (pictures, GIF or videos). Value: tweets with media.
verifiedUsers: users who are verified on Twitter ordered by number of followers. Value: true or false.
topUsersValue: users with the highest economic value. Value: USD by default.
topUserTweetsValue: users who have generated the highest economic impact in the report. This is calculated by multiplying their economic value by the type of tweets sent. Value: USD by default.
topRetweetEngagers: users with the highest number of retweets by tweet sent. This is calculated by dividing the number of retweets the user got by its number of original tweets sent. Value: retweets per tweet.
topFavoriteEngagers: users with the highest number of likes by tweet sent. This is calculated by dividing the number of likes the user got by its number of original tweets sent. Value: likes per tweet.

Media Rankings¶

All these ranking show several types of metrics.

topPublications: Tweet Binder ranks the publication based on its engagement. The value of each publication is determined by retweets x 3 + likes. So if a publication (tweet) has 100 RTs and 50 likes, the value will be 350. This value will be be shown under the field publicationScore. This rankings shows the following fields (and all the publication rankings do):
1. _id: publication (tweet) id
2. counts: information about the publication
  1. favorites: number of likes of the tweet.
  2. publicationScore: publication score based on engagement.
  3. userValue: economic value of the user.
  4. tweetValue: economic value of the tweet.
  5. retweets: number of retweets of the tweet.
3. createdAt: date the publication was created. Expressed in milliseconds.
4. images: it shows the url to all the images in the tweet if it has any.
5. text: it shows the text of the tweet.
6. user: information about the user
  1. id: Twitter user for the user.
  2. name: chosen name of the user.
  3. alias: Twitter’s username.
  4. picture: profile picture of the user,
  5. followers: number of followers of the user.
  6. verified: this shows if the user is verified on Twitter. Values: true or false.
7. value: it shows again the publicationScore.
mostValuedTweets: this ranking shows the tweets ranked by economic value. The fields in this ranking, as the topPublications one, are: (same as topPublications)
1. _id: publication (tweet) id
2. counts: information about the publication
  1. favorites: number of likes of the tweet.
  2. publicationScore: publication score based on engagement.
  3. userValue: economic value of the user.
  4. tweetValue: economic value of the tweet.
  5. retweets: number of retweets of the tweet.
3. createdAt: date the publication was created. Expressed in milliseconds.
4. images: it shows the url to all the images in the tweet if it has any.
5. text: it shows the text of the tweet.
6. user: information about the user
  1. id: Twitter user for the user.
  2. name: chosen name of the user.
  3. alias: Twitter’s username.
  4. picture: profile picture of the user,
  5. followers: number of followers of the user.
  6. verified: this shows if the user is verified on Twitter. Values: true or false.
7. value: it shows again the economic value of the tweet.
mostRetweetedTweets: this ranking shows the most retweeted tweets. The fields are:
1. _id: publication (tweet) id
2. counts: information about the publication
  1. favorites: number of likes of the tweet.
  2. publicationScore: publication score based on engagement.
  3. userValue: economic value of the user.
  4. tweetValue: economic value of the tweet.
  5. retweets: number of retweets of the tweet.
3. createdAt: date the publication was created. Expressed in milliseconds.
4. images: it shows the url to all the images in the tweet if it has any.
5. text: it shows the text of the tweet.
6. user: information about the user
  1. id: Twitter user for the user.
  2. name: chosen name of the user.
  3. alias: Twitter’s username.
  4. picture: profile picture of the user,
  5. followers: number of followers of the user.
  6. verified: this shows if the user is verified on Twitter. Values: true or false.
7. value: it shows again the retweets of the tweet.
mostFavoritedTweets: this ranking shows the tweets ordered by number of likes. The fields also are:
1. _id: publication (tweet) id
2. counts: information about the publication
  1. favorites: number of likes of the tweet.
  2. publicationScore: publication score based on engagement.
  3. userValue: economic value of the user.
  4. tweetValue: economic value of the tweet.
  5. retweets: number of retweets of the tweet.
3. createdAt: date the publication was created. Expressed in milliseconds.
4. images: it shows the url to all the images in the tweet if it has any.
5. text: it shows the text of the tweet.
6. user: information about the user
  1. id: Twitter user for the user.
  2. name: chosen name of the user.
  3. alias: Twitter’s username.
  4. picture: profile picture of the user,
  5. followers: number of followers of the user.
  6. verified: this shows if the user is verified on Twitter. Values: true or false.
7. value: it shows again the likes.
topHashtags: this rankings shows the hashtags included on the tweets of the report ranked by number of tweets (including retweets and original tweets). The fields of this ranking are:
1. _id: this is the value of the hashtag.
2. value: this is a number value that shows the number of tweets.
topLanguages: ranking of all the languages of the tweets included on the report. The fields of this ranking are:
1. _id: this will be the language in ISO 639‑1.
2. value: number of tweets of that language (including retweets and original tweets).
topSources: this ranking shows the sources the tweets are sent from. It can be Twitter for iphone, android, etc. This ranking contains the following fields:
1. _id: actual source of the tweet
2. value: number of tweets sent from that source (including retweets and original tweets).
mostMentioned: this ranking shows the most mentioned users in the tweets of the report. Tweet Binder must run a petition to Twitter to collect this user information. The fields of each user are:
1. id: Twitter id of the user.
2. alias: username of the user.
3. name: chosen name of the user.
4. picture: url to the profile picture of the user.
5. followers: number of followers of the user.
6. verified: shows if the user is verified, true or falso field.
7. _id: username of the user.
8. value: number of mentions received by this user.
genderPerContributor: this rankings shows the distribution of the users by gender. There are three genders:
1. 0 = undefined
2. 1 = male
3. 2 = female
Each one has its own value, it represents the number of users in that gender.
mostRetweetedImages: this rankings shows the most retweeted tweets containing media: image(s), gif or video.
1. _id: publication (tweet) id
2. counts: information about the publication
  1. favorites: number of likes of the tweet.
  2. publicationScore: publication score based on engagement.
  3. userValue: economic value of the user.
  4. tweetValue: economic value of the tweet.
  5. retweets: number of retweets of the tweet.
3. createdAt: date the publication was created. Expressed in milliseconds.
4. images: it shows the url to all the images in the tweet if it has any.
5. text: it shows the text of the tweet.
6. user: information about the user
  1. id: Twitter user for the user.
  2. name: chosen name of the user.
  3. alias: Twitter’s username.
  4. picture: profile picture of the user,
  5. followers: number of followers of the user.
  6. verified: this shows if the user is verified on Twitter. Values: true or false.
7. value: it shows again the retweets of the image.
mostFavoritedImages: this rankings shows the most liked tweets containing media: image(s), gif or video.
1. _id: publication (tweet) id
2. counts: information about the publication
  1. favorites: number of likes of the tweet.
  2. publicationScore: publication score based on engagement.
  3. userValue: economic value of the user.
  4. tweetValue: economic value of the tweet.
  5. retweets: number of retweets of the tweet.
3. createdAt: date the publication was created. Expressed in milliseconds.
4. images: it shows the url to all the images in the tweet if it has any.
5. text: it shows the text of the tweet.
6. user: information about the user
  1. id: Twitter user for the user.
  2. name: chosen name of the user.
  3. alias: Twitter’s username.
  4. picture: profile picture of the user,
  5. followers: number of followers of the user.
  6. verified: this shows if the user is verified on Twitter. Values: true or false.
7. value: it shows again the liked of the image.
mostRetweeted: this rankings shows the most retweeted users of the report. The fields are:
- _id: User ID on Twitter
- alias: Username on Twitter, example @tweetbinder
- name: the name the user shows on Twitter (different from alias)
- picture: url of the picture of the user on Twitter
- verified: it shows if the user is verified or not, true or false
- value: number of retweets.
Influences¶

These are different metrics Tweet Binder uses to give more information in the report, they are divided in intervals and go from sentiment ranges to age and more. The intervals have a lower limit and upper limit which establish the values of that interval. These metrics are:
1. sentimentInfluence: it shows how many tweets are negative, positive or neutral. The are three ranges 0, 1 and 2:
  1. 0 = negative
  2. 1 = neutral
  3. 2 = positive
  The fields in each range are:
  1. influence: type of influence, negative, neutral or positive
  2. tweets: number of tweet of that “influence”
  3. lower limit: these are standard values, the starting limits of the influence
  4. upper limit: these are standard values, the ending limits of the influence
    1. tweetsPerContributor: this value shows how many tweets were sent by how many contributors. The ranges go from 1 tweet to more than 6 tweets:
  5. 0 = 1 tweet sent
  6. 1 = 2 tweets sent
  7. 2 = 3 tweets sent
  8. 3 = 4 tweets sent
  9. 4 = 5 tweets sent
  10. 5 = 6 tweets sent
  11. 6 = more than 6 tweets sent
  The fields in each range are:
  1. influence: number of tweets sent, from 1 to more than 6
  2. tweets: number of tweets inside that “influence”
  3. lower limit: these are standard values, the starting limits of the influence
  4. upper limit: these are standard values, the ending limits of the influence
  The average value shows the average number of tweets sent by contributor.
2. contributorInfluence: this metrics tells you how many users there are under certain ranges of followers. In this case, influence is based on number of followers. The intervals are:
  1. 0 = XXS from 0 to 10 followers
  2. 1 = XS from 10 to 50 followers
  3. 2 = S from 50 to 200 followers
  4. 3 = M from 200 to 500 followers
  5. 4 = L from 500 to 1000 followers
  6. 5 = XL from 1000 to 5000 followers
  7. 6 = XXL more than 5000 followers
  Each range will show the following fields:
  1. influence: type of influence from XXS to XXL
  2. contributors: number of contributors inside that “influence”
  3. lower limit: these are standard values, the starting limits of the influence
  4. upper limit: these are standard values, the ending limits of the influence
  The average value shows the average number of followers per contributor.
3. tweetValueInfluence: this metric shows how many tweets are between some parameters of economic value in USD. Tweet Binder assigns an economic value to each tweet, this metric groups tweets in several intervals which are:
  1. 0 = XS from 0 to 1 US Dollars
  2. 1 = S from 1 to 3 followers US Dollars
  3. 2 = M from 3 to 8 followers US Dollars
  4. 3 = L from 8 to 15 followers US Dollars
  5. 4 = XL more than 15 US Dollars
  Each range will show the following fields:
  1. influence: type of influence from XS to XL
  2. tweets: number of tweets inside that “influence”
  3. lower limit: these are standard values, the starting limits of the influence
  4. upper limit: these are standard values, the ending limits of the influence
  The average value shows the average economic value per tweet.
4. userValueInfluence: metric that shows the economic value assigned to each user. It has the same intervals and almost fields than the tweetValueInfluence metric:
  1. 0 = XS from 0 to 1 US Dollars
  2. 1 = S from 1 to 3 followers US Dollars
  3. 2 = M from 3 to 8 followers US Dollars
  4. 3 = L from 8 to 15 followers US Dollars
  5. 4 = XL more than 15 US Dollars
  Each range will show the following fields:
  1. influence: type of influence from XS to XL
  2. contributors: number of contributors inside that “influence”
  3. lower limit: these are standard values, the starting limits of the influence
  4. upper limit: these are standard values, the ending limits of the influence
  The average value shows the average economic value per user.
5. ageInfluence: this metric is based on the age of each account. The age is calculated from the creation date of the account. The limits are established in seconds and the ranges are:
  1. 0 = XXS from 0 to 31536000 seconds
  2. 1 = XS from 31536000 to 63072000 seconds
  3. 2 = S from 63072000 to 94608000 seconds
  4. 3 = M from 94608000 to 126144000 seconds
  5. 4 = L from 126144000 to 157680000 seconds
  6. 5 = XL from 157680000 to 189216000 seconds
  7. 6 = XXL more than 189216000 seconds
  Note: 31536000 equals 1 year.
  
  Each range will show the following fields:
  1. influence: type of influence from XS to XL
  2. tweets: number of contributors inside that “influence”
  3. lower limit: these are standard values, the starting limits of the influence
  4. upper limit: these are standard values, the ending limits of the influence
  The average value shows the average economic value per user.
6. textLengthInfluence: this metric shows how long the tweets are. In the past tweets used to be 140 characters long then, in 2017, they changed to 280. So tweets can be up to 280 characters. The intervals of this “influence” are:
  1. 0 = XXS from 0 to 40 characters
  2. 1 = XS from 40 to 80 characters
  3. 2 = S from 80 to 120 characters
  4. 3 = M from 120 to 160 characters
  5. 4 = L from 160 to 200 characters
  6. 5 = XL from 200 to 240 characters
  7. 6 = XXL more than 240 characters
  Each range will show the following fields:
  1. influence: type of influence from XXS to XXL
  2. tweets: number of tweets in that influence
  3. lower limit: these are standard values, the starting limits of the influence
  4. upper limit: these are standard values, the ending limits of the influence
  The average value shows the average length of a tweet in the report.
7. oldVsNewInfluence: this is an old metric use to differentiate how many tweets were sent with less than 140 characters and how many were sent with more than 140 characters. So there will be just two intervals:
  1. 0 = Old tweets, with less than 140 characters
  2. 1 = New tweets, with more than 140 characters
  Each range will show the following fields:
  1. influence: type of influence “old” or “new”
  2. tweets: number of tweets in that influence
  3. lower limit: these are standard values, the starting limits of the influence
  4. upper limit: these are standard values, the ending limits of the influence
  The average value shows the average length of a tweet in the report.
  
  Timeline¶
  
  The timeline shows in a temporal chart several datapoints. The timeline starts always with the date of the first tweet (expressed in seconds) and ends with the date of the last tweet. All the data points are grouped in a maximum of 30 points, each point contains the following data points:
  - tweets : number of tweets, included original tweets and retweets
  - linksAndImages : tweets with media or a link
  - retweets : retweets
  - originals : original tweets
  - replies : replies
  - tweetsValue : value of the tweets
  - images : number of images shared
  - links : tweets with link
  - positives : positive tweets
  - negatives : negative tweets
  - neutrals : neutral tweets
  - undefined : undefined tweets
  - min : starting of the chart (in seconds)
  - contributors : number of user
  - max : ending of the chart (in seconds)
Binders¶

Tweet Binder offers the possibility of classify the tweets of the report into “binders”. One binder would be a space in the report where we classify certain tweets from the report that contain one or more selected keywords.

You can create as many binders as you need within of the report. Each binder has the following fields:
1. Id: unique id of the binder
2. createdAt: date the binder was created, expressed in seconds.
3. name: name the user has chosen for the binder
4. terms: term or terms the tweets are filtered by in the binder
5. stats: each binder has its own stats, these are:
  1. total : total number of tweets
  2. clears : text tweets
  3. originals : original tweets
  4. retweets : retweets
  5. replies : replies
  6. impact : impacts
  7. links : tweets with links
  8. images : images in the binder
  9. linksAndImages : tweets with media or a link
  10. contributors : users
  11. tweetsContributors : average number of tweets per contributor
  12. followersContributors : average number of followers per contributor
Meta¶

This section offers some last data about the report. The fields are:
1. Updated at: date (in seconds) the report was updated. A report is updated if tweets enter or are deleted or the user creates a binder.
2. id: unique id of the report
3. name: this is the name of the report
4. search: info about the creation of the report:
  1. startedAt: date of the first tweet of the report, expressed in seconds.
  2. finishedAt: date of the last tweet of the report, expressed in seconds.
5. source: in this case it can only be Twitter
6. type: type of report, 7-day, historical, etc
7. version: (N/A)

Get report stats¶

Stats - Structure¶

General stats¶

Sentiment stats¶

Contributor rankings¶

Media Rankings¶

Influences¶

Timeline¶

Binders¶

Meta¶