Search Tweets

Premium search operators

Below is a list of all operators supported in Twitter's premium and enterprise search APIs:

  • Premium Search Tweets API: 30-day endpoint
  • Premium Search Tweets API: Full-archive endpoint
  • Enterprise 30-day search API
  • Enterprise Full-archive search API

For a side-by-side comparison of available operators by product see HERE.

 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 is based on punctuation, symbol, and separator Unicode basic plane 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 use a quoted exact match as described below.

Note that with Search APIs, accented and special characters are normalized to standard latin characters, which can change meanings in foreign languages or return unexpected results:

e.g. "músic" will match “music” and vice versa. 

e.g. common phrases like "Feliz Año Nuevo!" in Spanish, would be indexed as "Feliz Ano Nuevo", which changes the meaning of the phrase.

emoji
Matches an emoji within the body of a Tweet. Emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Tweet body – tokenization is based on punctuation, symbol/emoji, and separator Unicode basic plane characters. For example, a Tweet with the text “I like 🍕” would be split into the following tokens: I, like, 🍕. These tokens would then be compared to the emoji used in your rule. Note that if an emoji has a variant, you must use “quotations” to add to a rule.
"exact phrase match"

Matches an exact phrase within the body of a Tweet.

Note: 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. 

e.g. "Love Snow" will match "#love #snow"

e.g. "#Love #Snow" will match "love snow"

"keyword1 keyword2"~N

Commonly referred to as a proximity operator, this matches a Tweet 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.

Note that this operator is only available in the enterprise search APIs.

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.

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.

url:
Performs a tokenized (keyword/phrase) match on the expanded URLs of a tweet (similar to url_contains). Tokens and phrases containing punctuation or special characters should be double-quoted. E.g. url:"/developer". While generally not recommended, if you want to match on a specific protocol, enclose in double-quotes: url:"https://developer.twitter.com".
#

Matches any Tweet 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. See HERE for more information on Twitter Entities JSON attributes.

@

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.

$

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. See HERE for more information on Twitter Entities JSON attributes.

Note that this operator is only available in the enterprise search APIs.

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.
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 current supported languages and their corresponding BCP 47 language indentifier:

Amharic - am             Hungarian – hu        Portuguese - pt

Arabic - ar                  Icelandic - is               Romanian - ro

Armenian - hy           Indonesian - in          Russian - ru

Bengali - bn               Italian - it                    Serbian - sr

Bulgarian - bg            Japanese - ja              Sindhi - sd

Burmese – my           Kannada - kn             Sinhala - si

Chinese - zh               Khmer - km               Slovak - sk

Czech - cs                   Korean - ko                Slovenian - sl

Danish - da                 Lao - lo                       Sorani Kurdish - ckb

Dutch - nl                   Latvian - lv                 Spanish - es

English - en                Lithuanian - lt            Swedish - sv

Estonian - et              Malayalam - ml          Tagalog - tl

Finnish - fi                  Maldivian - dv            Tamil - ta

French - fr                  Marathi - mr               Telugu - te

Georgian - ka            Nepali - ne                  Thai - th

German - de              Norwegian - no         Tibetan - bo

Greek - el                   Oriya - or                    Turkish - tr

Gujarati - gu              Panjabi - pa                Ukrainian - uk

Haitian - ht                Pashto - ps                  Urdu - ur

Hebrew - iw              Persian - fa                  Uyghur - ug

Hindi - hi                   Polish - pl                    Vietnamese - vi

                                                                        Welsh - cy

 

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.

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

point_radius:[lon lat radius]

Matches against the Exact Location (x,y) of the Tweet 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.
bounding_box:[west_long south_lat east_long north_lat]

Matches against the Exact Location (long, lat) of the Tweet 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.
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.

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.

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.

 

  NOTE:  All ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @TwitterDev has:links)
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.

has:profile_geo
Matches Tweets that have any Profile Geo metadata, regardless of the actual value.

has:links

This operators matches Tweets which contain links in the message body.
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.

is:verified
Deliver only Tweets where the author is “verified” by Twitter. Can also be negated to exclude Tweets where the author is verified.
has:mentions
Matches Tweets that mention another Twitter user.
has:hashtags
Matches Tweets that contain a hashtag.
has:media
Matches Tweets that contain a media url classified by Twitter, e.g. pic.twitter.com.
has:images
Matches Tweets that contain a media url classified by Twitter, e.g. pic.twitter.com.
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.
has:symbols
Matches Tweets that contain a cashtag symbol (with a leading ‘$’ character, e.g. $tag).  Note that this operator is only available in the enterprise search APIs.