Using the Twitter Search API

The Twitter Search API is part of our REST API v1.1. It allows queries against the real-time index of recent Tweets. There are a number of important things to know before using the Search API which are explained below.

• The Search API is not complete index of all Tweets, but instead an index of recent Tweets. At the moment that index includes between 6-9 days of Tweets.
• You cannot use the Search API to find Tweets older than about a week.
• 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."}
• Search is focused in relevance and not completeness. This means that some Tweets and users may be missing from search results. If you want to match for completeness you should consider using the Streaming API instead.
• The near operator cannot be used by the Search API. Instead you should use the geocode parameter.
• Queries are limited to 1,000 characters in length, including any operators.
• When performing geo-based searches with a radius, only 1,000 distinct subregions will be considered when evaluating the query.
• In API v1.1, the Search API requires some form of authentication -- either OAuth 1.0A or app-only auth

• API v1.1's Search methods return tweets in the same format as other REST API methods.
• Classic pagination is not offered in API v1.1. You must use since_id and max_id to naviagte through results.
• The user IDs returned in the Search API now match the user IDs utilized in the Twitter REST & Streaming APIs. You no longer need to maintain a mapping of "search IDs" and "real IDs."
• In v1, use include_entities=true to have Tweet Entities included for mentions, links, media, and hashtags.
• in_reply_to_status_id and in_reply_to_status_id_str are now included with @replies, allowing you to know the replied-to status ID, which can be looked up using GET statuses/show/:id.

Rate Limiting on API v1.1's search/tweets

The GET search/tweets is part of the Twitter REST API 1.1 and is rate limited similarly to other v1.1 methods. See REST API Rate Limiting in v1.1 for information on that model. At this time, users represented by access tokens can make 180 requests/queries per 15 minutes. Using application-only auth, an application can make 450 queries/requests per 15 minutes on its own behalf without a user context.

Rate Limiting on deprecated search.twitter.com

The Rate Limits for the legacy Search API are not the same as for the REST API. When using the Search API you are not restricted by a certain number of API requests per hour, but instead by the complexity and frequency.

As requests to the Search API are anonymous, the rate limit is measured against the requesting client IP.

To prevent abuse the rate limit for Search is not published. If you are rate limited, the Search API will respond with an HTTP 420 Error. {"error":"You have been rate limited. Enhance your calm."}.

• Ensure all parameters are properly URL encoded.
• Include a since_id when asking for Tweets. since_id should be set to the value of the last Tweet you received or the max_id from the Search API response. If the since_id you provide is older than the index allows, it will be updated to the oldest since_id available.
• Include a meaningful and unique User Agent string when using this method. It helps identify your traffic when you use shared hosting and can be used by our support team to triage any issues you report.
• Limit your searches to 10 keywords and operators.

If you are not sure how to construct a query for the Search API you can:

1. Run your search on twitter.com/search.
2. Copy the URL. For example: https://twitter.com/#!/search/%40twitterapi
3. Replace https://twitter.com/#!/search/ with https://api.twitter.com/1.1/search/tweets.json?q=. For example: https://api.twitter.com/1.1/search/tweets.json?q=%40twitterapi

Please note that the Search interface presented on twitter.com will not completely match the results you'll get back from the unauthenticated Search API.

In addition to the parameters listed in the Search API documentation, there are a number of operators you can use to modify the behavior of query.

since and until

• do not support the negation (-) operator.
• should be entered in the format year-month-day or yyyy-mm-dd.
• are assumed to be from/to 00:00 UTC.
• cannot be set into the future. If until is in the future you will receive an HTTP 403 error with the message: {"error":"You cannot use an 'until:' date in the future"}. If since is in the future you will receive an HTTP 403 error with the message: {"error":"since_id too recent, poll less frequently"}.

source

• can only be combined with a keyword parameter. If you do not include a keyword you will receive an HTTP 403 error with the message: {"error":"You must enter a query."}.
• supports multi-word sources by using _ instead of spaces. For example, the source "Tweet Button" should be entered as source: tweet_button

place

• supports many data set aliases. Finding Tweets about Places has the complete list of aliases.

result_type

Results will sometimes contain a result_type field into the metadata with a value of either "recent" or "popular". Popular results are derived by an algorithm that Twitter computes, and up to 3 will appear in the default mixed mode that the Search API operates under. Popular results include another node in the metadata called recent_retweets. This field indicates how many retweets the Tweet has had.

The Search API has been built up over time and some of it's original behaviors are maintained. This behaviors can lead to confusion if you don't expect them.

Location data is only included if the query includes the geocode parameter, and the user Tweeted with Geo information. When conduction Geo searches, the Search API will:

• Attempt to find Tweets which have a place or lat/long within the queried geocode.
• Attempt to find Tweets created by users whose profile location can be reverse geocoded into a lat/long within the queried geocode.

This means it is possible to receive Tweets which do not include a latitude or longitude.

If a Tweet contains a URL, the Search API will match to the fully expanded version of the URL. This means a keyword search may return results which appear to not include the keywords you provide. Instead, the keyword is in the expanded version of the URL in the Tweet.

The user_ids in the Search API responses do not match those for Twitter.com by default. Use the with_twitter_user_id=true parameter to return IDs which match Twitter.com.