Introduction  

Products utilizing PowerTrack rules deliver social data to you based on filtering rules you set up. Rules are made up of one or more ‘clauses’, where a clause is a keyword, exact phrase, or one of the many PowerTrack Operators. Before beginning to build PowerTrack rules, be sure to review the syntax described below, look through the list of available operators, and understand the restrictions around building rules. You should also be sure to understand the nuances of how rules are evaluated logically, in the ‘order of operations’ section.

Multiple clauses can be combined with both ‘and’ and ‘or’ logic. ‘And’ logic is specified with a space between clauses, and ‘or’ logic is specified with an upper-case OR. See Core Concepts section for more details.

Note: 30-Day Search supports up to 2,048 characters per rule, with no limit on the number of positive clauses or negative clauses.

List of Operators 

Below is a list of all operators supported in 30-day Search 2.0.

Operator Description

keyword

Matches a keyword within the body of an activity. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the activity body – tokenization is based on punctuation, symbol, and separator Unicode basic plane characters. For example, an activity with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your rule. To match strings containing punctuation (e.g. coca-cola), symbol, or separator characters, you must use a quoted exact match as described below.

Gnip Rule Match No Match
gnip I need to call gnip
Check out gnip's documentation.
I love the @gnip blog.
Check out Gnip.
#gniprocks
cola Ice cold cola on a hot day
I like coca-cola!
I like cocacola!
snow please let it snow!

twitter_entities.urls.display_url: https://en.wikipedia.org/wiki/Snow

gnip.urls.expanded_url: http://www.snowdays.com/2015/01/how-to-get-more-snow-days/
it is finally snowing!
Coachella Hanging out at #coachella NEW.PICS.FROM.COACHELLA2015!



See Examples

"exact phrase match"

Matches an exact phrase within the body of an activity.

Note: In Search 2.0, punctuation is not tokenized and is instead treated as whitespace.

e.g. quoted “#hashtag” will match “hashtag” but not #hashtag (use the hashtag # operator without quotes to match on actual hashtags

e.g. quoted “$cashtag” will match “cashtag” but not $cashtag (use the cashtag $ operator without quotes to match on actual cashtags

Gnip Rule Match No Match
"call gnip" Let's call gnip now!
I need to call gnip, again
http://gnip.com/contact/call-gnip
Let's give gnip a call
recall gnip
"Search API for Twitter" Check out http://blog.gnip.com/search-api-for-twitter for more.
What kind of search api for twitter is available?
Should I use the search api for Gnip and Twitter?
"#coca-cola" Best soda ever- coca-cola
I love coca cola, it's the best.
I like cocacola with ice.
That #cocacola commerical was awesome!



See Examples

"keyword1 keyword2"~N

Commonly referred to as a proximity operator, this matches an activity where the keywords are no more than N tokens from each other.

If the keywords are in the opposite order, they can not be more than N-2 tokens from each other.

Can have any number of keywords in quotes.

N cannot be greater than 6.

Gnip Rule Match No Match
"love boulder"~4 Love everything about my town Boulder.
Boulder, I love living here.
I don’t love hiking, but I really like to visit Boulder.
Boulder is a place I love to visit.



See Examples

from:

Matches any Tweet from a specific user.

The value must be the user’s Twitter numeric Account ID or username (excluding the @ character). See HERE or HERE for methods for looking up numeric Twitter Account IDs.

Gnip Rule Match No Match
from:17200003 All original tweets from user 1720003
Retweets of others' tweets by user 1720003
Replies made by user 1720003 on others' tweets
Tweets from this user 1720003, regardless of user's changed username
Retweets of user 1720003 tweets by other users
from:mikesmith All original tweets from user mikesmith
Retweets of others' tweets by mikesmith
Retweets of mikesmith tweets by other users
Tweets from this user, with a different or changed username



See Examples

to:

Matches any Tweet that is in reply to a particular user.

The value must be the user’s numeric Account ID or username (excluding the @ character). See HERE for methods for looking up numeric Twitter Account IDs.

Gnip Rule Match No Match
Twitter
to:gnip
to:16958875
Tweets that have a Tweet ID from @Gnip as the in_reply_to: id specified
Reply to a tweet sent originally by @gnip (Twitter ID = 16958875)
Tweets that start with @Gnip
Tweet that mentions @gnip but not start with @gnip
Quote tweets of tweets from @gnip



See Examples

url:

Performs a tokenized (keyword/phrase) match on the expanded URLs of a tweet (similar to url_contains).

Gnip Rule Match No Match
url:gnip http://support.gnip.com/
https://blog.twitter.com/2014/twitter-welcomes-gnip-to-the-flock
https://gn.ip.com
https://github.com/abh1nav/gnippy
url:"big-data" https://medium.com/@user/reinventing-social-sciences-in-the-era-of-big-data-d255f3e391f3
http://www.cmswire.com/big-data/mapr-patents-its-big-data-cruncher/
https://gnip.com/bigdata/blog-post-01
https://github.com/big/data-testing



See Examples

has:links

This operators matches activities which contain links in the message body.


Note: All ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @gnip has:links)

Gnip Rule Match No Match
cat has:links Here's a picture of my cat: bit.ly/cat
Adopt a cat at http://spca.org/cats
Check out @gnip
Check out #gnip



See Examples

#

Matches any activity with the given hashtag.

This operator performs an exact match, NOT a tokenized match, meaning the rule “2016” will match posts with the exact hashtag “2016”, but not those with the hashtag “2016election”

Note: that the hashtag operator relies on Twitter’s entity extraction to match hashtags, rather than extracting the hashtag from the body itself. The description of how Twitter extracts entities can be found here: http://dev.twitter.com/pages/tweet_entities.

Gnip Rule Match No Match
#politics All posts tagged with #politics  
#2016_election All posts tagged with #2016_election Posts tagged with #2016
#boulderfire All posts tagged with #boulderfire Posts tagged with #boulderfirefighters



See Examples

point_radius:[lon lat radius]

Matches against the Exact Location (x,y) of the Activity when present, and in Twitter, against a “Place” geo polygon, where the Place is fully contained within the defined region.

  • Units of radius supported are miles (mi) and kilometers (km).
  • Radius must be less than 25mi.
  • Longitude is in the range of ±180
  • Latitude is in the range of ±90
  • All coordinates are in decimal degrees.
  • Rule arguments are contained with brackets, space delimited.
Gnip Rule Match No Match
point_radius:[-105.27346517 40.01924738 0.5mi] Geo-tagged Tweets within .5 miles of 17th and Pearl Street in Boulder, CO. Geo-tagged Tweets outside more than .5 miles from 17th and Pearl in Boulder, CO.
Tweets without place defined
point_radius:[2.355128 48.861118 16km] Geo-tagged Tweets within 16 kilometers of the center of Paris, France Geo-tagged Tweets outside more than 16 kilometers from the center of Paris, France
Tweets without place defined



See Examples

bounding_box:[west_long south_lat east_long north_lat]

Matches against the Exact Location (x,y) of the Activity when present, and in Twitter, against a “Place” geo polygon, where the Place is fully contained within the defined region.

  • west_long south_lat represent the southwest corner of the bounding box where west-long is the longitude of that point, and south_lat is the latitude.
  • east_long and north_lat represent the northeast corner of the bounding box, where east_long is the longitude of that point, and north_lat is the latitude.
  • Width and height of the bounding box must be less than 25mi
  • Longitude is in the range of ±180
  • Latitude is in the range of ±90
  • All coordinates are in decimal degrees.
  • Rule arguments are contained with brackets, space delimited.
Gnip Rule Match No Match
bounding_box:[-105.301758 39.964069 -105.178505 40.09455] Tweets (with place) or Checkins with coordinates contained within a box drawn around Boulder, CO Tweets (with place) or Checkins outside the box drawn around Boulder, CO
Tweets without place defined.



See Examples

@

Matches any Tweet that mentions the given username.

The to: operator returns a subset match of the @mention operator.

The value can be either the username (excluding the @ character) or the user’s numeric Account ID or. See HERE or HERE for methods for looking up numeric Twitter Account IDs.

@ gnip
Gnip Rule Match No Match
@gnip cool @gnip stuff
"entities":{user_mentions":[{"screen_name":"gnip","name":"Gnip, Inc.","id_str":"16958875"}]
cool stuff @gnipeng
cool stuff #gnip



See Examples

$

Matches any Tweet that contains the specified ‘cashtag’ (where the leading character of the token is the ‘$’ character).

Note that the cashtag operator relies on Twitter’s ‘symbols’ entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself. The description of how Twitter extracts entities can be found here: https://dev.twitter.com/overview/api/entities.

Gnip Rule Match No Match
$TWTR snow Everytime we have snow $TWTR changes Everytime I use TWTR $SNOW changes



See Examples

retweets_of:

Matches tweets that are retweets of a specified user. Accepts both usernames and numeric Twitter Account IDs (NOT tweet status IDs).
See HERE or HERE for methods for looking up numeric Twitter Account IDs.

Gnip Rule Match No Match
retweets_of:justinbieber When verb:share this matches on the object.actor.preferredUsername:justinbieber
Retweets of organic tweets from justinbieber account
Retweets of retweets by justinbieber
Quoted justinbieber tweets
retweets_of:6264412    



See Examples

lang:

Matches tweets that have been classified by Twitter as being of a particular language (if, and only if, the tweet has been classified). It is important to note that each activity is currently only classified as being of one language, so AND’ing together multiple languages will yield no results.

Note: if no language classification can be made the provided result is ‘und’ (for undefined).

The list below represents the current supported languages and their corresponding BCP 47 language indentifier:

  • Amharic - am
  • Arabic - ar
  • Armenian - hy
  • Bengali - bn
  • Bulgarian - bg
  • Burmese - my
  • Chinese - zh
  • Czech - cs
  • Danish - da
  • Dutch - nl
  • English - en
  • Estonian - et
  • Finnish - fi
  • French - fr
  • Georgian - ka
  • German - de
  • Greek - el
  • Gujarati - gu
  • Haitian - ht
  • Hebrew - iw
  • Hindi - hi
  • Hungarian - hu
  • Icelandic - is
  • Indonesian - in
  • Italian - it
  • Japanese - ja
  • Kannada - kn
  • Khmer - km
  • Korean - ko
  • Lao - lo
  • Latvian - lv
  • Lithuanian - lt
  • Malayalam - ml
  • Maldivian - dv
  • Marathi - mr
  • Nepali - ne
  • Norwegian - no
  • Oriya - or
  • Panjabi - pa
  • Pashto - ps
  • Persian - fa
  • Polish - pl
  • Portuguese - pt
  • Romanian - ro
  • Russian - ru
  • Serbian - sr
  • Sindhi - sd
  • Sinhala - si
  • Slovak - sk
  • Slovenian - sl
  • Sorani Kurdish - ckb
  • Spanish - es
  • Swedish - sv
  • Tagalog - tl
  • Tamil - ta
  • Telugu - te
  • Thai - th
  • Tibetan - bo
  • Turkish - tr
  • Ukrainian - uk
  • Urdu - ur
  • Uyghur - ug
  • Vietnamese - vi
  • Welsh - cy
Gnip Rule Match No Match
lang:fr "C'est un plaisir de vous rencontrer!" "Nice to meet you!"



See Examples

is:verified

Deliver only Tweets where the author is “verified” by Twitter. Can also be negated to exclude Tweets where the author is verified.

Note: All ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @gnip has:links)

Gnip Rule Match No Match
dog is:verified Tweets from verified users with the keyword dog  
cat -is:verified Tweets only from not verified users with the keyword dog  
dog OR (cat is:verified) Tweets containing the keyword dog or Tweets from verified users with the keyword cat  
(dog OR cat) is:verified Tweets from verified users with either the keyword dog or the keyword cat  



See Examples

place:

Matches tweets tagged with the specified location or Twitter place ID (see examples). Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes.

Note: See the GET geo/search public API endpoint for how to obtain Twitter place IDs.

Gnip Rule Match No Match
place:"Rio de Janeiro" Tweets that are geo-tagged with the exact place.name Rio de Janeiro Tweets where place:null
place:Florida Tweets that are geo-tagged with the exact place.name:Florida Tweets that are geo-tagged with place.name:USA
Tweets where place:null
place:fd70c22040963ac7 Tweets that are geo-tagged with the exact Twitter place.id:fd70c22040963ac7
Tweets that are geo-tagged with Boulder, CO (place.id:fd70c22040963ac7)
Tweets where place.id:e21c8e4914eef2b3 (Note: this is the placeID for the state Colorado)
Tweets where place:null



See Examples

place_country:

Matches tweets where the country code associated with a tagged place/location matches the given ISO alpha-2 character code.

Valid ISO codes can be found here: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

Gnip Rule Match No Match
place_country:us Tweets with the United States place/location country code
location.twitter_country_code:US
 
place_country:gb Tweets with the Great Britain place/location country code
location.twitter_country_code:GB
 
place_country:uk No matches, UK is not an ISO alpha-2 country code  
place_country:USA No matches, USA is not an ISO alpha-2 country code  



See Examples

has:geo

Matches Tweets that have Tweet-specific geo location data provided from Twitter. This can be either “geo” lat-long coordinate, or a “location” in the form of a Twitter “Place”, with corresponding display name, geo polygon, and other fields.

Note: All ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @gnip has:links)

Gnip Rule Match No Match
sale has:geo Any Tweets with geolocation data, either an exact lat/lon or a named "place", that also have the keyword 'sale' in the body of the Tweet Tweets that have keyword 'sale' but do not have a place/location
sale -has:geo Tweets that have keyword 'sale' that do not have a place/location



See Examples

has:mentions

Matches Tweets that mention another Twitter user.

Note: All ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @gnip has:links)

Gnip Rule Match No Match
"best friends" has:mentions Tweets that mention other users and have the phrase "best friends"  
enemies -has:mentions Tweets that have the keyword enemies and do not mention other users  



See Examples

has:hashtags

Matches Tweets that contain a hashtag.

Note: All ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @gnip has:links)

Gnip Rule Match No Match
cat has:hashtags My cat is too fat. #diet
My cat just had kittens. #cute
 



See Examples

has:images

A boolean search operator that returns all tweets that contain a native images (e.g. pic.twitter.com). Please note that this a subset of has:media.

Gnip Rule Match No Match
has:images Tweets with an image pic.twitter.com



See Examples

has:media

Matches Tweets that contain a media url classified by Twitter, e.g. pic.twitter.com.

Note: All ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @gnip has:links)

Gnip Rule Match No Match
has:media (Any Tweets that contain a media url as classified by Twitter including images and videos)  



See Examples

has:symbols

Matches Tweets that contain a cashtag symbol (with a leading ‘$’ character, e.g. $tag).

Note: All ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @gnip has:links)

Gnip Rule Match No Match
has:symbols Any predictions for $TWTR? Not sure what to do with my ca$h.



See Examples

has:videos

Matches Tweets that contain native Twitter videos, uploaded directly to Twitter. This will not match on videos created with Vine, Periscope, or Tweets with links to other video hosting sites.

Note: All ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @gnip has:links)

Gnip Rule Match No Match
has:videos (Any tweets that contain a native Twitter video)  



See Examples

is:retweet

Deliver only explicit retweets that match a rule. Can also be negated to exclude retweets that match a rule from delivery and only original content is delivered.

This operator looks only for true Retweets, which use Twitter’s retweet functionality. Quoted Tweets and Modified Tweets which do not use Twitter’s retweet functionality will not be matched by this operator.

Note: All ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @gnip has:links)

Gnip Rule Match No Match
dog is:retweet    
cat -is:retweet    
dog OR (cat is:retweet)    
(dog OR cat) is:retweet    



See Examples

has:profile_geo

Matches tweets that have any Profile Geo metadata, regardless of the actual value.

Gnip Rule Match
cat has:profile_geo If account is enabled for the Profile-Geo Enrichment, this will match any Tweets that mentions the word “cat” and has any Gnip Profile Geo metadata derived from the user's bio "location". Tweets from accounts that do not have a bio "location" entered by the user



See Examples

profile_country:

Exact match on the “countryCode” field from the “address” object in the Profile Geo enrichment.

Uses a normalized set of two-letter country codes, based on ISO-3166-1-alpha-2 specification. This operator is provided in lieu of an operator for “country” field from the “address” object to be concise.

Gnip Rule Match
profile_country:us All Profile Geo Enrichments in the United States.



See Examples

profile_region:

Matches on the “region” field from the “address” object in the Profile Geo enrichment.

This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\/two”. Use double quotes to match substrings that contain whitespace or punctuation.

Gnip Rule Match
profile_region:"New York" All Profile Geo Enrichments in New York state



See Examples

profile_locality:

Matches on the “locality” field from the “address” object in the Profile Geo enrichment.

This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\/two”. Use double quotes to match substrings that contain whitespace or punctuation.

Gnip Rule Match
profile_locality:boulder All Profile Geo Enrichments in ANY city named "Boulder"



See Examples


Core Concepts  

Keyword match

Keyword matches are similar to queries in a search interface (e.g. Google). For example, the following PowerTrack rule would match activities with ‘happy’ in the text body.

 happy

ANDing terms with white space

Adding another keyword is the same as adding another requirement for finding matches. For example, this rule would only match activities where both ‘happy’ and ‘party’ were present in the text, in either order – having a space between terms operates as boolean AND logic.

Note: if you include an explicit AND in your rule, it will be treated as a regular keyword.

 happy party

ORing terms with upper-case OR

Many situations actually call for boolean OR logic, however. This is easily accomplished as well.

Note: that the OR operator must be upper-case and a lower-case ‘or’ will be treated as a regular keyword in your rule.

 happy OR party

Negating terms

Still other scenarios might call for excluding results with certain keywords (a boolean NOT logic). For instance, activities with ‘happy’, but excluding any with ‘birthday’ in the text.

 happy -birthday

Grouping with parentheses

These types of logic can be combined using grouping with parentheses, and expanded to much more complex queries.

 (happy OR party) (holiday OR house) -(birthday OR democratic OR republican)

This is just the beginning though – while the above examples rely simply on tokenized matching for keywords, PowerTrack also offers a operators to perform different types of matching on the text.

Exact match

 "happy birthday"

Proximity match

 "happy birthday"~3

Further, other operators allow you to filter on unique aspects of social data, besides just the text. For example:

The user who is posting a Tweet

 from:user

Geo-tagged Tweets within 10 miles of Pearl St. in Boulder, CO

 point_radius:[-105.27346517 40.01924738 10.0mi]

Putting it all together

These can be combined with text filters using the same types of logic described above.

 (happy OR party) (holiday OR house OR "new year's eve") point_radius:[-105.27346517 40.01924738 10.0mi] lang:en -(birthday OR democratic OR republican)

Boolean Syntax 

The examples in the previous section, utilized various types of boolean logic and grouping. See the table below for additional detail regarding the syntax and requirements for each.

Logic Type PowerTrack Syntax Description
AND social data Whitespace between two operators results in AND logic between them

Matches activities containing BOTH keywords ('social', 'data').

Do NOT use AND explicitly in your rule. Only use whitespace. An explicit AND will be treated like a regular keyword.
OR social OR data To OR together two operators, insert an all-caps OR, enclosed in whitespace between them

Matches activities with EITHER keyword ('social' OR 'data')

Note that if you combine OR and AND functionality in a single rule, you should understand the order of operations described here, and consider grouping operators together using parentheses as described below to ensure your rule behaves as expected.

You must use upper-case 'OR' in your rule. Lower-case 'or' will be treated as a regular keyword.
NOT  social -data
apple -(fruit OR orange)
apple -(android phone)
Insert a - character immediately in front of the operator or group of operators.

The example rule shown matches activities containing keyword 'social', but excludes those which contain the keyword 'data')

Negated ORs are not allowed where the rule would request "everything in the firehose except the negation." E.g., apple OR -ipad is invalid because it would match all activities except those mentioning 'ipad'.
Grouping (social OR data) -(gnop OR ping) Parentheses around multiple operators create a functional "group".

Groups can be connected to clauses in the same manner as an individual clause via whitespace (AND) or ORs, and can be negated. However, note that the same restriction described above regarding negation/OR combination also applies to groups. For example, the following are examples of invalid syntax using groups:
ipad OR -(iphone OR ipod)
ipad OR (-iphone OR ipod)

Grouping is especially important where a single rule combines AND and OR functionality, due to the order of operations used to evaluate the rule. See below for more details.

Note that Operators may be either positive or negative.

Positive Operators  define what you want to include in the results. E.g. the ‘has:geo’ operator says “I want Tweets containing geo metadata.”

Negative Operators  define what you want to exclude from the results, and are created by using the Boolean NOT logic described above. E.g. ‘-has:mentions’ says “Exclude any activities with @mentions, even if they otherwise match my rule.”

A single Search API query/rule can support up to 30 positive operators, and up to 50 negative operators, subject to the restrictions documented here.


Order of Operations 

When combining AND and OR functionality in a single rule, the following order of operations will dictate how your rule is evaluated.

  1. Operators connected by AND logic are combined first
  2. Then, Operators connected with OR logic are applied

Example:

  • apple OR iphone ipad would be evaluated as apple OR (iphone ipad)
  • ipad iphone OR android would be evaluated as (iphone ipad) OR android

To eliminate uncertainty and ensure that your rules are evaluated as intended, group terms together with parentheses where appropriate. For example:

  • (apple OR iphone) ipad
  • iphone (ipad OR android)

Punctuation, Diacritics, and Case Sensitivity 

Also see Restrictions below.

If you specify a keyword or hashtag rule with character accents or diacritics for the Search APIs, it will match Tweet text regardless of the diacritics (hashtags or keywords). Rule with a keyword Diacrítica or hashtag #cumpleaños will match Diacrítica or #cumpleaños and will match Diacritica or #cumpleanos without the tilde í or eñe.

Characters with accents or diacritics are treated the same as normal characters and are not treated as word boundaries. For example, a rule of cumpleaños would only match activities containing the word cumpleaños and would not match activities containing cumplea, cumplean, or os.

All operators are evaluated in a case-insensitive manner. For example, the rule Cat will match all of the following: cat, CAT, Cat.


Rule Tags 

As described here, each rule may be created with a tag. These tags have no effect on filtering, but can be used to create logical groupings of rules within your app. Each rule may have only one tag, with a maximum of 255 characters. Tags are included with the JSON formatted rule at the time of creation via the API, as described in our documentation.


Putting Rules in JSON Format 

In order to add or delete a rule from a PowerTrack stream via the API, the rules must utilize JSON format. Essentially, this requires putting each rule into the following structure:

 {"value":"insert_rule_here"}

Rules with Double-quotes

If the ‘rule’ contains double-quote characters (“) associated with exact-match or other operators, they must be escaped using a backslash to distinguish them from the structure of the JSON format. For example, if your rule is:

 "social data" @gnip

The JSON formatted rule would be:

 {"value":"\"social data\" @gnip"}

Rules with Double-quote String Literals

To include a double-quote character as a string literal within an exact-match, it must be double-escaped. For example, for a rule matching on the exact phrase ‘Toys “R” Us’, including the double-quotes around R, the plain-text representation of this would look like the following:

  "Toys \"R\" Us"

Translating this to JSON format, you should use the following structure:

  {"value":"\"Toys \\\"R\\\" Us\""}

Rules with Tags

To include an optional Tag with your rule, as described above, simply include an additional “tag” field with the rule value:

 {"value":"\"social data\" @gnip","tag":"RULE-TAG-01"}

Formatting for API Requests

When adding or deleting rules from the PowerTrack stream via the API, multiple JSON formatted rules should be comma delimited, and wrapped in a JSON “rules” array, as shown below:

  {"rules":[{"value":"from:gnip"},{"value":"\social data\" @gnip","tag":"RULE-TAG-01"}]}

Restrictions 

  • 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. Please note that this list of stop words is subject to change, but the current stop words we use are: "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"

  • Rules cannot consist of only negated terms/operators. For example, ‘-cat -dog’ is not valid.

  • The entire string for a rule may be no more than 2048 characters, including all operators and spaces, with no single term exceeding 128 characters.

  • Negated ORs are not supported. Such as: apple OR -lang:en

  • Each rule may only have 1 tag. However, the tag is simply treated as a string, and may contain up to 255 characters, including - ; and other punctuation.

  • Geo rules with a radius greater than 25mi are not supported. Geo rules with a bounding box comprised of any edge greater than 25mi are not supported.

  • A rule keyword or input can start with either a digit (0-9) or any non-punctuation character. Current punctuation characters are defined as the ASCII characters below. Any keyword or input that needs to start with or contains punctuation must be “quoted”. A keyword can not have a colon or parentheses unless you quote it. Punctuation characters are not indexed and thus cannot be matched on, even if using the exact match operator.

! % & \ ' ( ) * + - . / ; < = > ? \\ , : # @ \t \r \n " [] _
and the Unicode ranges:
U+007B -- U+00BF
U+02B0 -- U+037F
U+2000 -- U+2BFF
U+FF00 -- U+FF03
U+FF05 -- U+FF0F
  • PowerTrack rules do not allow zero-width characters that exist in the General Punctuation block:
    http://www.fileformat.info/info/unicode/block/general_punctuation/list.htm
    Note that any characters in the above link that don’t have a visible symbol associated with them. The characters mentioned below change how text is formatted on the screen but not it’s intended meaning (for directional markers in particular, different keyboards will put different combinations of these characters in identical-looking text), and as such are not considered during text parsing.
    PowerTrack rules allow-but-ignore the following characters list:
    'U+202A', 'U+202B', // explicit directional embeddings
    'U+202D', 'U+202E', // explicit directional overrides
    'U+202C', // pop directional formatting
    'U+2066', 'U+2067', 'U+2068', // explicit directional overrides
    'U+2069', // pop directional isolate
    'U+200E', 'U+200F', 'U+061C' // implicit directional marks / arabic letter mark