This deprecated method is replaced by GET search/tweets in API v1.1
Returns relevant tweets that match a specified query. To best learn how to use Twitter Search effectively, consult our guide to Using the Twitter Search API
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.
As of Nov 7, 2011 the Search API returns Twitter user IDs that match the Twitter REST API. You no longer need to maintain multiple ids for the same user.
As of Dec, 2011 the Search API now supports all Entities in Twitter Objects when using the include_entities=true parameter.
Resource URL
Parameters
A UTF-8, URL-encoded search query of 1,000 characters maximum, including operators. Queries may additionally be limited by complexity.
Example Values: @noradio
Only available for JSON format. If supplied, the response will use the JSONP format with a callback of the given name.
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. A maximum of 1,000 distinct "sub-regions" will be considered when using the radius modifier.
Example Values: 37.781157,-122.398720,1mi
Restricts tweets to the given language, given by an ISO 639-1 code.
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.
Example Values: ja
The page number (starting at 1) to return, up to a max of roughly 1500 results (based on rpp * page).
Example Values: 10
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.
Example Values: mixed, recent, popular
The number of tweets to return per page, up to a max of 100.
Example Values: 100
When true, prepends "
Optional. Returns tweets generated before the given date. Date should be formatted as YYYY-MM-DD.
Example Values: 2010-03-28
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.
Example Values: 12345
Returns results with an ID less than (that is, older than) or equal to the specified ID.
Example Values: 54321
When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a variety of metadata about the tweet in a discrete structure, including: urls, media and hashtags. Note that user mentions are currently not supported for search and there will be no "user_mentions
" key in the entities map. See Tweet Entities for more detail on entities. Please note that entities are only available for JSON responses in the Search API.
Example Values: true
Example Request
GET |
|
Returns 5 mixed results with Twitter.com user IDs plus entities for the term "blue angels":
{
"completed_in":0.031,
"max_id":122078461840982016,
"max_id_str":"122078461840982016",
"next_page":"?page=2&max_id=122078461840982016&q=blue%20angels&rpp=5",
"page":1,
"query":"blue+angels",
"refresh_url":"?since_id=122078461840982016&q=blue%20angels",
"results":[
{
"created_at":"Thu, 06 Oct 2011 19:36:17 +0000",
"entities":{
"urls":[
{
"url":"http://t.co/L9JXJ2ee",
"expanded_url":"http://bit.ly/q9fyz9",
"display_url":"bit.ly/q9fyz9",
"indices":[
37,
57
]
}
]
},
"from_user":"SFist",
"from_user_id":14093707,
"from_user_id_str":"14093707",
"geo":null,
"id":122032448266698752,
"id_str":"122032448266698752",
"iso_language_code":"en",
"metadata":{
"recent_retweets":3,
"result_type":"popular"
},
"profile_image_url":"http://a3.twimg.com/profile_images/51584619/SFist07_normal.jpg",
"source":"<a href="http://twitter.com/tweetbutton" rel="nofollow">Tweet Button</a>",
"text":"Reminder: Blue Angels practice today http://t.co/L9JXJ2ee",
"to_user_id":null,
"to_user_id_str":null
},
{
"created_at":"Thu, 06 Oct 2011 19:41:12 +0000",
"entities":{
},
"from_user":"masters212",
"from_user_id":2242041,
"from_user_id_str":"2242041",
"geo":null,
"id":122033683212419072,
"id_str":"122033683212419072",
"iso_language_code":"en",
"metadata":{
"recent_retweets":1,
"result_type":"popular"
},
"profile_image_url":"http://a3.twimg.com/profile_images/488532540/rachel25final_normal.jpg",
"source":"<a href="http://twitter.com/">web</a>",
"text":"Starting to hear Blue Angels... Not such angels with all of the noise and carbon pollution.",
"to_user_id":null,
"to_user_id_str":null
},
{
"created_at":"Thu, 06 Oct 2011 19:39:52 +0000",
"entities":{
},
"from_user":"SFBayBridge",
"from_user_id":182107587,
"from_user_id_str":"182107587",
"geo":null,
"id":122033350327279617,
"id_str":"122033350327279617",
"iso_language_code":"en",
"metadata":{
"recent_retweets":1,
"result_type":"popular"
},
"profile_image_url":"http://a0.twimg.com/profile_images/1162882917/bbtwitternew_normal.jpg",
"source":"<a href="http://twitter.com/">web</a>",
"text":"BZZZzzzZzZzzzZZZZZzZz WHAT? I CAN'T HEAR YOU. THERE ARE BLUE ANGELS. ZZZzzZZZ!",
"to_user_id":null,
"to_user_id_str":null
},
{
"created_at":"Thu, 06 Oct 2011 22:39:08 +0000",
"entities":{
},
"from_user":"OnDST",
"from_user_id":265656068,
"from_user_id_str":"265656068",
"geo":null,
"id":122078461840982016,
"id_str":"122078461840982016",
"iso_language_code":"nl",
"metadata":{
"result_type":"recent"
},
"profile_image_url":"http://a3.twimg.com/profile_images/1271597598/OnDST_normal.jpg",
"source":"<a href="http://dlvr.it" rel="nofollow">dlvr.it</a>",
"text":"SF Fleet Week to open with Blue Angels flyovers | Student ...",
"to_user_id":null,
"to_user_id_str":null
},
{
"created_at":"Thu, 06 Oct 2011 22:38:51 +0000",
"entities":{
},
"from_user":"gusbumper",
"from_user_id":15912539,
"from_user_id_str":"15912539",
"geo":null,
"id":122078393641603072,
"id_str":"122078393641603072",
"iso_language_code":"en",
"metadata":{
"result_type":"recent"
},
"profile_image_url":"http://a2.twimg.com/profile_images/832286946/pho_normal.jpg",
"source":"<a href="http://itunes.apple.com/us/app/twitter/id409789998?mt=12" rel="nofollow">Twitter for Mac</a>",
"text":"RT @gzahnd: WAKE UP HIPPIES, THE BLUE ANGELS ARE IN TOWN!",
"to_user_id":null,
"to_user_id_str":null
},
{
"created_at":"Thu, 06 Oct 2011 22:38:31 +0000",
"entities":{
},
"from_user":"LUVTQUILT",
"from_user_id":32653550,
"from_user_id_str":"32653550",
"geo":null,
"id":122078309004742656,
"id_str":"122078309004742656",
"iso_language_code":"en",
"metadata":{
"result_type":"recent"
},
"profile_image_url":"http://a1.twimg.com/profile_images/1188428056/IMG00007-20100521-1647_1__normal.jpg",
"source":"<a href="http://ubersocial.com" rel="nofollow">\u00DCberSocial for BlackBerry</a>",
"text":"Thursday - Just watched the Blue Angels practice over SF Bay Impressive! What a background. GGB & Alcatraz. ;) .",
"to_user_id":null,
"to_user_id_str":null
},
{
"created_at":"Thu, 06 Oct 2011 22:38:22 +0000",
"entities":{
"urls":[
{
"url":"http://t.co/fyL8Rs5f",
"expanded_url":"http://dlvr.it/pfFfj",
"display_url":"dlvr.it/pfFfj",
"indices":[
52,
72
]
}
]
},
"from_user":"johnnyfuncheap",
"from_user_id":20717004,
"from_user_id_str":"20717004",
"geo":null,
"id":122078271478317056,
"id_str":"122078271478317056",
"iso_language_code":"en",
"metadata":{
"result_type":"recent"
},
"profile_image_url":"http://a0.twimg.com/profile_images/1130541908/funcheap_icon_twitter_normal.gif",
"source":"<a href="http://dlvr.it" rel="nofollow">dlvr.it</a>",
"text":"10/8/11: Blue Angels Wine Tasting | Treasure Island http://t.co/fyL8Rs5f",
"to_user_id":null,
"to_user_id_str":null
},
{
"created_at":"Thu, 06 Oct 2011 22:37:28 +0000",
"entities":{
"urls":[
{
"url":"http://t.co/KfzEqOWM",
"expanded_url":"http://married2travel.com/2600/san-francisco-day3-golden-gate-park-pier-39-blue-angels/",
"display_url":"married2travel.com/2600/san-franc\u2026",
"indices":[
47,
67
]
}
]
},
"from_user":"espenorio",
"from_user_id":52736683,
"from_user_id_str":"52736683",
"geo":null,
"id":122078043664695296,
"id_str":"122078043664695296",
"iso_language_code":"en",
"metadata":{
"result_type":"recent"
},
"profile_image_url":"http://a0.twimg.com/profile_images/1574863913/sheil_normal.png",
"source":"<a href="http://twitter.com/">web</a>",
"text":"San Francisco 2010 Fleet week photos and video http://t.co/KfzEqOWM",
"to_user_id":null,
"to_user_id_str":null
}
],
"results_per_page":5,
"since_id":0,
"since_id_str":"0"
}
Returns first page of mixed results for the search term "Twitter API":
GET http://search.twitter.com/search.json?q=Twitter%20API&result;_type=mixed
{
"max_id": 27836852555751424,
"results": [
{
"created_at": "Wed, 19 Jan 2011 21:16:37 +0000",
"profile_image_url": "http://a2.twimg.com/sticky/default_profile_images/default_profile_1_normal.png",
"from_user_id_str": "191709163",
"id_str": "27836852555751424",
"from_user": "DanLabTesting",
"text": "Twitter api: 1234455",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27836852555751424,
"geo": null,
"from_user_id": 191709163,
"iso_language_code": "en",
"source": "<a href="http://www.danlabgames.com/index.php?computer=ipad" rel="nofollow">Wacka Monsta</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 21:12:02 +0000",
"profile_image_url": "http://a0.twimg.com/profile_images/1142619698/DSC_0195_normal.jpg",
"from_user_id_str": "165544885",
"id_str": "27835698383945728",
"from_user": "Deberamatkin",
"text": "Fetching the number of followers without using any Twitter API http://pr9.in/4q",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27835698383945728,
"geo": null,
"from_user_id": 165544885,
"iso_language_code": "en",
"source": "<a href="http://www.exaspring.com" rel="nofollow">ExaSpring Information Services</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 20:57:35 +0000",
"profile_image_url": "http://a3.twimg.com/profile_images/1093562803/__F1000040mini_normal.jpg",
"from_user_id_str": "95281337",
"id_str": "27832064640290817",
"from_user": "Lito_tweet",
"text": "More info can be found here http://support.twitter.com/articles/15364-about-twitter-limits-update-api-dm-and-following",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27832064640290817,
"geo": null,
"from_user_id": 95281337,
"iso_language_code": "en",
"source": "<a href="http://yubitter.com/" rel="nofollow">yubitter</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 20:53:18 +0000",
"profile_image_url": "http://a1.twimg.com/profile_images/1196625301/Twitter_normal.JPG",
"from_user_id_str": "77719707",
"id_str": "27830982988005377",
"from_user": "g_a_x",
"text": "RT @ramirezviki: RT @g_a_x: "Twitter Status: Twitter API rate excedeed" WTF??? // Que dejes de twittearrrr!!!!!!!!!!! // JJAJAJAJAJJAAA",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27830982988005377,
"geo": null,
"from_user_id": 77719707,
"iso_language_code": "en",
"source": "<a href="http://www.tweetdeck.com" rel="nofollow">TweetDeck</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 20:51:06 +0000",
"profile_image_url": "http://a2.twimg.com/profile_images/673715309/danlablogo_normal.png",
"from_user_id_str": "20913275",
"id_str": "27830431516729344",
"from_user": "DanLabGames",
"text": "Working on Facebook and Twitter API on iPhone.. Silly Piece of code. But it Work",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27830431516729344,
"geo": null,
"from_user_id": 20913275,
"iso_language_code": "en",
"source": "<a href="http://www.danlabgames.com/index.php?computer=ipad" rel="nofollow">Wacka Monsta</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 20:44:42 +0000",
"profile_image_url": "http://a1.twimg.com/profile_images/1220195008/BeautyIsHerName_normal.JPG",
"from_user_id_str": "180040602",
"id_str": "27828818869747713",
"from_user": "MozBWanKinobi",
"text": "@Patroose It's slow as shit, that damn Twitter API thing pops up every 5 minutes, and won't post tweets half the time, they need to fix it",
"to_user_id": 16219315,
"metadata": {
"result_type": "recent"
},
"id": 27828818869747713,
"geo": null,
"to_user": "Patroose",
"from_user_id": 180040602,
"iso_language_code": "en",
"source": "<a href="http://twitter.com/">web</a>",
"to_user_id_str": "16219315"
},
{
"created_at": "Wed, 19 Jan 2011 20:42:13 +0000",
"profile_image_url": "http://a3.twimg.com/profile_images/1167064690/b460f7b0-d6ac-4d8a-b025-998cadb31acc_normal.png",
"from_user_id_str": "11861298",
"id_str": "27828194379833345",
"from_user": "twittwootwiggy",
"text": "@USoBritain @elejamie Cheers, if i'm on the list i will prove i'm worth it. http://api.twitter.com/EDLinfidel/wankers#",
"to_user_id": 105839068,
"metadata": {
"result_type": "recent"
},
"id": 27828194379833345,
"geo": null,
"to_user": "USoBritain",
"from_user_id": 11861298,
"iso_language_code": "en",
"source": "<a href="http://twitter.com/">web</a>",
"to_user_id_str": "105839068"
},
{
"created_at": "Wed, 19 Jan 2011 20:35:29 +0000",
"profile_image_url": "http://a2.twimg.com/profile_images/1197946386/Seb_lasLe_as_normal.jpg",
"from_user_id_str": "155070729",
"id_str": "27826502271762432",
"from_user": "iSebx",
"text": "RT @g_a_x "Twitter Status: Twitter API rate excedeed" WTF??? // estaba por postear lo mismo no me dejaba subir una foto",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27826502271762432,
"geo": null,
"from_user_id": 155070729,
"iso_language_code": "en",
"source": "<a href="http://www.tweetdeck.com" rel="nofollow">TweetDeck</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 20:24:26 +0000",
"profile_image_url": "http://a2.twimg.com/profile_images/859603564/johannes_normal.jpg",
"from_user_id_str": "104685382",
"id_str": "27823718839361536",
"from_user": "seo_depp",
"text": "rt @davide_rosi2011#analytics New ActionScript 3 Library For The API: We love simplifying access to Google Analy... http://bit.ly/i8k0IA",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27823718839361536,
"geo": null,
"from_user_id": 104685382,
"iso_language_code": "en",
"source": "<a href="http://twitterfeed.com" rel="nofollow">twitterfeed</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 20:21:46 +0000",
"profile_image_url": "http://a1.twimg.com/profile_images/1196625301/Twitter_normal.JPG",
"from_user_id_str": "77719707",
"id_str": "27823049667510272",
"from_user": "g_a_x",
"text": ""Twitter Status: Twitter API rate excedeed" WTF???",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27823049667510272,
"geo": null,
"from_user_id": 77719707,
"iso_language_code": "en",
"source": "<a href="http://www.tweetdeck.com" rel="nofollow">TweetDeck</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 20:05:22 +0000",
"profile_image_url": "http://a1.twimg.com/profile_images/1102380575/61918c9a-8d5c-4390-b41f-b234398cd5d4_normal.png",
"from_user_id_str": "7654007",
"id_str": "27818920278757376",
"from_user": "ConMend",
"text": "#TwitterHelp #Help #CallingofTheGeeks Please help me get rid of the Twitter API dialogue box that pops up every bleeding minute!",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27818920278757376,
"geo": null,
"from_user_id": 7654007,
"iso_language_code": "en",
"source": "<a href="http://twitter.com/">web</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 19:55:36 +0000",
"profile_image_url": "http://a3.twimg.com/profile_images/1167064690/b460f7b0-d6ac-4d8a-b025-998cadb31acc_normal.png",
"from_user_id_str": "11861298",
"id_str": "27816463830089728",
"from_user": "twittwootwiggy",
"text": "Its easy to get on http://api.twitter.com/#!/EDLinfidel/wankers @Andrea_UrbanFox just ask @EDLinfidel a Hypothetical question referring #EDL",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27816463830089728,
"geo": null,
"from_user_id": 11861298,
"iso_language_code": "en",
"source": "<a href="http://twitter.com/">web</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 19:55:10 +0000",
"profile_image_url": "http://a0.twimg.com/profile_images/585494683/13038_613894593395_24403188_35452430_7524658_n_normal.jpg",
"from_user_id_str": "1493373",
"id_str": "27816354073550848",
"from_user": "mirandafte",
"text": "@mirandafte testing some twitter API - ness",
"to_user_id": 1493373,
"metadata": {
"result_type": "recent"
},
"id": 27816354073550848,
"geo": null,
"to_user": "mirandafte",
"from_user_id": 1493373,
"iso_language_code": "en",
"source": "<a href="http://twitter.com/">web</a>",
"to_user_id_str": "1493373"
},
{
"created_at": "Wed, 19 Jan 2011 19:55:07 +0000",
"profile_image_url": "http://a0.twimg.com/profile_images/1213136572/110105-195452_normal.jpg",
"from_user_id_str": "134087646",
"id_str": "27816342371434496",
"from_user": "rachel8973",
"text": "Actually @TweetDeck it's not your fault it's the useless @twitter API. But you still smell",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27816342371434496,
"geo": null,
"from_user_id": 134087646,
"iso_language_code": "en",
"source": "<a href="http://seesmic.com/app" rel="nofollow">Seesmic Web</a>",
"to_user_id_str": null
},
{
"created_at": "Wed, 19 Jan 2011 19:52:39 +0000",
"profile_image_url": "http://a3.twimg.com/profile_images/1172946788/eagle-flag-4_normal.jpg",
"from_user_id_str": "174036699",
"id_str": "27815721295679488",
"from_user": "benny_hans",
"text": "One Reason For Those Twitter API Limits: Search Volume is Soaring http://bit.ly/aksMW2 #twitter #twittertips",
"to_user_id": null,
"metadata": {
"result_type": "recent"
},
"id": 27815721295679488,
"geo": null,
"from_user_id": 174036699,
"iso_language_code": "en",
"source": "<a href="http://twitter.com/">web</a>",
"to_user_id_str": null
}
],
"since_id": 0,
"refresh_url": "?since_id=27836852555751424&q=Twitter+API",
"next_page": "?page=2&max_id=27836852555751424&q=Twitter+API",
"page": 1,
"results_per_page": 15,
"completed_in": 0.075744,
"since_id_str": "0",
"query": "Twitter+API",
"max_id_str": "27836852555751424"
}
GET |
|
As of November 15th, 2011, the Search API returns a from_user_name field with the display name for the owner of a Tweet, and, if the Tweet is a reply, a to_user_name field with the display name for the user being replied to.
{
"completed_in": 0.012,
"max_id": 136536013832069120,
"max_id_str": "136536013832069120",
"next_page": "?page=2&max_id=136536013832069120&q=twitterapi&rpp=1",
"page": 1,
"query": "twitterapi",
"refresh_url": "?since_id=136536013832069120&q=twitterapi",
"results": [
{
"created_at": "Tue, 15 Nov 2011 20:08:17 +0000",
"from_user": "fakekurrik",
"from_user_id": 370773112,
"from_user_id_str": "370773112",
"from_user_name": "fakekurrik",
"geo": null,
"id": 136536013832069120,
"id_str": "136536013832069120",
"iso_language_code": "en",
"metadata": {
"result_type": "recent"
},
"profile_image_url": "http://a1.twimg.com/profile_images/1540298033/phatkicks_normal.jpg",
"source": "<a href="http://twitter.com/">web</a>",
"text": "@twitterapi, keep on keeping it real",
"to_user": "twitterapi",
"to_user_id": 6253282,
"to_user_id_str": "6253282",
"to_user_name": "Twitter API"
}
],
"results_per_page": 1,
"since_id": 0,
"since_id_str": "0"
}