Premium Search API operators

Below are the operators available with the premium Search APIs. 

 

Operator

Description
keyword

Matches a keyword within the text body or URL of a Tweet. Keywords must start with either a digit (0-9) or any non-puncutation character.  Keyword matching is a tokenized match, meaning that your keyword will be matched against the tokenized text of the Tweet body – tokenization is based on punctuation, symbol, and separator Unicode basic plane characters.  To match strings containing punctuation (for example, coca-cola), symbol, or separator characters, you must use a quoted "exact phrase match".

Example:
(social OR pizza OR wildfire) -planet

Note: With the Search API, accented and special characters are normalized to standard latin characters, which can change meanings in foreign languages or return unexpected results:
For example, "músic" will match “music” and vice versa. 
For example, common phrases like "Feliz Año Nuevo!" in Spanish, would be indexed as "Feliz Ano Nuevo", which changes the meaning of the phrase.

Note: This operator will match on both URLs and unwound URLs within a Tweet.

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.

Example:
(🍕 OR 💜 OR 🐢) -🤖
"exact phrase match"

Matches an exact phrase within the body of a Tweet.

Example:
("social media" OR "developer.twitter.com" OR "wildfire911" OR "coca-cola") -"planet earth"

Note: In 30 Day Search and Full Archive Search, punctuation is not tokenized and is instead treated as whitespace. 
For example, quoted “#hashtag” will match “hashtag” but not #hashtag (use the hashtag # operator without quotes to match on actual hashtags)
For example, quoted “$cashtag” will match “cashtag” but not $cashtag (use the cashtag $ operator without quotes to match on actual cashtags)

Note: This operator will match on both URLs and unwound URLs within a Tweet.

#

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”

Example:
(#social OR #pizza OR #2016election) -#planet

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.

Example:
(@twitterdev OR @twitterapi OR @twittereng) -@jack

Note: that the mention operator relies on Twitter’s entity extraction to match mentioned users, rather than extracting the mention from the body itself. See HERE for more information on Twitter Entities JSON attributes.

from:

Matches any Tweet from a specific user.

Example:
(from:2244994945 OR from:twitterapi OR from:twittereng) -from:jack

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

to:

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

Example:
(to:2244994945 OR to:twitterapi OR to:twittereng) -to:jack

The value must be the user’s numeric Account ID or username (excluding the @ character). See HERE  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).

Example:
@twitterdev url:"developer.twitter.com"

Note: When using PowerTrack or Historical PowerTrack, this operator will match on URLs contained within the original Tweet of a Quote Tweet. For example, if your rule includes url:"developer.twitter.com", and a Tweet contains that URL, any Quote Tweets of that Tweet will be included in the results. This is not the case when using the Search API. 
retweets_of:
Matches Tweets that are Retweets of a specified user. Accepts both usernames and numeric Twitter Account IDs (NOT Tweet status IDs).

Example:
(retweets_of:2244994945 OR retweets_of:twitterapi OR retweets_of:twittereng) -retweets_of:jack

See HERE for looking up numeric Twitter Account IDs.
source: Matches any Tweet generated by the given source application. The value must be either the name of the application, or the application’s URL.  Cannot be used alone.

Example:
#happybirthday source:"Twitter for iPhone"
"This is a test Tweet from my TestingApp" source:MyTestAppName

Note: As a Twitter app developer, Tweets created programattically by your application will have the source of your application Name and Website URL set in your app settings. The source operator seraches on the Tweet source attribute.  See HERE for more information on Twitter Entities JSON attributes.
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. This operator is not recommended to be used alone, matching volume will be very high. 

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

Amharic: am German: de Malayalam: ml Slovak: sk
Arabic: ar Greek: el Maldivian: dv Slovenian: sl
Armenian: hy Gujarati: gu Marathi: mr Sorani Kurdish: ckb
Basque: eu Haitian Creole: ht Nepali: ne Spanish: es
Bengali: bn Hebrew: iw Norwegian: no Swedish: sv
Bosnian: bs Hindi: hi Oriya: or Tagalog: tl
Bulgarian: bg Latinized Hindi: hi-Latn Panjabi: pa Tamil: ta
Burmese: my Hungarian: hu Pashto: ps Telugu: te
Croatian: hr Icelandic: is Persian: fa Thai: th
Catalan: ca Indonesian: in Polish: pl Tibetan: bo
Czech: cs Italian: it Portuguese: pt Traditional Chinese: zh-TW
Danish: da Japanese: ja Romanian: ro Turkish: tr
Dutch: nl Kannada: kn Russian: ru Ukrainian: uk
English: en Khmer: km Serbian: sr Urdu: ur
Estonian: et Korean: ko Simplified Chinese: zh-CN Uyghur: ug
Finnish: fi Lao: lo Sindhi: sd Vietnamese: vi
French: fr Latvian: lv Sinhala: si Welsh: cy
Georgian: ka Lithuanian: lt  

Example:

(@twitterdev OR to:twitterdev) lang:es

Note: The language operator matches on the specific Tweet language determined by Twitter and set as the lang Tweet attribute.  See HERE for more information on Twitter Entities JSON attributes.  If no language classification can be made for a Tweet, the Tweet lang will be set as ‘und’ (for undefined).

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.

Example:
(place:London OR place:"Great Britain") -place:USA
place:fd70c22040963ac7

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

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Tweet. It will also not match on places attached to the original Tweet of a Quote Tweet.

place_country:

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

Example:
place_country:GB OR place_country:AU OR place_country:CA

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

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Tweet. It will also not match on places attached to the original Tweet of a Quote Tweet.

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.

  • Radius must be less than 25mi.
  • Units of radius supported are miles (mi) and kilometers (km).
  • 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.

Example:
point_radius:[-105.27346517 40.01924738 0.5mi]

point_radius:[2.355128 48.861118 16km]

 

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Tweet. It will also not match on places attached to the original Tweet of a Quote Tweet.

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.

Example:
bounding_box:[-105.301758 39.964069 -105.178505 40.09455]

Note: This operator will not match on Retweets, since Retweet's places are attached to the original Tweet. It will also not match on places attached to the original Tweet of a Quote Tweet.

profile_country:

Only available to paid premium subscriptions.

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:

Only available to paid premium subscriptions.

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:

Only available to paid premium subscriptions.

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.

profile_subregion:

Only available to paid premium subscriptions.

Matches on the “subRegion” field from the “address” object in the Profile Geo enrichment. In addition to targeting specific counties, these operators can be helpful to filter on a metro area without defining filters for every city and town within the region.

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.

has:geo

Only available to paid premium subscriptions.

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: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

has:profile_geo
Only available to paid premium subscriptions.

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

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

has:links

This operator matches Tweets that contain a link or referenced media in the "text" object of the payload.

Note: In addition to this operator matching Tweets with a link in their text, it also matches Tweets with media (image, video, gif), and Quote Tweets.

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

is:retweet

Only available to paid premium subscriptions.

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. Quoted Tweets which do not use Twitter’s Retweet functionality will not be matched by this operator.

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

is:reply
Only available to paid premium subscriptions.

Delivers only explicit replies that match a rule. Can also be negated to exclude replies that match a rule from delivery (see example request below).

Example:
#contest123 is:reply
@twitterdev -is:reply

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

Note: When used with enterprise PowerTrack, this operator matches on replies to an original Tweet, replies in quoted Tweets and replies in Retweets. When used with the Search API, this operator only matches on replies to an original Tweet and excludes replies in quoted Tweets and replies in Retweets.

is:quote

Delivers only Quote Tweets, or Tweets that reference another Tweet, as identified by the "is_quote_status":true in Tweet payloads. Can also be negated to exclude Quote Tweets. 

Example:
@twitterdev is:quote

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

is:verified
Only available to paid premium subscriptions.

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

Example:
@twitterdev is:verified

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

has:mentions
Matches Tweets that mention another Twitter user.

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

has:hashtags
Only available to paid premium subscriptions.

Matches Tweets that contain a hashtag.

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

has:media
Matches Tweets that contain a media url classified by Twitter. For example, pic.twitter.com.

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

has:images
Matches Tweets that contain a media url classified by Twitter. For example, pic.twitter.com.

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

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

Note: When using the Search API, this operator must be used in conjunction with other operators that don't include is: or has:. You can include this as a standalone operator when using enterprise PowerTrack and Historical PowerTrack.

Was this document helpful?
Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?
Thank you for the feedback. Your comments will help us improve our documents in the future.