Keyword Setup Guide

Correctly setting up keyword queries is critical for effective listening. This article provides guidance on how to use Boolean operators, quotes, parenthesis, nested queries and proximity operator.

Go to Campaign Overview and click on Add Keyword to set up a new keyword based query (or edit an existing one). Provide a Keyword name and type in the query.  When finished, make sure to click on "Add" or "Update" button to save your work!

The Add/Edit keyword user interface provides two interactive mechanisms to help you enter powerful queries while providing you guidance on avoiding common mistakes.
  1. A color coded Syntax Validation box will show Boolean operators in blue/red CAPS and keywords in green. It will display error message if there's a syntax issue such as missing term or unbalanced parenthesis. You will need to fix the error before you can save the keyword.
  2. The Syntax Tree is a visual, color-coded representation of your query as you type it. The inention is to show you how the query will be parsed so that you can avoid unitended mistakes. For example, one of the most common mistake is to forget using parenthesis for terms separated by OR and followed by NOT. In this case the NOT only applies to the last term, not the entire set of terms. See example below.

The simplest keywords consist of just one word / term - examples are:
  • verizon
  • #tmobile
  • @walmart
These keywords are easy to setup but can bring in heavy volume of results, depending on how unique or popular they are.

Keywords with Multiple Terms
Keywords with multiple words / terms match posts which contain ALL the words in the keyword, regardless of where they occur. More words/terms tend to act as a filter for noise: they bring in lesser volume than single term keywords while providing better results - examples are:
  • coverage #tmobile 
  • samsung galaxy s6
  • @verizon customer service
It is important to note that the words in above examples do not have to be next to each other or appear in the exact same order. The two words in the first example, coverage #tmobile, can be any number of words apart, as shown below in the real-world example from Twitter:

Thank you @ATT for saving me from #tmobile I finally have coverage no matter where I go!

Use Quotation Marks around words/terms for EXACT matches of that phrase; quotation marks should also be used for terms which include punctuation or non-alpahnumeric characters. Do NOT use quotation marks around hashtags or @names.

For a multiple word keyword, the words within quotation marks have to be right next to each other (no other word should separate them), in exactly the order/sequence as defined by the keyword. 
  • "bluebell recall"
  • "macy's"
  • walmart "hd tv"  
Use Boolean operators for advanced queries
  • AND - when you need to match all terms (jetblue AND "customer service")
  • OR - allows you to match only ONE of the term (@jetblue OR #jetblue )
  • NOT - excludes posts which include the terms after NOT
When you use two or more words in a term, AND is implicit e.g.
walmart store location == walmart AND store AND location 
"walmart store" location == "walmart AND store" AND location
Use Parentheses  
Parentheses are required between sets of terms with a Boolean operator between them. See examples below. Parentheses impose order of operation on the terms. That is, the terms within the parenthesis are processed first. Correctly using parenthesis provides a powerful way to  organize and group multiple terms in a Keyword.

** Omitting parenthesis is the most common mistake in keyword setup and it can change results dramatically **
  • (#Jetblue OR @jetblue) AND (customer service)
  • (#Jetblue OR @jetblue) AND (customer service) NOT stadium
  • (#Jetblue OR @jetblue) AND (customer service) NOT (stadium OR arena)
  •  (#fail OR sucks) AND (#tmobile OR (“t-mobile” AND service))
USEFUL TIP: Always use parenthesis around multiple OR terms!

Use ~ for Specifying Proximity Between Words
Use ~ immediately next to a term within quotes with a number from 1 through 6 to specify proximity between the individual words in the term. Words in the term do not have to appear in the exact order. 
  • “Jetblue best”~5 will match this tweet: Jetblue has the best service 
  • "verizon tv"~6 listens for verizon and tv when these keywords are within a distance of 6 words in a post.  
  • "verizon droid"~3 will also match "droid verizon"~3 
Tips and Limitations
  • Keywords are always matched explicity based on the grammar of the query and filters. In other words, its either a match or not a match.
  • Keywords are case insensitive i.e. verizon is the same as VERIZON 
  • Do NOT use quotation marks around #hashtags or @names - your keyword will not be accepted
  • NOT must be preceded by another term and cannot be used by itself. Example: "verizon samsung" NOT galaxy
Stop Words (Commonly used words)
  • Stop words are not allowed as stand-alone terms in queries. 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”. As long as there is at least one required and allowed term in the rule, it will be allowed. 
  • Here's the current stop words list (subject to change): "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"
  • If Boolean operators, "AND", "OR", and "NOT" are part of a keyword within quotes, they will be ignored
Special (non-alphanumeric) Characters
  • When using hashtags # or @names , do not use quotation marks.
  • Special characters need to be within quotes  ! % & \ ' ( ) * + - . / ; < = > ? \\ , :  \t \r \n " [ ] _
URLs within Posts
  • You can enter a URL as a keyword to search for full or partial match to correctly constructed URLs in a social post e.g. a clickable link in a Tweet
  • URLs should be entered with the http, https or equivalent. We recommend using both http and https. 
  • We also recommend adding URLs with and without the "www" as shown below. 
  •    --- matches -->
  •           --- matches --> ,
  • An example of a keyword with multiple URLs 

Maximum Length and Number of Operators
  • A keyword needs to be less than 1,000 characters -- the number of remaining characters are shown below the keyword entry box.
  • A single keyword/query can support up to 30 positive operators i.e. AND / OR terms, and up to 50 negative operators i.e. NOT terms.
Keyword Volume Estimation (Beta)
We have added a tool that allows you to estimate the approximate volume of Tweets for a keyword that you have created (even though you may not have saved it yet). Click on "Test" button to the botton right of keyword Syntax Tree and the distribution and volume of Tweets matching this keyword for last 30 days is shown below with a total and daily average. Important Caveats: (1) There are no language, location or exclusion filters applied to this estimate and (2) Twitter volume estimate is ONLY - does not include any other publisher/source. 

Even so, this could be valuable to get a high level idea of what volume to expect from this keyword. Very low or high is likely an indicator of a syntax or other error. You can tweak the keyword and get updated volume information.

Changes to existing keywords:
You can edit a keyword by hovering over the keyword and clicking on "edit" icon. You can also delete a keyword. Deleting a keyword does not automatically remove the results that were collected for it.

Listening Setup Video:


For more details please review our blog

Feedback and Knowledge Base