Operator syntax

In order to create a rule, you can specify one or more of these operators.

  • Operators specified together will be interpreted as AND. For example, grumpy cat #meme will match Tweets containing the terms grumpycat and the hashtag #meme.
  • You can also match Tweets based on the presence of any of the operators by using the OR conjunction. For example, specifying grumpy OR cat OR #meme will match any Tweets containing at least one of grumpy, cat, or the hashtag #meme.
  • You can parentheses to group operators together. For example (grumpy cat) OR (#meme has:images) will return either Tweets containing the terms grumpy and cat, or Tweets with images containing the hashtag #meme.
  • Prepend a dash to a keyword to negate it (NOT). For example, -grumpy cat #meme will match Tweets containing the hashtag #meme and the term cat, but only if they do not contain the term grumpy. You can also negate operators grouped using parenthesis.
     

All operators can be negated, except for sample. Negated operators cannot be used alone.
 

Standalone operators

These operators can be used alone or together with any other operators (including those from the Entity operators list).

 Operator

Description

keyword

Matches a keyword within the body of a Tweet. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Tweet body. Tokenization splits words based on punctuation, symbols, and Unicode basic plane separator characters.

For example, a Tweet 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 wrap your keyword in double quotes.

emoji

Matches an emoji within the body of a Tweet. Similar to a keyword, emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Tweet body.

Note that if an emoji has a variant, you must wrap it double quotes to add to a rule.

"exact phrase match"

Matches the exact phrase within the body of a Tweet.

#

Matches any Tweet containing a recognized hashtag, if the hashtag is a recognized entity in a Tweet.

This operator performs an exact match, NOT a tokenized match, meaning the rule #thanku will match posts with the exact hashtag #thanku, but not those with the hashtag #thankunext.

@

Matches any Tweet that mentions the given username, if the username is a recognized entity (including  the @ character).

from:

Matches any Tweet from a specific user.

The value can be either the username (excluding the @ character) or the user’s numeric user ID.

to:

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

The value can be either the username (excluding the @ character) or the user’s numeric user ID.

url:

Performs a tokenized match on any validly-formatted URL of a Tweet.

This operator can matches on the contents of both the url or expanded_url. For example, a Tweet containing You should check out Twitter Developer Labs: https://t.co/c0A36SWil4 (with the short URL redirecting to https://developer.twitter.com) will match both the following rules:

  • from:TwitterDev url:"https://developer.twitter.com" (because it will match the contents of entities.urls.expanded_url)
  • from:TwitterDev url:"https://t.co" (because it will match the contents of entities.urls.url)

Tokens and phrases containing punctuation or special characters should be double-quoted (e.g. url:"/developer"). Similarly, to match on a specific protocol, enclose in double-quotes (e.g. url:"https://developer.twitter.com").

bio:

Matches Tweets from authors with the specified keyword or phrase within the user bio of a Tweet. This is a tokenized match within the contents of the user's description field.

bio_name:

Matches Tweets from authors with the specified keyword or phrase in their profile's name. This is a tokenized match within the contents of a user’s name field.

bio_location:

Matches Tweets from authors whose location contains the specified keyword or phrase. This is a tokenized match within the contents of a user’s location field (if present).

retweets_of:

Matches Tweets that are Retweets of the specified user. The value can be either the username (excluding the @ character) or the user’s numeric user ID.

 

 

place:

Matches Tweets tagged with the specified location. Multi-word place names (e.g. “New York City”, “New Delhi”) should be enclosed in quotes. This operator will match only on original Tweets (this is because Retweets do not contain any place information), and only when a location has been specified in the Tweet.

place_country:

Matches Tweets where its location's country code matches the given ISO alpha-2 character code. This operator will match only on original Tweets (this is because Retweets do not contain any place information), and only when a location has been specified in the Tweet.

point_radius:[lon lat radius]

Matches against the exact location (x,y) of the Tweet (if present).

  • 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 within brackets, space delimited.

This operator will match only on original Tweets (this is because Retweets do not contain any place information), and only when a location has been specified in the Tweet.

bounding_box:[west_long south_lat east_long north_lat]

Matches against the exact location (long, lat) of the Tweet (if present).

  • 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 25 miles.
  • Longitude is in the range of ±180.
  • Latitude is in the range of ±90.
  • All coordinates are in decimal degrees.
  • All coordinates are contained within brackets, and are separated by a space.

This operator will match only on original Tweets (this is because Retweets do not contain any place information), and only when a location has been specified in the Tweet.

 

Entity operators

The following operators cannot be used alone in a rule; they can only be used together with at least one operator from the Standalone operators list.

 Operator

Description

has:links

This operator matches Tweets which contain links in the Tweet body.

has:mentions

Matches Tweets that mention another Twitter user.

has:media

Matches Tweets that contain a media URL recognized by Twitter.

has:images

Matches Tweets that contain a recognized URL to an image.

has:videos

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

has:hashtags

Matches Tweets that contain at least one hashtag.

 

has:geo

Matches Tweets that containing geolocation (if the user added location information to a Tweet).

is:retweet

Delivers only explicit Retweets that match the rest of the specified rule. This operator looks only for true Retweets (for example, those generated using the Retweet button). Tweets with comments (also known as Quoted Tweets) and modified Tweets will not be matched by this operator.

 

is:quote

Delivers only explicit Retweets with comments (also known as Quoted Tweets) that match the rest of the specified rule.

is:verified

Deliver only Tweets whose authors are verified by Twitter.

sample:

Returns a random percent sample of Tweets that match a rule rather than the entire set of Tweets. The percent value must be represented by an integer between 1 and 100 (for example, sample:10 will return a random 10% sample).

This operator first reduces the scope of the stream to the percentage you specified, then the rule/filter is applied to that sampled subset. In other words, if you are using, for example, sample:10, each Tweet will have a 10% chance of being in the sample.

This operator applies to the entire rule and requires all OR'd terms to be grouped.

 

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 Tweet 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 currently supported languages and their corresponding BCP 47 language identifier:

am Amharic

hu Hungarian

pt Portuguese

ar Arabic

is Icelandic

ro Romanian

hy Armenian

in Indonesian

ru Russian

bn Bengali

it Italian

sr Serbian

bg Bulgarian

ja Japanese

sd Sindhi

my Burmese

kn Kannada

si Sinhala

zh Chinese

km Khmer

sk Slovak

cs Czech

ko Korean

sl Slovenian

da Danish

lo Lao

ckb Sorani Kurdish

nl Dutch

lv Latvian

es Spanish

en English

lt Lithuanian

sv Swedish

et Estonian

ml Malayalam

tl Tagalog

fi Finnish

dv Maldivian

ta Tamil

fr French

mr Marathi

te Telugu

ka Georgian

ne Nepali

th Thai

de German

no Norwegian

bo Tibetan

el Greek

or Oriya

tr Turkish

gu Gujarati

pa Panjabi

uk Ukrainian

ht Haitian

ps Pashto

ur Urdu

iw Hebrew

fa Persian

ug Uyghur

hi Hindi

pl Polish

vi Vietnamese

cy Welsh