Standard search API
get-search-tweets

Standard search API

Returns a collection of relevant Tweets matching a specified query.

Please note that Twitter's search service and, by extension, the Search API is not meant to be an exhaustive source of Tweets. Not all Tweets will be indexed or made available via the search interface.

To learn how to use Twitter Search effectively, please see the Standard search operators page for a list of available filter operators. Also, see the Working with Timelines page to learn best practices for navigating results by since_id and max_id.

Resource URL

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

Resource Information

Response formats JSON
Requires authentication? Yes
Rate limited? Yes
Requests / 15-min window (user auth) 180
Requests / 15-min window (app auth) 450
Supports Edit Tweets feature? Yes

Parameters

Name Required Description Default Value Example
q required A UTF-8, URL-encoded search query of 500 characters maximum, including operators. Queries may additionally be limited by complexity. @noradio
include_ext_edit_control optional

Must be set to true in order to return edited Tweet metadata as part of the Tweet object.

include_ext_edit_control=true

Note that historical Tweets may not contain edited Tweet metadata.

To learn more about how edited Tweets are supported, see the Edit Tweets fundamentals page.

true
geocode optional 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. 37.781157 -122.398720 1mi
lang optional Restricts tweets to the given language, given by an ISO 639-1 code. Language detection is best-effort. eu
locale optional Specify 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. ja
result_type optional

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.

mixed recent popular
count optional The number of tweets to return per page, up to a maximum of 100. Defaults to 15. This was formerly the "rpp" parameter in the old Search API. 100
until optional Returns tweets created before the given date. Date should be formatted as YYYY-MM-DD. Keep in mind that the search index has a 7-day limit. In other words, no tweets will be found for a date older than one week. 2015-07-19
since_id optional 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. 12345
max_id optional Returns results with an ID less than (that is, older than) or equal to the specified ID. 54321
include_entities optional The entities node will not be included when set to false. false

Example Requests

$ curl --request GET 
 --url 'https://api.twitter.com/1.1/search/tweets.json?q=nasa&result_type=popular' 
 --header 'authorization: OAuth oauth_consumer_key="consumer-key-for-app", 
 oauth_nonce="generated-nonce", oauth_signature="generated-signature", 
 oauth_signature_method="HMAC-SHA1", oauth_timestamp="generated-timestamp", 
 oauth_token="access-token-for-authed-user", oauth_version="1.0"'
$ twurl /1.1/search/tweets.json?q=nasa&result_type=popular

Example Response

{
    "statuses": [
        {
            "created_at": "Sun Feb 25 18:11:01 +0000 2018",
            "id": 967824267948773377,
            "id_str": "967824267948773377",
            "text": "From pilot to astronaut, Robert H. Lawrence was the first African-American to be selected as an astronaut by any na… https://t.co/FjPEWnh804",
            "truncated": true,
            "entities": {
                "hashtags": [],
                "symbols": [],
                "user_mentions": [],
                "urls": [
                    {
                        "url": "https://t.co/FjPEWnh804",
                        "expanded_url": "https://twitter.com/i/web/status/967824267948773377",
                        "display_url": "twitter.com/i/web/status/9…",
                        "indices": [
                            117,
                            140
                        ]
                    }
                ]
            },
            "metadata": {
                "result_type": "popular",
                "iso_language_code": "en"
            },
            "source": "<a href='"https://www.sprinklr.com"' rel='"nofollow"'>Sprinklr</a>",
            "in_reply_to_status_id": null,
            "in_reply_to_status_id_str": null,
            "in_reply_to_user_id": null,
            "in_reply_to_user_id_str": null,
            "in_reply_to_screen_name": null,
            "user": {
                "id": 11348282,
                "id_str": "11348282",
                "name": "NASA",
                "screen_name": "NASA",
                "location": "",
                "description": "Explore the universe and discover our home planet with @NASA. We usually post in EST (UTC-5)",
                "url": "https://t.co/TcEE6NS8nD",
                "entities": {
                    "url": {
                        "urls": [
                            {
                                "url": "https://t.co/TcEE6NS8nD",
                                "expanded_url": "http://www.nasa.gov",
                                "display_url": "nasa.gov",
                                "indices": [
                                    0,
                                    23
                                ]
                            }
                        ]
                    },
                    "description": {
                        "urls": []
                    }
                },
                "protected": false,
                "followers_count": 28605561,
                "friends_count": 270,
                "listed_count": 90405,
                "created_at": "Wed Dec 19 20:20:32 +0000 2007",
                "favourites_count": 2960,
                "utc_offset": -18000,
                "time_zone": "Eastern Time (US & Canada)",
                "geo_enabled": false,
                "verified": true,
                "statuses_count": 50713,
                "lang": "en",
                "contributors_enabled": false,
                "is_translator": false,
                "is_translation_enabled": false,
                "profile_background_color": "000000",
                "profile_background_image_url": "http://pbs.twimg.com/profile_background_images/590922434682880000/3byPYvqe.jpg",
                "profile_background_image_url_https": "https://pbs.twimg.com/profile_background_images/590922434682880000/3byPYvqe.jpg",
                "profile_background_tile": false,
                "profile_image_url": "http://pbs.twimg.com/profile_images/188302352/nasalogo_twitter_normal.jpg",
                "profile_image_url_https": "https://pbs.twimg.com/profile_images/188302352/nasalogo_twitter_normal.jpg",
                "profile_banner_url": "https://pbs.twimg.com/profile_banners/11348282/1518798395",
                "profile_link_color": "205BA7",
                "profile_sidebar_border_color": "000000",
                "profile_sidebar_fill_color": "F3F2F2",
                "profile_text_color": "000000",
                "profile_use_background_image": true,
                "has_extended_profile": true,
                "default_profile": false,
                "default_profile_image": false,
                "following": null,
                "follow_request_sent": null,
                "notifications": null,
                "translator_type": "regular"
            },
            "geo": null,
            "coordinates": null,
            "place": null,
            "contributors": null,
            "is_quote_status": false,
            "retweet_count": 988,
            "favorite_count": 3875,
            "favorited": false,
            "retweeted": false,
            "possibly_sensitive": false,
            "lang": "en"
        },
        {
            "created_at": "Sun Feb 25 19:31:07 +0000 2018",
            "id": 967844427480911872,
            "id_str": "967844427480911872",
            "text": "A magnetic power struggle of galactic proportions - new research highlights the role of the Sun's magnetic landscap… https://t.co/29dZgga54m",
            "truncated": true,
            "entities": {
                "hashtags": [],
                "symbols": [],
                "user_mentions": [],
                "urls": [
                    {
                        "url": "https://t.co/29dZgga54m",
                        "expanded_url": "https://twitter.com/i/web/status/967844427480911872",
                        "display_url": "twitter.com/i/web/status/9…",
                        "indices": [
                            117,
                            140
                        ]
                    }
                ]
            },
            "metadata": {
                "result_type": "popular",
                "iso_language_code": "en"
            },
            "source": "<a href='"https://www.sprinklr.com"' rel='"nofollow"'>Sprinklr</a>",
            "in_reply_to_status_id": null,
            "in_reply_to_status_id_str": null,
            "in_reply_to_user_id": null,
            "in_reply_to_user_id_str": null,
            "in_reply_to_screen_name": null,
            "user": {
                "id": 11348282,
                "id_str": "11348282",
                "name": "NASA",
                "screen_name": "NASA",
                "location": "",
                "description": "Explore the universe and discover our home planet with @NASA. We usually post in EST (UTC-5)",
                "url": "https://t.co/TcEE6NS8nD",
                "entities": {
                    "url": {
                        "urls": [
                            {
                                "url": "https://t.co/TcEE6NS8nD",
                                "expanded_url": "http://www.nasa.gov",
                                "display_url": "nasa.gov",
                                "indices": [
                                    0,
                                    23
                                ]
                            }
                        ]
                    },
                    "description": {
                        "urls": []
                    }
                },
                "protected": false,
                "followers_count": 28605561,
                "friends_count": 270,
                "listed_count": 90405,
                "created_at": "Wed Dec 19 20:20:32 +0000 2007",
                "favourites_count": 2960,
                "utc_offset": -18000,
                "time_zone": "Eastern Time (US & Canada)",
                "geo_enabled": false,
                "verified": true,
                "statuses_count": 50713,
                "lang": "en",
                "contributors_enabled": false,
                "is_translator": false,
                "is_translation_enabled": false,
                "profile_background_color": "000000",
                "profile_background_image_url": "http://pbs.twimg.com/profile_background_images/590922434682880000/3byPYvqe.jpg",
                "profile_background_image_url_https": "https://pbs.twimg.com/profile_background_images/590922434682880000/3byPYvqe.jpg",
                "profile_background_tile": false,
                "profile_image_url": "http://pbs.twimg.com/profile_images/188302352/nasalogo_twitter_normal.jpg",
                "profile_image_url_https": "https://pbs.twimg.com/profile_images/188302352/nasalogo_twitter_normal.jpg",
                "profile_banner_url": "https://pbs.twimg.com/profile_banners/11348282/1518798395",
                "profile_link_color": "205BA7",
                "profile_sidebar_border_color": "000000",
                "profile_sidebar_fill_color": "F3F2F2",
                "profile_text_color": "000000",
                "profile_use_background_image": true,
                "has_extended_profile": true,
                "default_profile": false,
                "default_profile_image": false,
                "following": null,
                "follow_request_sent": null,
                "notifications": null,
                "translator_type": "regular"
            },
            "geo": null,
            "coordinates": null,
            "place": null,
            "contributors": null,
            "is_quote_status": false,
            "retweet_count": 2654,
            "favorite_count": 7962,
            "favorited": false,
            "retweeted": false,
            "possibly_sensitive": false,
            "lang": "en"
        },
        {
            "created_at": "Mon Feb 26 19:21:43 +0000 2018",
            "id": 968204446625869827,
            "id_str": "968204446625869827",
            "text": "Someone's got to be first. In space, the first explorers beyond Mars were Pioneers 10 and 11, twin robots who chart… https://t.co/SUX30Y45mr",
            "truncated": true,
            "entities": {
                "hashtags": [],
                "symbols": [],
                "user_mentions": [],
                "urls": [
                    {
                        "url": "https://t.co/SUX30Y45mr",
                        "expanded_url": "https://twitter.com/i/web/status/968204446625869827",
                        "display_url": "twitter.com/i/web/status/9…",
                        "indices": [
                            117,
                            140
                        ]
                    }
                ]
            },
            "metadata": {
                "result_type": "popular",
                "iso_language_code": "en"
            },
            "source": "<a href='"https://www.sprinklr.com"' rel='"nofollow"'>Sprinklr</a>",
            "in_reply_to_status_id": null,
            "in_reply_to_status_id_str": null,
            "in_reply_to_user_id": null,
            "in_reply_to_user_id_str": null,
            "in_reply_to_screen_name": null,
            "user": {
                "id": 11348282,
                "id_str": "11348282",
                "name": "NASA",
                "screen_name": "NASA",
                "location": "",
                "description": "Explore the universe and discover our home planet with @NASA. We usually post in EST (UTC-5)",
                "url": "https://t.co/TcEE6NS8nD",
                "entities": {
                    "url": {
                        "urls": [
                            {
                                "url": "https://t.co/TcEE6NS8nD",
                                "expanded_url": "http://www.nasa.gov",
                                "display_url": "nasa.gov",
                                "indices": [
                                    0,
                                    23
                                ]
                            }
                        ]
                    },
                    "description": {
                        "urls": []
                    }
                },
                "protected": false,
                "followers_count": 28605561,
                "friends_count": 270,
                "listed_count": 90405,
                "created_at": "Wed Dec 19 20:20:32 +0000 2007",
                "favourites_count": 2960,
                "utc_offset": -18000,
                "time_zone": "Eastern Time (US & Canada)",
                "geo_enabled": false,
                "verified": true,
                "statuses_count": 50713,
                "lang": "en",
                "contributors_enabled": false,
                "is_translator": false,
                "is_translation_enabled": false,
                "profile_background_color": "000000",
                "profile_background_image_url": "http://pbs.twimg.com/profile_background_images/590922434682880000/3byPYvqe.jpg",
                "profile_background_image_url_https": "https://pbs.twimg.com/profile_background_images/590922434682880000/3byPYvqe.jpg",
                "profile_background_tile": false,
                "profile_image_url": "http://pbs.twimg.com/profile_images/188302352/nasalogo_twitter_normal.jpg",
                "profile_image_url_https": "https://pbs.twimg.com/profile_images/188302352/nasalogo_twitter_normal.jpg",
                "profile_banner_url": "https://pbs.twimg.com/profile_banners/11348282/1518798395",
                "profile_link_color": "205BA7",
                "profile_sidebar_border_color": "000000",
                "profile_sidebar_fill_color": "F3F2F2",
                "profile_text_color": "000000",
                "profile_use_background_image": true,
                "has_extended_profile": true,
                "default_profile": false,
                "default_profile_image": false,
                "following": null,
                "follow_request_sent": null,
                "notifications": null,
                "translator_type": "regular"
            },
            "geo": null,
            "coordinates": null,
            "place": null,
            "contributors": null,
            "is_quote_status": false,
            "retweet_count": 729,
            "favorite_count": 2777,
            "favorited": false,
            "retweeted": false,
            "possibly_sensitive": false,
            "lang": "en"
        },
        {
            "created_at": "Mon Feb 26 06:42:50 +0000 2018",
            "id": 968013469743288321,
            "id_str": "968013469743288321",
            "text": "宇宙ステーションでも、日本と9時間の時差で月曜日が始まりました。n今週は6人から3人にクルーのサイズダウンがありますが、しっかりと任されているタスクをこなしたいと思います。nn写真は、NASAの実験施設「ディスティニー」のグローブ… https://t.co/2CYoPV6Aqx",
            "truncated": true,
            "entities": {
                "hashtags": [],
                "symbols": [],
                "user_mentions": [],
                "urls": [
                    {
                        "url": "https://t.co/2CYoPV6Aqx",
                        "expanded_url": "https://twitter.com/i/web/status/968013469743288321",
                        "display_url": "twitter.com/i/web/status/9…",
                        "indices": [
                            117,
                            140
                        ]
                    }
                ]
            },
            "metadata": {
                "result_type": "popular",
                "iso_language_code": "ja"
            },
            "source": "<a href='"http://twitter.com"' rel='"nofollow"'>Twitter Web Client</a>",
            "in_reply_to_status_id": null,
            "in_reply_to_status_id_str": null,
            "in_reply_to_user_id": null,
            "in_reply_to_user_id_str": null,
            "in_reply_to_screen_name": null,
            "user": {
                "id": 842625693733203968,
                "id_str": "842625693733203968",
                "name": "金井 宣茂",
                "screen_name": "Astro_Kanai",
                "location": "",
                "description": "宇宙飛行士。2017年12月19日から国際宇宙ステーションに長期滞在中。 応援いただいているフォロワーのみなさまと一緒に、宇宙滞在を楽しみたいと思います!",
                "url": "https://t.co/rWU6cxY9iL",
                "entities": {
                    "url": {
                        "urls": [
                            {
                                "url": "https://t.co/rWU6cxY9iL",
                                "expanded_url": "https://ameblo.jp/astro-kanai/",
                                "display_url": "ameblo.jp/astro-kanai/",
                                "indices": [
                                    0,
                                    23
                                ]
                            }
                        ]
                    },
                    "description": {
                        "urls": []
                    }
                },
                "protected": false,
                "followers_count": 51512,
                "friends_count": 59,
                "listed_count": 655,
                "created_at": "Fri Mar 17 06:36:35 +0000 2017",
                "favourites_count": 7075,
                "utc_offset": 32400,
                "time_zone": "Tokyo",
                "geo_enabled": false,
                "verified": true,
                "statuses_count": 1035,
                "lang": "ja",
                "contributors_enabled": false,
                "is_translator": false,
                "is_translation_enabled": false,
                "profile_background_color": "000000",
                "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png",
                "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png",
                "profile_background_tile": false,
                "profile_image_url": "http://pbs.twimg.com/profile_images/879071738625232901/u0nlrr4Y_normal.jpg",
                "profile_image_url_https": "https://pbs.twimg.com/profile_images/879071738625232901/u0nlrr4Y_normal.jpg",
                "profile_banner_url": "https://pbs.twimg.com/profile_banners/842625693733203968/1492509582",
                "profile_link_color": "E81C4F",
                "profile_sidebar_border_color": "000000",
                "profile_sidebar_fill_color": "000000",
                "profile_text_color": "000000",
                "profile_use_background_image": false,
                "has_extended_profile": true,
                "default_profile": false,
                "default_profile_image": false,
                "following": null,
                "follow_request_sent": null,
                "notifications": null,
                "translator_type": "none"
            },
            "geo": null,
            "coordinates": null,
            "place": null,
            "contributors": null,
            "is_quote_status": false,
            "retweet_count": 226,
            "favorite_count": 1356,
            "favorited": false,
            "retweeted": false,
            "possibly_sensitive": false,
            "lang": "ja"
        },
        {
            "created_at": "Mon Feb 26 01:07:05 +0000 2018",
            "id": 967928974960545793,
            "id_str": "967928974960545793",
            "text": "Congratulations to #Olympics athletes who won gold! Neutron stars like the one at the heart of the Crab Nebula may… https://t.co/vz4SnPupe2",
            "truncated": true,
            "entities": {
                "hashtags": [
                    {
                        "text": "Olympics",
                        "indices": [
                            19,
                            28
                        ]
                    }
                ],
                "symbols": [],
                "user_mentions": [],
                "urls": [
                    {
                        "url": "https://t.co/vz4SnPupe2",
                        "expanded_url": "https://twitter.com/i/web/status/967928974960545793",
                        "display_url": "twitter.com/i/web/status/9…",
                        "indices": [
                            116,
                            139
                        ]
                    }
                ]
            },
            "metadata": {
                "result_type": "popular",
                "iso_language_code": "en"
            },
            "source": "<a href='"https://studio.twitter.com"' rel='"nofollow"'>Media Studio</a>",
            "in_reply_to_status_id": null,
            "in_reply_to_status_id_str": null,
            "in_reply_to_user_id": null,
            "in_reply_to_user_id_str": null,
            "in_reply_to_screen_name": null,
            "user": {
                "id": 19802879,
                "id_str": "19802879",
                "name": "NASA JPL",
                "screen_name": "NASAJPL",
                "location": "Pasadena, Calif.",
                "description": "NASA Jet Propulsion Laboratory manages many of NASA's robotic missions exploring Earth, the solar system and our universe. Tweets from JPL's News Office.",
                "url": "http://t.co/gcM9d1YLUB",
                "entities": {
                    "url": {
                        "urls": [
                            {
                                "url": "http://t.co/gcM9d1YLUB",
                                "expanded_url": "http://www.jpl.nasa.gov",
                                "display_url": "jpl.nasa.gov",
                                "indices": [
                                    0,
                                    22
                                ]
                            }
                        ]
                    },
                    "description": {
                        "urls": []
                    }
                },
                "protected": false,
                "followers_count": 2566921,
                "friends_count": 379,
                "listed_count": 15065,
                "created_at": "Sat Jan 31 03:19:43 +0000 2009",
                "favourites_count": 1281,
                "utc_offset": -32400,
                "time_zone": "Alaska",
                "geo_enabled": false,
                "verified": true,
                "statuses_count": 6328,
                "lang": "en",
                "contributors_enabled": false,
                "is_translator": false,
                "is_translation_enabled": false,
                "profile_background_color": "0B090B",
                "profile_background_image_url": "http://pbs.twimg.com/profile_background_images/8479565/twitter_jpl_bkg.009.jpg",
                "profile_background_image_url_https": "https://pbs.twimg.com/profile_background_images/8479565/twitter_jpl_bkg.009.jpg",
                "profile_background_tile": false,
                "profile_image_url": "http://pbs.twimg.com/profile_images/2305452633/lg0hov3l8g4msxbdwv48_normal.jpeg",
                "profile_image_url_https": "https://pbs.twimg.com/profile_images/2305452633/lg0hov3l8g4msxbdwv48_normal.jpeg",
                "profile_banner_url": "https://pbs.twimg.com/profile_banners/19802879/1398298134",
                "profile_link_color": "0D1787",
                "profile_sidebar_border_color": "100F0E",
                "profile_sidebar_fill_color": "74A6CD",
                "profile_text_color": "0C0C0D",
                "profile_use_background_image": true,
                "has_extended_profile": false,
                "default_profile": false,
                "default_profile_image": false,
                "following": null,
                "follow_request_sent": null,
                "notifications": null,
                "translator_type": "none"
            },
            "geo": null,
            "coordinates": null,
            "place": null,
            "contributors": null,
            "is_quote_status": false,
            "retweet_count": 325,
            "favorite_count": 1280,
            "favorited": false,
            "retweeted": false,
            "possibly_sensitive": false,
            "lang": "en"
        }
    ],
    "search_metadata": {
        "completed_in": 0.057,
        "max_id": 0,
        "max_id_str": "0",
        "next_results": "?max_id=967574182522482687&q=nasa&include_entities=1&result_type=popular",
        "query": "nasa",
        "count": 3,
        "since_id": 0,
        "since_id_str": "0"
    }
}

Please note that "count" was previously "results_per_page".