Search API Documentation

Page history last edited by Matt Sanford 10 hours, 2 minutes ago

  1. Introduction
  2. Formats
  3. Methods
    1. Search
    2. Trends
  4. Terms of Service

Introduction

You can use our API to integrate Twitter search results with your own apps, clients, and readers. Check out these great examples of apps utilizing our API.  We currently serve two flavors of our Search API: Atom and JSON.  

In the near future, the Search API will be updated to more closely reflect the Twitter REST API, and we'll support XML responses as well.

Formats

 

Atom

You can grab the search results for any query as a standard Atom feed. For example, this is the Atom feed for the query twitter.  For example, to request search results in Atom, append your URL-encoded query as a parameter to the search method and specify the Atom format:

 

http://search.twitter.com/search.atom?q=<query> 

 

JSON

You can also request search results in JSON format. For example, this is the JSON response for the query twitter. Note that the tweet content is HTML-encoded.  To request search results in JSON, append your URL-encoded query as a parameter to the search method and specify the JSON format:

 

http://search.twitter.com/search.json?q=<query>

 

Requests for JSON support an additional URL parameter:

 

 

Methods

 

Search

Returns tweets that match a specified query.  You can use a variety of search operators in your query. Here are a few examples:

 

 

Alternatively, if you perform a search on our site, you can click the Feed for this query link in the sidebar to obtain its Atom feed URL. You can also use the advanced search page to easily incorporate any search operators.

 

The search method also supports the following optional URL parameters:

  • lang: restricts tweets to the given language, given by an ISO 639-1 code. Ex: http://search.twitter.com/search.atom?lang=en&q=devo
  • rpp: the number of tweets to return per page, up to a max of 100. Ex: http://search.twitter.com/search.atom?lang=en&q=devo&rpp=15
  • page: the page number (starting at 1) to return, up to a max of roughly 1500 results (based on rpp * page)
  • since_id: returns tweets with status ids greater than the given id.
  • geocode: returns tweets by users located within a given radius of the given latitude/longitude, where the user's location is taken from their Twitter profile. The parameter value is specified by "latitide,longitude,radius", where radius units must be specified as either "mi" (miles) or "km" (kilometers). Ex: http://search.twitter.com/search.atom?geocode=40.757929%2C-73.985506%2C25km. Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly.
  • show_user: when "true", adds "<user>:" to the beginning of the tweet. This is useful for readers that do not display Atom's author field. The default is "false".

 

There are a few restrictions to the search method:

  • We only provide access to data for about four months, older data may not be searchable.
  • As noted above, the near: operator does not work via the API and instead must be replaced by the geocode parameter.
  • Query length is limited to 140 characters

 

Trends

Returns the top ten queries that are currently trending on Twitter.  The response includes the time of the request, the name of each trending topic, and the url to the Twitter Search results page for that topic.  Currently, the only supported format for this method is JSON.  The callback parameter is supported, however.

 

The request URL for this method is:

 

http://search.twitter.com/trends.json

 

Terms of Service

We delight in all manifestations of our API. Only a few guidelines:

  1. Set the user agent of the request to something meaningful. This helps us answer any questions about your use of the API.
  2. If possible, use the since_id request parameter described above to only retrieve new tweets.
  3. Please give us a nod in your app, perhaps by including one of these stylish "Powered by Twitter" badges:

     

    Powered-by-twitter-sig Powered-by-twitter-badge

  4. We do not rate limit the search API under ordinary circumstances, however we have put measures in place to limit the abuse of our API. If you find yourself encountering these limits, please contact us and describe your app's requirements.
  5. Finally, let us know what you're up to so we can check it out!

Comments (0)

You don't have permission to comment on this page.

Printable version
 
Anonymous Create an account or Log in