<< Back to Twitter API Documentation

users/search

Run a search for users similar to Find People button on Twitter.com; the same results returned by people search on Twitter.com will be returned by using this API (about being listed in the People Search).  It is only possible to retrieve the first 1000 matches from this API.

method status | report a bug

URL:

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

Formats: 

xml, json

HTTP Method(s):

GET

Requires Authentication (about authentication):

true (see usage notes)

API rate limited (about rate limiting):

1 call per request and up to 60 calls per hour

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 method 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.

Parameters:

The following is required:

• q.  Required. The query to run against people search. 
• Example: http://api.twitter.com/1/users/search.xml?q=Doug%20Williams
• per_page.  Optional.  Specifies the number of statuses to retrieve. May not be greater than 20. 
• Example: http://api.twitter.com/1/users/search.xml?q=Doug%20Williams&per_page=5 

• page. Optional. Specifies the page of results to retrieve.

• Example: http://api.twitter.com/1/users/search.xml?q=Doug%20Williams&page=3 

Response (about return values): 

          XML example (truncated):

<?xml version="1.0" encoding="UTF-8"?>

<users>

<user>

<id>1401881</id>

<name>Doug Williams</name>

<screen_name>dougw</screen_name>

<location>San Francisco, CA</location>

<description>Twitter API Support. Internet, greed, users, dougw and opportunities are my passions.</description>

<profile_image_url>http://s3.amazonaws.com/twitter_production/profile_images/59648642/avatar_normal.png</profile_image_url>

<url>http://www.igudo.com</url>

<protected>false</protected>

<followers_count>1031</followers_count>

<profile_background_color>9ae4e8</profile_background_color>

<profile_text_color>000000</profile_text_color>

<profile_link_color>0000ff</profile_link_color>

<profile_sidebar_fill_color>e0ff92</profile_sidebar_fill_color>

<profile_sidebar_border_color>87bc44</profile_sidebar_border_color>

<friends_count>293</friends_count>

<created_at>Sun Mar 18 06:42:26 +0000 2007</created_at>

<favourites_count>0</favourites_count>

<utc_offset>-18000</utc_offset>

<time_zone>Eastern Time (US & Canada)</time_zone>

<profile_background_image_url>http://s3.amazonaws.com/twitter_production/profile_background_images/2752608/twitter_bg_grass.jpg</profile_background_image_url>

<profile_background_tile>false</profile_background_tile>

<statuses_count>3390</statuses_count>

<notifications>false</notifications>

<following>false</following>

<verified>true</verified>

<status>

<created_at>Tue Apr 07 22:52:51 +0000 2009</created_at>

<id>1472669360</id>

<text>At least I can get your humor through tweets. RT @abdur: I don't mean this in a bad way, but genetically speaking you're a cul-de-sac.</text>

<source><a href="http://www.tweetdeck.com/">TweetDeck</a></source>

<truncated>false</truncated>

<in_reply_to_status_id></in_reply_to_status_id>

<in_reply_to_user_id></in_reply_to_user_id>

<favorited>false</favorited>

<in_reply_to_screen_name></in_reply_to_screen_name>

</status>

</user>

...

</users> 

Usage examples: 

cURL (about cURL):

curl -u user:password http://api.twitter.com/1/users/search.xml?q=Doug%20Williams

          Do you have an example to share in the language of your choice? Please share!

<< Back to Twitter API Documentation