Building standard search queries

This section describes the filtering tools available to the standard v1.1 search endpoint.

We also have rules and filtering sections for premium v1.1 and enterprise, as well as the following pages describing filtering functionality for our new Twitter API v2 endpoints:

How to build a standard query

Standard

The best way to build a standard query and test if it’s valid and will return matched Tweets is to first try it at twitter.com/search. As you get a satisfactory result set, the URL loaded in the browser will contain the proper query syntax that can be reused in the standard search API endpoint. Here’s an example:

  1. We want to search for Tweets referencing @TwitterDev account. First, we run the search on twitter.com/search
  2. Check and copy the URL loaded. In this case, we got: https://twitter.com/search?q=%40twitterdev
  3. Replace https://twitter.com/search with https://api.x.com/1.1/search/tweets.json and you will get: https://api.x.com/1.1/search/tweets.json?q=%40twitterdev
  4. Run a Twurl command to execute the search.

Please note that the API requires that the request be authenticated (check Authentication & Authorization documentation for more details on this). Note that the standard search API only serves data from the last week. If you need historical data odler than seven days, check out the premium and enterprise search APIs.

 

Best practices

  • Ensure all parameters are properly URL encoded.
  • Limit your searches to 10 keywords and operators.
  • Queries can be limited due to complexity. If this happens, the Search API will respond with the error: {"error":"Sorry, your query is too complex. Please reduce complexity and try again."}.
  • The Search API is not complete index of all Tweets, but instead an index of recent Tweets. The index includes between 6-9 days of Tweets.

 

Example searches

When you are following an event that’s currently happening, you would be interested in search for recent Tweets using the event hashtag:

 

When you want to know what Tweets are coming from a specific location, with a specific language:

  • You want: all recent Tweets in Portuguese, near Maracanã soccer stadium in Rio de Janeiro
  • Your search URL is: https://api.x.com/1.1/search/tweets.json?q=&geocode=-22.912214,-43.230182,1km&lang=pt&result_type=recent

 

When you want the most popular tweets of a specific user using a hashtag: