Viz Social User Guide
Version 1.0 | Published June 22, 2021 ©
The Twitter section supports various Search options:
-
The Term or Hashtag Search, which comes in three flavors:
-
High volume, no history, results 100% guaranteed for all volumes, cost per 100k Tweets : Based on Twitter's/Gnip's Powertrack API.
-
Medium volume, no history, free : Based on Twitter's Streaming API.
-
Low volume, with history, free : Based on Twitter's REST API.
-
-
The User Monitor, which comes in two flavors:
-
Medium volume, no history, free : Based on Twitter's Streaming API.
-
Low volume, with history, free : Based on Twitter's REST API.
-
-
The List Monitor, Low volume, with history, free: Based on Twitter's REST API.
-
The Twitter Moment Monitor, Low volume, with history, free: Partly based on Twitter's REST API.
-
The Timeline Monitor, Low volume, with history, free: Based on Twitter's REST API.
-
The Tweet Monitor, High volume, without history, cost per tracked account : Based on Twitter's Account Activity API.
The advantage of the Twitter Search API over Twitter's Streaming API is that the former allows one to (also) look back into the history (at most seven days and no more than 10.000 Tweets). The disadvantage is that Twitter does not guarantee completeness of the response and gives no specific logic why some Tweets are returned and others not. The Twitter Streaming API is complete (up to its rate limit) but is not able to take in any Tweets from before it was set-up.
According to the Twitter rules, all requests must be issued on behalf of a Twitter account. All registered Twitter accounts are available for use in the 'low volume, with history' Twitter Searches.
From a functional perspective the choice of Twitter account in a Search is not relevant. However, Twitter assigns each account its own quota, so using multiple accounts is a method to increase bandwidth and to avoid congestion.
Twitter Term Search (low volume, with history, free)
The Twitter Term Search (low volume, with history, free) queries Twitter for Tweets in the recent past containing the search pattern. Search terms can contain #hashtags, @mentions or just separated words. When multiple terms are separated by a space a logical AND is applied. When multiple terms are separated by a comma a logical OR is assumed. Alternatively, “AND” and “OR” themselves (in capitals) can be used as well. The number of historical posts to begin with can be selected from the dropdown list.
By default, the Query is executed once per minute, but it is possible to query more or less often on the advanced tab. The default interval of 60 seconds translates into an average end-to-end latency of 30 seconds and a maximum one of 60 seconds. This is sufficient to cover almost all use cases. Lower frequencies free up resources at the cost of an increased latency. Higher frequencies decrease latency at the expense of resources (which translates in a reduced number of parallel Searches).
Note: It is recommended to first do a sanity check together with Vizrt support before changing these values.
User Monitor (low volume, with history, free)
The Twitter User Monitor (low volume, with history, free) tracks the Tweets from the specified Twitter users. Apart from one or more monitored accounts, no further input is necessary. At most 20 Twitter accounts can be tracked in a single Search.
The Search frequency can be set for this Search as well. The same considerations as in 3.5.2.1 apply here as well.
List Monitor (low volume, with history, free)
The Twitter List Monitor (low volume, with history, free) queries Twitter for Tweets on a particular Twitter List. The set-up of this Search a two step process: First, the list owner is requested, which is then used by Viz Social to find all Twitter Lists owned by this user. The user can then choose which list to be monitored.
The Search frequency can be set for this Search as well. The same considerations as in the Low volume Twitter Term Search apply.
Timeline Monitor (low volume, with history, free)
The Twitter Timeline Monitor (low volume, with history, free) queries Twitter for Tweets originating from a certain account, including Retweets, Quoted Tweets and Replies.
The Search frequency can be set for this Search as well. The same considerations as in the Low volume Twitter Term Search apply.
Term Search (medium volume, no history, free)
The Twitter Term Search (medium volume, no history, free) queries Twitter for Tweets in the recent past containing the search pattern. In contrast to the low volume Search, it does not return historic Tweets to start with, so it starts harvesting posts the moment it is activated. On the other hand, it has a significantly higher capacity and guarantees completeness of the results as long as its rate limit isn't crossed (see Volume and volume Limits).
Search terms can contain #hashtags, @mentions or just separated words. When multiple terms are separated by a space a logical AND is applied. When multiple terms are separated by a comma a logical OR is assumed. Alternatively, AND and OR themselves (in capitals) can be used as well. The number of historical posts to begin with can be selected from the dropdown list.
User Monitor (medium volume, no history, free)
The Twitter User Monitor (medium performance, no history, free) tracks the Tweets from the specified Twitter users. Apart from one or more monitored accounts, no further input is necessary. At most, 500 Twitter accounts can be tracked in a single Search.
In contrast to the low volume Search API, it does not return historic Tweets to start with, so it starts harvesting posts the moment it is activated. On the other hand, it has a significantly higher capacity and guarantees completeness of the results as long as its rate limit isn't crossed (see Volume and Performance Limits).
Term Search (high-performance, no history, cost per 100k Tweets)
The high-performance Twitter Firehose Term Search offers access, at a volume dependent cost, to the Twitter Firehose where all tweets worldwide are being published. Setting up Searches via this channel guarantees completeness of the harvested tweets satisfying a certain Search pattern, irrespective of the volume. This way all chatter around massive events like the Oscars, the Super Bowl or the Eurovision Song Contest can be tracked and processed. In addition, the Twitter Firehose is useful for contests where the legal obligation exists to prove that literally all relevant Tweets after a call-to-action are captured before prizes/winners are drawn.
Searches on Twitter's Firehose use the same syntax as other Twitter Searches.
Example:
-
searching for 'cat dog' or 'cat AND dog' returns all Tweets containing both 'cat' and 'dog'
-
searching for 'cat OR dog' returns all Tweets containing 'cat' or 'dog'
-
searching for '"cat dog"' returns all Tweets containing 'cat dog'
-
~ means NOT, so search for cat ~dog returns results that contain cat but not dog.
-
Extra rule 1: to keep search volumes within reasonable limits, it is not allowed to solely search for an exclusion. For instance, searching for ~dog would return all Tweets that do not contain dog, which is an extremely high volume.
-
Extra rule 2: for the same reason, it is not allowed to search for an exclusion combined only with ORs. For instance, cat OR ~dog would return all Tweets containing cat, or not dog, or both. Again, an extremely high number.
-
-
( and ) are parenthesis to modify the order in which operands are executed. This is a form of nesting and there is no limit to the nesting level as long as the search string remains syntactically correct (mostly that all parentheses must come in pairs).
-
For instance, searching for cat dog OR duck (which is the same as searching for (cat dog) OR duck because the operands are executed from left to right) returns results containing either both cat and dog, or duck (or both).
-
Whereas searching for cat (dog OR duck) returns results containing cat and either dog or duck (or both).
-
The current cost for each Search is shown in the left column of Gather. In the Advanced tab, a maximum cost for the Search can be configured. The monthly total cost for the overall server is shown in the status menu in the top right corner.
To prevent bill shock situations where high volume Searches unintentionally lead to enormous and unexpected costs, search queries only containing one of the most frequently used words (so-called stop words) are not allowed. If you need to find a phrase that contains a stop word, either pair it with an additional term, or use the exact match operators such as "on the roof". If there is at least one required allowed term in the query, the whole query is allowed.
Note: The current list of stop words is: a, an, and, at, but, by, com, from, http, https, if, in, is, it, its, me, my, or, rt, the, this, to, too, via, we, www, you. Please note that this list is subject to change.
Because of its guaranteed completeness even under the highest of peaks, we advise our customers to consider using the Firehose Search when tracking Twitter during mass events or for competitions that require guaranteed completeness and exactness.
Access to the Twitter Firehose requires a separate commercial license and its access is disabled by default. Please contact your Support representative for further information.
Monitor a Tweet
The Twitter Account Activity API allows users to monitor selective activity related to a specific Tweet. Viz Social supports tracking of a Tweet's likes, retweets, quotes and replies. The user can decide which of these operations need to be tracked on a Tweet-by-Tweet basis. Only Tweets owned by the selected Twitter account can be monitored. Viz Social shows the tracked Tweet as a pinned post at the top of the results and all activities as individual posts below it.
The Search comes in two varieties, labelled respectively Monitor an existing Tweet and Monitoring a new Tweet. For monitoring an existing Tweet, when owning account has been chosen, Viz Social then offers a list of recent Tweets by that account that the user can choose to monitor. The monitoring starts the moment the Search is created, so it doesn't fetch any operations from before that moment.
For monitoring a new Tweet, the user can compose a new Tweet including attachment which is tracked immediately after its creation.
Retweets, quotes and replies are displayed like they are in other Twitter Searches. Likes appear similar to retweets, except with a heart icon and liked instead of a retweet icon and retweeted.
Access to the Twitter Account Activity requires a separate commercial license and its access is disabled by default. Please contact your Support representative for further information.
Filters
Supported filtering capabilities for Twitter Searches are:
-
Exactly matched, partially matched, regexp matched words/terms (not for Twitter Firehose Searches).
-
Exclusion of specific words/terms
-
Exclusion of retweets, quoted tweets, replies, likes or sensitive tweets
-
Originator white or blacklist
-
Min/max number of followers and friends
-
Account age
-
Verified accounts (Y/N)
-
Tweet language (with configurable presets to adjust to local preferences).
-
Media (type) presence
|
Twitter Term Search with Media Filter |
|
|
|
Twitter Term Search with Exclude Filter |
|
|
|
Twitter Term Search with an Engagement Filter |
|
|
Auto-Response
Viz Social comes with a built-in auto-reply function for all Twitter Searches. Running a social campaign, enables operators to thank their participants and/or to provide them with further information or instructions.
This function is available under the Auto-response tab in Gather for the Term/Hashtag Searches (Low performance, Medium performance and High performance) and the Tweet Monitor (High performance). When active, it offers the possibility to send a configurable message back to the originator of each incoming Tweet or tracked Tweet activity. Apart from the message text, an attachment and the originating account of the response can be chosen as well. The response is sent as a reply to the Tweet or, in case of a tracked Twitter like, a mention of the liked Twitter User.
The auto-response function must be specifically enabled by Support staff under separate discussion.
Note: By default each Twitter account can send at most 2400 Tweets per day, so usually an outgoing throttle limit is set to protect Viz Social from being marked as a spamming application.
Contact Support for help approaching Twitter in case these volumes are insufficient for the use case at hand. For certain agreed cases this default limit can be lifted by Twitter.