Twitter REST API Method: statuses/home_timeline

Returns the 20 most recent statuses, including retweets, posted by the authenticating user and that user's friends. This is the equivalent of /timeline/home on the Web.

Usage note: This home_timeline is identical to statuses/friends_timeline except it also contains retweets, which statuses/friends_timeline does not (for backwards compatibility reasons). In a future version of the API, statuses/friends_timeline will go away and be replaced by home_timeline.

URL:

http://api.twitter.com/1/statuses/home_timeline.format

 

Formats: 

xml, json, atom 

 

HTTP Method(s):

GET

 

Requires Authentication (about authentication):

true

 

API rate limited (about rate limiting):

1 call per request

 

Parameters:

• since_id.  Optional.  Returns only statuses with an ID greater than (that is, more recent than) the specified ID. 
  • Example: http://api.twitter.com/1/statuses/home_timeline.xml?since_id=12345
• max_id. Optional.  Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.
  • Example: http://api.twitter.com/1/statuses/home_timeline.xml?max_id=54321
• count.  Optional.  Specifies the number of statuses to retrieve. May not be greater than 200. 
  • Example: http://api.twitter.com/1/statuses/home_timeline.xml?count=5 

• page. Optional. Specifies the page of results to retrieve. Note: there are pagination limits.

  • Example: http://api.twitter.com/1/statuses/home_timeline.xml?page=3

 

Response (about return values): 

XML example (truncated):

 

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

<statuses type="array">

<status>

  <created_at>Wed Nov 18 18:54:12 +0000 2009</created_at>

  <id>5833943856</id>

  <text>RT @peoplemag: New Moon director Chris Weitz says he's quitting movies after one more http://ow.ly/DrjQ</text>

  <source>web</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>

  <retweeted_status>

    <created_at>Wed Nov 18 18:36:34 +0000 2009</created_at>

    <id>5833513351</id>

    <text>New Moon director Chris Weitz says he's quitting movies after one more http://ow.ly/DrjQ</text>

    <source><a href="http://www.hootsuite.com" rel="nofollow">HootSuite</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>

    <user>

      <id>25589776</id>

      <name>People magazine</name>

      <screen_name>peoplemag</screen_name>

      <location></location>

      <description>PEOPLE.com is the No. 1 site for celebrity news!</description>

      <profile_image_url>http://a3.twimg.com/profile_images/116213891/people_73x73_normal.jpg</profile_image_url>

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

      <protected>false</protected>

      <followers_count>1653473</followers_count>

      <profile_background_color>08a9e7</profile_background_color>

      <profile_text_color>000000</profile_text_color>

      <profile_link_color>ee0077</profile_link_color>

      <profile_sidebar_fill_color>ffee9a</profile_sidebar_fill_color>

      <profile_sidebar_border_color>ffcc66</profile_sidebar_border_color>

      <friends_count>406</friends_count>

      <created_at>Fri Mar 20 22:30:24 +0000 2009</created_at>

      <favourites_count>2</favourites_count>

      <utc_offset>-18000</utc_offset>

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

      <profile_background_image_url>http://a1.twimg.com/profile_background_images/6859800/bgpage.gif</profile_background_image_url>

      <profile_background_tile>true</profile_background_tile>

      <statuses_count>1740</statuses_count>

      <notifications>false</notifications>

      <geo_enabled>false</geo_enabled>

      <verified>false</verified>

      <following>false</following>

    </user>

    <geo/>

  </retweeted_status>

  <user>

    <id>44940026</id>

    <name>Anita Doller</name>

    <screen_name>testiverse</screen_name>

    <location></location>

    <description></description>

    <profile_image_url>http://a3.twimg.com/profile_images/251164577/testing_normal.JPG</profile_image_url>

    <url></url>

    <protected>false</protected>

    <followers_count>14</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>25</friends_count>

    <created_at>Fri Jun 05 17:07:09 +0000 2009</created_at>

    <favourites_count>1</favourites_count>

    <utc_offset>-28800</utc_offset>

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

    <profile_background_image_url>http://s.twimg.com/a/1258507899/images/themes/theme1/bg.png</profile_background_image_url>

    <profile_background_tile>false</profile_background_tile>

    <statuses_count>14</statuses_count>

    <notifications>false</notifications>

    <geo_enabled>false</geo_enabled>

    <verified>false</verified>

    <following>true</following>

  </user>

  <geo/>

</status>

<status>

  <created_at>Wed Nov 18 18:53:17 +0000 2009</created_at>

  <id>5833921302</id>

  <text>Can't believe I didn't know about TextMate column-select. @macasek just showed me the power. Now I can't be stopped.</text>

  <source><a href="http://www.atebits.com/" rel="nofollow">Tweetie</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>

  <user>

    <id>364</id>

    <name>Mike Champion</name>

    <screen_name>graysky</screen_name>

    <location>Boston, MA</location>

    <description>Developer at @oneforty</description>

    <profile_image_url>http://a1.twimg.com/profile_images/72387934/me3_normal.jpg</profile_image_url>

    <url>http://graysky.org</url>

    <protected>false</protected>

    <followers_count>866</followers_count>

    <profile_background_color>2f2f2f</profile_background_color>

    <profile_text_color>2f2f2f</profile_text_color>

    <profile_link_color>599B4C</profile_link_color>

    <profile_sidebar_fill_color>FDFDFD</profile_sidebar_fill_color>

    <profile_sidebar_border_color>599B4C</profile_sidebar_border_color>

    <friends_count>387</friends_count>

    <created_at>Sat Jun 24 17:47:36 +0000 2006</created_at>

    <favourites_count>53</favourites_count>

    <utc_offset>-18000</utc_offset>

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

    <profile_background_image_url>http://a1.twimg.com/profile_background_images/332/mem_drive_large.jpg</profile_background_image_url>

    <profile_background_tile>false</profile_background_tile>

    <statuses_count>3489</statuses_count>

    <notifications>false</notifications>

    <geo_enabled>false</geo_enabled>

    <verified>false</verified>

    <following>false</following>

  </user>

  <geo/>

</status>

<!-- truncated -->

</statuses>

 

 

Usage examples: 

cURL (about cURL):

curl -u user:password http://api.twitter.com/1/statuses/home_timeline.xml

 

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