Please note:
We graduated the Labs version of filtered stream into Twitter API v2: Early Access and retired it in October 2020.
Learn more about the new filtered stream, and review our migration resources to update to The New Twitter API.
Building queries for the filtered stream endpoints
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 grumpy, cat 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.
Please note the following important details about building queries:
- Queries can be 512 characters long.
- All operators can be negated except for
sample. Negated operators cannot be used alone. - Do not negate a set of operators grouped together in a set of parentheses. Instead, negate each individual operator.
For example, Instead of using-(grumpy OR cat OR meme), we suggest that you use-grumpy -cat -meme
To learn more about building queries for the recent search endpoint, please review our tutorial on translating plain language to queries.
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:
Tokens and phrases containing punctuation or special characters should be double-quoted (for example, url:"/developer"). Similarly, to match on a specific protocol, enclose in double-quotes (for example, 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. |
Matches tweets with a specific domain id and/or domain id, enitity id pair where * represents a wildcard. To learn more about this operator, please visit our page on Annotations. "context": domain_id.entity_id || *.entity_id || domain_id.* Examples:
|
|
| entity | Matches tweets with a specific entity string value. To learn more about this operator, please visit our page on Annotations. "entity":"string declaration of entity/place" Examples:
|
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).
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).
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:
|
