Rules and filtering
Basic query operators
The query can have operators that modify its behavior. the available operators are:
|watching now||containing both “watching” and “now”. This is the default operator.|
|“happy hour”||containing the exact phrase “happy hour”.|
|love OR hate||containing either “love” or “hate” (or both).|
|beer -root||containing “beer” but not “root”.|
|#haiku||containing the hashtag “haiku”.|
|from:interior||sent from Twitter account “interior”.|
|list:NASA/astronauts-in-space-now||sent from a Twitter account in the NASA list astronauts-in-space-now|
|to:NASA||a Tweet authored in reply to Twitter account “NASA”.|
|@NASA||mentioning Twitter account “NASA”.|
|politics filter:safe||containing “politics” with Tweets marked as potentially sensitive removed.|
|puppy filter:media||containing “puppy” and an image or video.|
|puppy -filter:retweets||containing “puppy”, filtering out retweets|
|puppy filter:native_video||containing “puppy” and an uploaded video, Amplify video, Periscope, or Vine.|
|puppy filter:periscope||containing “puppy” and a Periscope video URL.|
|puppy filter:vine||containing “puppy” and a Vine.|
|puppy filter:images||containing “puppy” and links identified as photos, including third parties such as Instagram.|
|puppy filter:twimg||containing “puppy” and a pic.twitter.com link representing one or more photos.|
|hilarious filter:links||containing “hilarious” and linking to URL.|
|puppy url:amazon||containing “puppy” and a URL with the word “amazon” anywhere within it.|
|superhero since:2015-12-21||containing “superhero” and sent since date “2015-12-21” (year-month-day).|
|puppy until:2015-12-21||containing “puppy” and sent before the date “2015-12-21”.|
|movie -scary :)||containing “movie”, but not “scary”, and with a positive attitude.|
|flight :(||containing “flight” and with a negative attitude.|
|traffic ?||containing “traffic” and asking a question.|
Please, make sure to URL encode these queries before making the request. There are several online tools to help you to do that, or you can search at twitter.com/search and copy the encoded URL from the browser’s address bar. The table below shows some example mappings from search queries to URL encoded queries:
|Search query||URL encoded query|
|“happy hour” :)||%22happy%20hour%22%20%3A%29|
Note that the space character can be represented by “%20” or “+” sign.
There is a set of additional parameters that allows a better control of the search results. The GET search/tweets documentation has detailed information about the usage of the parameters, this section will only give a brief description of their capabilities:
- Result Type: just like twitter.com/search results, the result_type parameter selects whether the result set will be represented by recent or popular Tweets, or even a mix of both.
- Geolocalization: the search operator “near” isn’t available in the API, but there is a more precise way to restrict your query by a given location using the geocode parameter specified with the template “latitude,longitude,radius”, for example, “37.781157,-122.398720,1mi”. When conducting geo searches, the search API will first attempt to find Tweets which have lat/long within the queried geocode, and in case of not having success, it will attempt to find Tweets created by users whose profile location can be reverse geocoded into a lat/long within the queried geocode, meaning that is possible to receive Tweets which do not include lat/long information.
- Language: the lang parameter restricts Tweets to the given language.
- Iterating in a result set: parameters such count, until, since_id, max_id control iteration through search results, since it could be a large set of Tweets. The Working with Timelines documentation is a rich and illustrative tutorial to learn how to use these parameters to achieve the best efficiency and reliability when processing result sets.