GET users/search

Updated on Wed, 2012-04-18 11:26

Runs a search for users similar to Find People button on Twitter.com. The results returned by people search on Twitter.com are the same as those returned by this API request. Note that unlike GET search, this method does not support any operators.

Only the first 1000 matches are available.

Resource URL

http://api.twitter.com/1/users/search.format

Parameters

q required

The search query to run against people search.

Example Values: Twitter%20API

page optional

Specifies the page of results to retrieve.

Example Values: 3

per_page optional

The number of people to retrieve. Maxiumum of 20 allowed per page.

Example Values: 5

include_entities optional

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 discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more detail on entities.

Example Values: true

Extended description

This method has a feature-specific rate limit of 60 calls per hour that is applied in conjunction with the main REST API rate limit. Calls to this method will count against the feature-specific rate limit and the main REST API rate limit. If either limit is exhausted, the request will fail. You can monitor the status of the feature-specific rate limit by inspecting the HTTP response headers X-FeatureRateLimit-Limit, X-FeatureRateLimit-Remaining, and X-FeatureRateLimit-Reset. These headers correspond to the X-RateLimit headers provided by the main REST API limit.

Example Request

GET

https://api.twitter.com/1/users/search.json?q=Twitter%20API

  1. [
  2.   {
  3.     "name": "Twitter API",
  4.     "profile_sidebar_border_color": "87bc44",
  5.     "profile_background_tile": false,
  6.     "profile_sidebar_fill_color": "e0ff92",
  7.     "location": "San Francisco, CA",
  8.     "profile_image_url": "http://a3.twimg.com/profile_images/689684365/api_normal.png",
  9.     "created_at": "Wed May 23 06:01:13 +0000 2007",
  10.     "profile_link_color": "0000ff",
  11.     "favourites_count": 2,
  12.     "url": "http://apiwiki.twitter.com",
  13.     "contributors_enabled": true,
  14.     "utc_offset": -28800,
  15.     "id": 6253282,
  16.     "profile_use_background_image": true,
  17.     "profile_text_color": "000000",
  18.     "protected": false,
  19.     "followers_count": 160753,
  20.     "lang": "en",
  21.     "verified": true,
  22.     "profile_background_color": "c1dfee",
  23.     "geo_enabled": true,
  24.     "notifications": null,
  25.     "description": "The Real Twitter API. I tweet about API changes, service issues and happily answer questions about Twitter and our API. Don't get an answer? It's on my website.",
  26.     "time_zone": "Pacific Time (US & Canada)",
  27.     "friends_count": 19,
  28.     "statuses_count": 1858,
  29.     "profile_background_image_url": "http://a3.twimg.com/profile_background_images/59931895/twitterapi-background-new.png",
  30.     "status": {
  31.       "coordinates": null,
  32.       "favorited": false,
  33.       "created_at": "Tue Jun 22 16:53:28 +0000 2010",
  34.       "truncated": false,
  35.       "text": "@Demonicpagan possible some part of your signature generation is incorrect & fails for real reasons.. follow up on the list if you suspect",
  36.       "contributors": null,
  37.       "id": 16783999399,
  38.       "geo": null,
  39.       "in_reply_to_user_id": 6339722,
  40.       "place": null,
  41.       "source": "<a href="http://www.tweetdeck.com" rel="nofollow">TweetDeck</a>",
  42.       "in_reply_to_screen_name": "Demonicpagan",
  43.       "in_reply_to_status_id": 16781827477
  44.     },
  45.     "screen_name": "twitterapi",
  46.     "following": null
  47.   },
  48.   ...
  49.   {
  50.     "name": "twitterAPI",
  51.     "profile_sidebar_border_color": "87bc44",
  52.     "profile_background_tile": false,
  53.     "profile_sidebar_fill_color": "e0ff92",
  54.     "location": null,
  55.     "profile_image_url": "http://s.twimg.com/a/1277162817/images/default_profile_6_normal.png",
  56.     "created_at": "Fri Jun 04 12:07:25 +0000 2010",
  57.     "profile_link_color": "0000ff",
  58.     "favourites_count": 0,
  59.     "url": null,
  60.     "contributors_enabled": false,
  61.     "utc_offset": null,
  62.     "id": 151851125,
  63.     "profile_use_background_image": true,
  64.     "profile_text_color": "000000",
  65.     "protected": false,
  66.     "followers_count": 0,
  67.     "lang": "ja",
  68.     "verified": false,
  69.     "profile_background_color": "9ae4e8",
  70.     "geo_enabled": false,
  71.     "notifications": false,
  72.     "description": null,
  73.     "time_zone": null,
  74.     "friends_count": 0,
  75.     "statuses_count": 0,
  76.     "profile_background_image_url": "http://s.twimg.com/a/1277162817/images/themes/theme1/bg.png",
  77.     "screen_name": "popoAPI",
  78.     "following": false
  79.   }
  80. ]