Twitter API

version 1.1           https://api.twitter.com/1.1/

/search/tweets.json


GET https://api.twitter.com/1.1//search/tweets.json

Returns a collection of relevant Tweets matching a specified query.

Query Parameters

ParameterTypeRequiredDescription
qstringYesA UTF-8, URL-encoded search query of 1,000 characters maximum, including operators. Queries may additionally be limited by complexity.
geocodestringReturns 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.
langstringRestricts tweets to the given language, given by an ISO 639-1 code. Language detection is best-effort.
localestringSpecify the language of the query you are sending (only ja is currently effective). This is intended for language-specific consumers and the default should work in the majority of cases.Example: ja
result_type Notice: Undefined index: type in /var/www/vhosts/mikestowe.com/httpdocs/demos/raml2htmlphpQA/templates/grey/_action.phtml on line 26 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.
countintegerThe number of tweets to return per page, up to a maximum of 100.
untilstringReturns tweets generated before the given date. Date should be formatted as YYYY-MM-DD. Keep in mind that the search index may not go back as far as the date you specify here.
since_idintegerReturns 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.
max_idintegerReturns results with an ID less than (that is, older than) or equal to the specified ID.
callbackstringIf supplied, the response will use the JSONP format with a callback of the given name. The usefulness of this parameter is somewhat diminished by the requirement of authentication for requests to this endpoint.

Code Samples

JavaScript PHP Rails
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", "https://api.twitter.com/1.1//search/tweets.json?q=%q%", false);

// Make sure you set the appropriate headers
xmlHttp.setRequestHeader("Header Goes Here");

xmlHttp.send(null);

var response = xmlHttp.responseText;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.twitter.com/1.1//search/tweets.json?q=%q%");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Make sure you set the nessary headers as a $headers array
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
uri = URI.parse("https://api.twitter.com/1.1//search/tweets.json?q=%q%")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Get.new(uri.request_uri)

# Make sure you set the appropriate headers
request["header"] = "header value"

response = http.request(request)

Response

200:

Standard Response
{
    "statuses": [
        {
            "coordinates": null,
            "favorited": false,
            "truncated": false,
            "created_at": "Mon Sep 24 03:35:21 +0000 2012",
            "id_str": "250075927172759552",
            "entities": {
                "urls": [],
                "hashtags": [
                    {
                        "text": "freebandnames",
                        "indices": [
                            20,
                            34
                        ]
                    }
                ],
                "user_mentions": []
            },
            "in_reply_to_user_id_str": null,
            "contributors": null,
            "text": "Aggressive Ponytail #freebandnames",
            "metadata": {
                "iso_language_code": "en",
                "result_type": "recent"
            },
            "retweet_count": 0,
            "in_reply_to_status_id_str": null,
            "id": 250075927172759550,
            "geo": null,
            "retweeted": false,
            "in_reply_to_user_id": null,
            "place": null,
            "user": {
                "profile_sidebar_fill_color": "DDEEF6",
                "profile_sidebar_border_color": "C0DEED",
                "profile_background_tile": false,
                "name": "Sean Cummings",
                "profile_image_url": "http://a0.twimg.com/profile_images/2359746665/1v6zfgqo8g0d3mk7ii5s_normal.jpeg",
                "created_at": "Mon Apr 26 06:01:55 +0000 2010",
                "location": "LA, CA",
                "follow_request_sent": null,
                "profile_link_color": "0084B4",
                "is_translator": false,
                "id_str": "137238150",
                "entities": {
                    "url": {
                        "urls": [
                            {
                                "expanded_url": null,
                                "url": "",
                                "indices": [
                                    0,
                                    0
                                ]
                            }
                        ]
                    },
                    "description": {
                        "urls": []
                    }
                },
                "default_profile": true,
                "contributors_enabled": false,
                "favourites_count": 0,
                "url": null,
                "profile_image_url_https": "https://si0.twimg.com/profile_images/2359746665/1v6zfgqo8g0d3mk7ii5s_normal.jpeg",
                "utc_offset": -28800,
                "id": 137238150,
                "profile_use_background_image": true,
                "listed_count": 2,
                "profile_text_color": "333333",
                "lang": "en",
                "followers_count": 70,
                "protected": false,
                "notifications": null,
                "profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme1/bg.png",
                "profile_background_color": "C0DEED",
                "verified": false,
                "geo_enabled": true,
                "time_zone": "Pacific Time (US & Canada)",
                "description": "Born 330 Live 310",
                "default_profile_image": false,
                "profile_background_image_url": "http://a0.twimg.com/images/themes/theme1/bg.png",
                "statuses_count": 579,
                "friends_count": 110,
                "following": null,
                "show_all_inline_media": false,
                "screen_name": "sean_cummings"
            },
            "in_reply_to_screen_name": null,
            "source": "<a href=\"http://itunes.apple.com/us/app/twitter/id409789998?mt=12\" rel=\"nofollow\">Twitter for Mac</a>",
            "in_reply_to_status_id": null
        },
        {
            "coordinates": null,
            "favorited": false,
            "truncated": false,
            "created_at": "Fri Sep 21 23:40:54 +0000 2012",
            "id_str": "249292149810667520",
            "entities": {
                "urls": [],
                "hashtags": [
                    {
                        "text": "FreeBandNames",
                        "indices": [
                            20,
                            34
                        ]
                    }
                ],
                "user_mentions": []
            },
            "in_reply_to_user_id_str": null,
            "contributors": null,
            "text": "Thee Namaste Nerdz. #FreeBandNames",
            "metadata": {
                "iso_language_code": "pl",
                "result_type": "recent"
            },
            "retweet_count": 0,
            "in_reply_to_status_id_str": null,
            "id": 249292149810667520,
            "geo": null,
            "retweeted": false,
            "in_reply_to_user_id": null,
            "place": null,
            "user": {
                "profile_sidebar_fill_color": "DDFFCC",
                "profile_sidebar_border_color": "BDDCAD",
                "profile_background_tile": true,
                "name": "Chaz Martenstein",
                "profile_image_url": "http://a0.twimg.com/profile_images/447958234/Lichtenstein_normal.jpg",
                "created_at": "Tue Apr 07 19:05:07 +0000 2009",
                "location": "Durham, NC",
                "follow_request_sent": null,
                "profile_link_color": "0084B4",
                "is_translator": false,
                "id_str": "29516238",
                "entities": {
                    "url": {
                        "urls": [
                            {
                                "expanded_url": null,
                                "url": "http://bullcityrecords.com/wnng/",
                                "indices": [
                                    0,
                                    32
                                ]
                            }
                        ]
                    },
                    "description": {
                        "urls": []
                    }
                },
                "default_profile": false,
                "contributors_enabled": false,
                "favourites_count": 8,
                "url": "http://bullcityrecords.com/wnng/",
                "profile_image_url_https": "https://si0.twimg.com/profile_images/447958234/Lichtenstein_normal.jpg",
                "utc_offset": -18000,
                "id": 29516238,
                "profile_use_background_image": true,
                "listed_count": 118,
                "profile_text_color": "333333",
                "lang": "en",
                "followers_count": 2052,
                "protected": false,
                "notifications": null,
                "profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/9423277/background_tile.bmp",
                "profile_background_color": "9AE4E8",
                "verified": false,
                "geo_enabled": false,
                "time_zone": "Eastern Time (US & Canada)",
                "description": "You will come to Durham, North Carolina. I will sell you some records then, here in Durham, North Carolina. Fun will happen.",
                "default_profile_image": false,
                "profile_background_image_url": "http://a0.twimg.com/profile_background_images/9423277/background_tile.bmp",
                "statuses_count": 7579,
                "friends_count": 348,
                "following": null,
                "show_all_inline_media": true,
                "screen_name": "bullcityrecords"
            },
            "in_reply_to_screen_name": null,
            "source": "web",
            "in_reply_to_status_id": null
        },
        {
            "coordinates": null,
            "favorited": false,
            "truncated": false,
            "created_at": "Fri Sep 21 23:30:20 +0000 2012",
            "id_str": "249289491129438208",
            "entities": {
                "urls": [],
                "hashtags": [
                    {
                        "text": "freebandnames",
                        "indices": [
                            29,
                            43
                        ]
                    }
                ],
                "user_mentions": []
            },
            "in_reply_to_user_id_str": null,
            "contributors": null,
            "text": "Mexican Heaven, Mexican Hell #freebandnames",
            "metadata": {
                "iso_language_code": "en",
                "result_type": "recent"
            },
            "retweet_count": 0,
            "in_reply_to_status_id_str": null,
            "id": 249289491129438200,
            "geo": null,
            "retweeted": false,
            "in_reply_to_user_id": null,
            "place": null,
            "user": {
                "profile_sidebar_fill_color": "99CC33",
                "profile_sidebar_border_color": "829D5E",
                "profile_background_tile": false,
                "name": "Thomas John Wakeman",
                "profile_image_url": "http://a0.twimg.com/profile_images/2219333930/Froggystyle_normal.png",
                "created_at": "Tue Sep 01 21:21:35 +0000 2009",
                "location": "Kingston New York",
                "follow_request_sent": null,
                "profile_link_color": "D02B55",
                "is_translator": false,
                "id_str": "70789458",
                "entities": {
                    "url": {
                        "urls": [
                            {
                                "expanded_url": null,
                                "url": "",
                                "indices": [
                                    0,
                                    0
                                ]
                            }
                        ]
                    },
                    "description": {
                        "urls": []
                    }
                },
                "default_profile": false,
                "contributors_enabled": false,
                "favourites_count": 19,
                "url": null,
                "profile_image_url_https": "https://si0.twimg.com/profile_images/2219333930/Froggystyle_normal.png",
                "utc_offset": -18000,
                "id": 70789458,
                "profile_use_background_image": true,
                "listed_count": 1,
                "profile_text_color": "3E4415",
                "lang": "en",
                "followers_count": 63,
                "protected": false,
                "notifications": null,
                "profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme5/bg.gif",
                "profile_background_color": "352726",
                "verified": false,
                "geo_enabled": false,
                "time_zone": "Eastern Time (US & Canada)",
                "description": "Science Fiction Writer, sort of. Likes Superheroes, Mole People, Alt. Timelines.",
                "default_profile_image": false,
                "profile_background_image_url": "http://a0.twimg.com/images/themes/theme5/bg.gif",
                "statuses_count": 1048,
                "friends_count": 63,
                "following": null,
                "show_all_inline_media": false,
                "screen_name": "MonkiesFist"
            },
            "in_reply_to_screen_name": null,
            "source": "web",
            "in_reply_to_status_id": null
        },
        {
            "coordinates": null,
            "favorited": false,
            "truncated": false,
            "created_at": "Fri Sep 21 22:51:18 +0000 2012",
            "id_str": "249279667666817024",
            "entities": {
                "urls": [],
                "hashtags": [
                    {
                        "text": "freebandnames",
                        "indices": [
                            20,
                            34
                        ]
                    }
                ],
                "user_mentions": []
            },
            "in_reply_to_user_id_str": null,
            "contributors": null,
            "text": "The Foolish Mortals #freebandnames",
            "metadata": {
                "iso_language_code": "en",
                "result_type": "recent"
            },
            "retweet_count": 0,
            "in_reply_to_status_id_str": null,
            "id": 249279667666817020,
            "geo": null,
            "retweeted": false,
            "in_reply_to_user_id": null,
            "place": null,
            "user": {
                "profile_sidebar_fill_color": "BFAC83",
                "profile_sidebar_border_color": "615A44",
                "profile_background_tile": true,
                "name": "Marty Elmer",
                "profile_image_url": "http://a0.twimg.com/profile_images/1629790393/shrinker_2000_trans_normal.png",
                "created_at": "Mon May 04 00:05:00 +0000 2009",
                "location": "Wisconsin, USA",
                "follow_request_sent": null,
                "profile_link_color": "3B2A26",
                "is_translator": false,
                "id_str": "37539828",
                "entities": {
                    "url": {
                        "urls": [
                            {
                                "expanded_url": null,
                                "url": "http://www.omnitarian.me",
                                "indices": [
                                    0,
                                    24
                                ]
                            }
                        ]
                    },
                    "description": {
                        "urls": []
                    }
                },
                "default_profile": false,
                "contributors_enabled": false,
                "favourites_count": 647,
                "url": "http://www.omnitarian.me",
                "profile_image_url_https": "https://si0.twimg.com/profile_images/1629790393/shrinker_2000_trans_normal.png",
                "utc_offset": -21600,
                "id": 37539828,
                "profile_use_background_image": true,
                "listed_count": 52,
                "profile_text_color": "000000",
                "lang": "en",
                "followers_count": 608,
                "protected": false,
                "notifications": null,
                "profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/106455659/rect6056-9.png",
                "profile_background_color": "EEE3C4",
                "verified": false,
                "geo_enabled": false,
                "time_zone": "Central Time (US & Canada)",
                "description": "Cartoonist, Illustrator, and T-Shirt connoisseur",
                "default_profile_image": false,
                "profile_background_image_url": "http://a0.twimg.com/profile_background_images/106455659/rect6056-9.png",
                "statuses_count": 3575,
                "friends_count": 249,
                "following": null,
                "show_all_inline_media": true,
                "screen_name": "Omnitarian"
            },
            "in_reply_to_screen_name": null,
            "source": "<a href=\"http://twitter.com/download/iphone\" rel=\"nofollow\">Twitter for iPhone</a>",
            "in_reply_to_status_id": null
        }
    ],
    "search_metadata": {
        "max_id": 250126199840518140,
        "since_id": 24012619984051000,
        "refresh_url": "?since_id=250126199840518145&q=%23freebandnames&result_type=mixed&include_entities=1",
        "next_results": "?max_id=249279667666817023&q=%23freebandnames&count=4&include_entities=1&result_type=mixed",
        "count": 4,
        "completed_in": 0.035,
        "since_id_str": "24012619984051000",
        "query": "%23freebandnames",
        "max_id_str": "250126199840518145"
    }
}