This snapshot, taken on
26/05/2011
, shows web content acquired for preservation by The National Archives. External links, forms and search may not work in archived websites and contact details are likely to be out of date.
 
 
The UK Government Web Archive does not use cookies but some may be left in your browser from archived websites.

Introducing Web Intents

Attention!       March 30, 2011 Bring interactivity to Tweets that you display on the web with Web Intents.    x

Find out everything about Web Intents here.

GET search

Home › Documentation › Search Resources › search

Returns tweets that match a specified query. Learn more about using search in our resource pages.

Notice: As of April 1st 2010, the Search API provides an option to retrieve "popular tweets" in addition to real-time search results. In an upcoming release, this will become the default and clients that don't want to receive popular tweets in their search results will have to explicitly opt-out. See the result_type parameter below for more information.

Warning: The user ids in the Search API are different from those in the REST API (about the two APIs). 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/lookup method to get the correct user id if necessary.

URL

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

Supported formats

json, atom

Supported request methods

GET

Requires Authentication

false About authentication »

Rate Limited

true About rate limiting »

Parameters

Required

  • q Search query. Should be URL encoded. Queries will be limited by complexity.
    • http://search.twitter.com/search.json?q=@noradio

Optional

  • callback Only available for JSON format. If supplied, the response will use the JSONP format with a callback of the given name.
  • lang Restricts tweets to the given language, given by an ISO 639-1 code.
  • locale Specify the language of the query you are sending (only ja is currently effective). This is intended for language-specific clients and the default should work in the majority of cases.
    • http://search.twitter.com/search.json?locale=ja
  • rpp The number of tweets to return per page, up to a max of 100.
    • http://search.twitter.com/search.json?rpp=100
  • page The page number (starting at 1) to return, up to a max of roughly 1500 results (based on rpp * page).
    • http://search.twitter.com/search.json?page=10
  • since_id Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
    • http://search.twitter.com/search.json?since_id=12345
  • until Optional. Returns tweets generated before the given date. Date should be formatted as YYYY-MM-DD.
    • http://search.twitter.com/search.json?until=2010-03-28
  • geocode Returns tweets by users located within a given radius of the given latitude/longitude. The location is preferentially taking from the Geotagging API, but will fall back to their Twitter profile. The parameter value is specified by "latitude,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.
    • http://search.twitter.com/search.json?geocode=37.781157,-122.398720,1mi
  • show_user When true, prepends ":" to the beginning of the tweet. This is useful for readers that do not display Atom's author field. The default is false.
  • result_type Optional. Specifies what type of search results you would prefer to receive. The current default is "mixed." Valid values include:
    • mixed: Include both popular and real time results in the response.
    • recent: return only the most recent results in the response
    • popular: return only the most popular results in the response.
    • http://search.twitter.com/search.json?result_type=mixed
    • http://search.twitter.com/search.json?result_type=recent
    • http://search.twitter.com/search.json?result_type=popular

Example requests

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


{"results":[
     {"text":"@twitterapi  http:\/\/tinyurl.com\/ctrefg",
     "to_user_id":396524,
     "to_user":"TwitterAPI",
     "from_user":"jkoum",
     "metadata":
     {
      "result_type":"popular",
      "recent_retweets": 100

     },
     "id":1478555574,
     "from_user_id":1833773,
     "iso_language_code":"nl",
     "source":"<a href=http://collections.europarchive.org/tna/20110602045055/http://dev.twitter.com/doc/get/"http:\/\/twitter.com\/">twitter<\/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"},
     ... truncated ...],
     "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"}
}

Related Documentation

This document last updated by themattharris on April 29, 2011