<< Back to Twitter API Documentation

 

search

Returns tweets that match a specified query.

 

URL:

http://search.twitter.com/search.format

 

Formats: 

json, atom 

 

HTTP Method:

GET

 

Requires Authentication (about authentication):

false

 

API rate limited (about rate limiting):

1 call per request 

 

Parameters:

• callback: Optional. Only available for JSON format. If supplied, the response will use the JSONP format with a callback of the given name.
  • Example: http://search.twitter.com/search.json?callback=foo&q=twitter 

• lang: Optional: Restricts tweets to the given language, given by an ISO 639-1 code.
  • Example: http://search.twitter.com/search.atom?lang=en&q=devo
• rpp: Optional. The number of tweets to return per page, up to a max of 100.
  • Example: http://search.twitter.com/search.atom?q=devo&rpp=15
• page: Optional. The page number (starting at 1) to return, up to a max of roughly 1500 results (based on rpp * page)
  • Example: http://search.twitter.com/search.atom?q=devo&rpp=15&page=2
• since_id: Optional. Returns tweets with status ids greater than the given id.
  • Example: http://search.twitter.com/search.atom?q=twitter&since_id=1520639490
• geocode: Optional. 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). 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.
  • Example: http://search.twitter.com/search.atom?geocode=40.757929%2C-73.985506%2C25km
• show_user: Optional. When true, prepends "<user>:" to the beginning of the tweet. This is useful for readers that do not display Atom's author field. The default is false.
  • Example: http://search.twitter.com/search.atom?q=twitterapi&show_user=true

 

Usage Notes:

• Query strings should be URL encoded.
• Queries are limited 140 URL encoded characters.
• If you are having trouble constructing your query, use the advanced search form to construct your search, then add the format. For example http://search.twitter.com/search?q=twitter would become http://search.twitter.com/search.json?q=twitter

 

Example queries:

• Containing a word: http://search.twitter.com/search.atom?q=twitter
• From a user: http://search.twitter.com/search.atom?q=from%3Aal3x
• Replying to a user (tweet starts with @mzsanford): http://search.twitter.com/search.atom?q=to%3Amzsanford
• Mentioning a user (tweet contains @biz): http://search.twitter.com/search.atom?q=%40biz
• Containing a hashtag (up to 16 characters): http://search.twitter.com/search.atom?q=%23haiku
• Combine any of the operators together: http://search.twitter.com/search.atom?phrase=happy+hour&until=2009-03-24
• Originating from an application: http://search.twitter.com/search.atom?q=landing+source:tweetie

 

Search operators:

     Most search operators can be used with API queries.

 

Boolean operators:

• OR to combine queries:
  • Mentioning @twitterapi OR @twitter: http://search.twitter.com/search.atom?q=%40twitterapi+OR+%40twitter
• Negation: place - infront of the operator.
  • Referencing a user but not from that user: http://search.twitter.com/search.atom?q=dougw+-from%3Adougw

 

Operator Limits:

• since: and until operators:
  • since: will return a HTTP 404 if it is too old
  • until: cannot be in the future
  • since: and until: do not accept the negation (-) operation
• filter:links operator:
  • results are limited to 7 days
• source: operator:
  • results are limited to 7 days
  • queries must contain at least one keyword parameter with the source: operator
• lang= operator:
  • results are limited to 7 days
• location operator:
  • results are limited to 7 days
• near:
  • cannot be used in API search

 

Response (about return values):

Warning: The user ids in the Search API are different from those in the REST API (about the two APIs). This defect is being tracked by Issue 214. This means that the to_user_id and from_user_id field vary from the actualy user id on Twitter.com. Applications will have to perform a screen name-based lookup with the users/show method to get the correct user id if necessary.

 

          JSON example (truncated):

{"results":

     {"text":"@twitterapi  http:\/\/tinyurl.com\/ctrefg",

     "to_user_id":396524,

     "to_user":"TwitterAPI",

     "from_user":"jkoum",

     "id":1478555574,   

     "from_user_id":1833773,

     "iso_language_code":"nl",

     "source":"<a href="http:\/\/twitter.com\/">web<\/a>",

     "profile_image_url":"http:\/\/s3.amazonaws.com\/twitter_production\/profile_images\/118412707\/2522215727_a5f07da155_b_normal.jpg",

     "created_at":"Wed, 08 Apr 2009 19:22:10 +0000"}],

     "since_id":0,

     "max_id":1480307926,

     "refresh_url":"?since_id=1480307926&q=%40twitterapi",

     "results_per_page":15,

     "next_page":"?page=2&max_id=1480307926&q=%40twitterapi",

     "completed_in":0.031704,

     "page":1,

     "query":"%40twitterapi"},

     ... truncated ...

}

  

Usage examples: 

cURL (about cURL):

curl http://search.twitter.com/search.json?q=%40twitterapi

 

          Do you have an example to share in the language of your choice? Please share!

 

<< Back to Twitter API Documentation