Module: Twitter::Client::Timelines

Included in:
Twitter::Client
Defined in:
lib/twitter/client/timelines.rb

Overview

Defines methods related to timelines

Instance Method Summary collapse

Instance Method Details

#home_timeline(options = {}) ⇒ Array<Twitter::Status>

Note:

This method can only return up to 800 statuses, including retweets.

Returns the 20 most recent statuses, including retweets if they exist, posted by the authenticating user and the users they follow

Examples:

Return the 20 most recent statuses, including retweets if they exist, posted by the authenticating user and the users they follow

Twitter.home_timeline

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :page (Integer) —

    Specifies the page of results to retrieve.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, ‘t’ or 1.

  • :exclude_replies (Boolean, String, Integer) —

    This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets — this is because the count parameter retrieves that many tweets before filtering out retweets and replies.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • Yes



27
28
29
30
31
 
# File 'lib/twitter/client/timelines.rb', line 27

def home_timeline(options={})
  get("/1/statuses/home_timeline.json", options).map do |status|
    Twitter::Status.new(status)
  end
end

#media_timeline(user, options = {}) ⇒ Array<Twitter::Status>

Note:

This method can only return up to the 100 most recent images.

Note:

Images will not be returned from tweets posted before January 1, 2010.

Returns the 20 most recent images posted by the specified user

Examples:

Return the 20 most recent statuses posted by @sferik

Twitter.media_timeline("sferik")

Parameters:

  • user (Integer, String) —

    A Twitter user ID or screen name.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :page (Integer) —

    Specifies the page of results to retrieve.

  • :filter (Boolean) —

    Include possibly sensitive media when set to false, ‘f’ or 0.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, ‘t’ or 1.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No unless the user whose timeline you’re trying to view is protected



230
231
232
233
234
235
236
237
238
 
# File 'lib/twitter/client/timelines.rb', line 230

def media_timeline(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  if user = args.pop
    options.merge_user!(user)
  end
  get("/1/statuses/media_timeline.json", options).map do |status|
    Twitter::Status.new(status)
  end
end

#mentions(options = {}) ⇒ Array<Twitter::Status>

Note:

This method can only return up to 800 statuses. If the :include_rts option is set, only 800 statuses, including retweets if they exist, can be returned.

Returns the 20 most recent mentions (statuses containing @username) for the authenticating user

Examples:

Return the 20 most recent mentions (statuses containing @username) for the authenticating user

Twitter.mentions

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :page (Integer) —

    Specifies the page of results to retrieve.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :include_rts (Boolean, String, Integer) —

    The timeline will contain native retweets (if they exist) in addition to the standard stream of tweets when set to true, ‘t’ or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • Yes



51
52
53
54
55
 
# File 'lib/twitter/client/timelines.rb', line 51

def mentions(options={})
  get("/1/statuses/mentions.json", options).map do |status|
    Twitter::Status.new(status)
  end
end

#network_timeline(options = {}) ⇒ Array<Twitter::Status>

Note:

Undocumented

Returns the 20 most recent statuses from the authenticating user’s network

Examples:

Return the 20 most recent statuses from the authenticating user’s network

Twitter.network_timeline

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :page (Integer) —

    Specifies the page of results to retrieve.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, ‘t’ or 1.

  • :exclude_replies (Boolean, String, Integer) —

    This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets — this is because the count parameter retrieves that many tweets before filtering out retweets and replies.

Returns:

Raises:

Rate Limited?:

  • Yes

Requires Authentication?:

  • Yes



257
258
259
260
261
 
# File 'lib/twitter/client/timelines.rb', line 257

def network_timeline(options={})
  get("/i/statuses/network_timeline.json", options).map do |status|
    Twitter::Status.new(status)
  end
end

#public_timeline(options = {}) ⇒ Array<Twitter::Status>

Note:

The public timeline is cached for 60 seconds. Requesting more frequently than that will not return any more data, and will count against your rate limit usage.

Returns the 20 most recent statuses, including retweets if they exist, from non-protected users

Examples:

Return the 20 most recent statuses, including retweets if they exist, from non-protected users

Twitter.public_timeline

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, ‘t’ or 1.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No



69
70
71
72
73
 
# File 'lib/twitter/client/timelines.rb', line 69

def public_timeline(options={})
  get("/1/statuses/public_timeline.json", options).map do |status|
    Twitter::Status.new(status)
  end
end

#retweeted_by(options = {}) ⇒ Array<Twitter::Status> #retweeted_by(user, options = {}) ⇒ Array<Twitter::Status>

Returns the 20 most recent retweets posted by the specified user

Overloads:

  • #retweeted_by(options = {}) ⇒ Array<Twitter::Status>

    Examples:

    Return the 20 most recent retweets posted by the authenticating user

    Twitter.retweeted_by("sferik")

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :since_id (Integer) —

      Returns results with an ID greater than (that is, more recent than) the specified ID.

    • :max_id (Integer) —

      Returns results with an ID less than (that is, older than) or equal to the specified ID.

    • :count (Integer) —

      Specifies the number of records to retrieve. Must be less than or equal to 200.

    • :page (Integer) —

      Specifies the page of results to retrieve.

    • :trim_user (Boolean, String, Integer) —

      Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

    • :include_entities (Boolean, String, Integer) —

      Include Tweet Entities when set to true, ‘t’ or 1.

    Returns:

    Raises:

  • #retweeted_by(user, options = {}) ⇒ Array<Twitter::Status>

    Examples:

    Return the 20 most recent retweets posted by the authenticating user

    Twitter.retweeted_by

    Parameters:

    • user (Integer, String) —

      A Twitter user ID or screen name.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :since_id (Integer) —

      Returns results with an ID greater than (that is, more recent than) the specified ID.

    • :max_id (Integer) —

      Returns results with an ID less than (that is, older than) or equal to the specified ID.

    • :count (Integer) —

      Specifies the number of records to retrieve. Must be less than or equal to 200.

    • :page (Integer) —

      Specifies the page of results to retrieve.

    • :trim_user (Boolean, String, Integer) —

      Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

    • :include_entities (Boolean, String, Integer) —

      Include Tweet Entities when set to true, ‘t’ or 1.

    Returns:

    Raises:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • Supported



106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/twitter/client/timelines.rb', line 106

def retweeted_by(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  if user = args.pop
    options.merge_user!(user)
    get("/1/statuses/retweeted_by_user.json", options)
  else
    get("/1/statuses/retweeted_by_me.json", options)
  end.map do |status|
    Twitter::Status.new(status)
  end
end

#retweeted_to(options = {}) ⇒ Array<Twitter::Status> #retweeted_to(user, options = {}) ⇒ Array<Twitter::Status>

Returns the 20 most recent retweets posted by users the specified user follows

Overloads:

  • #retweeted_to(options = {}) ⇒ Array<Twitter::Status>

    Examples:

    Return the 20 most recent retweets posted by users followed by the authenticating user

    Twitter.retweeted_to

    Parameters:

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :since_id (Integer) —

      Returns results with an ID greater than (that is, more recent than) the specified ID.

    • :max_id (Integer) —

      Returns results with an ID less than (that is, older than) or equal to the specified ID.

    • :count (Integer) —

      Specifies the number of records to retrieve. Must be less than or equal to 200.

    • :page (Integer) —

      Specifies the page of results to retrieve.

    • :trim_user (Boolean, String, Integer) —

      Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

    • :include_entities (Boolean, String, Integer) —

      Include Tweet Entities when set to true, ‘t’ or 1.

    Returns:

    Raises:

  • #retweeted_to(user, options = {}) ⇒ Array<Twitter::Status>

    Examples:

    Return the 20 most recent retweets posted by users followed by the authenticating user

    Twitter.retweeted_to("sferik")

    Parameters:

    • user (Integer, String) —

      A Twitter user ID or screen name.

    • options (Hash) (defaults to: {}) —

      A customizable set of options.

    Options Hash (options):

    • :since_id (Integer) —

      Returns results with an ID greater than (that is, more recent than) the specified ID.

    • :max_id (Integer) —

      Returns results with an ID less than (that is, older than) or equal to the specified ID.

    • :count (Integer) —

      Specifies the number of records to retrieve. Must be less than or equal to 200.

    • :page (Integer) —

      Specifies the page of results to retrieve.

    • :trim_user (Boolean, String, Integer) —

      Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

    • :include_entities (Boolean, String, Integer) —

      Include Tweet Entities when set to true, ‘t’ or 1.

    Returns:

    Raises:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • Supported



149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/twitter/client/timelines.rb', line 149

def retweeted_to(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  if user = args.pop
    options.merge_user!(user)
    get("/1/statuses/retweeted_to_user.json", options)
  else
    get("/1/statuses/retweeted_to_me.json", options)
  end.map do |status|
    Twitter::Status.new(status)
  end
end

#retweets_of_me(options = {}) ⇒ Array<Twitter::Status>

Returns the 20 most recent tweets of the authenticated user that have been retweeted by others

Examples:

Return the 20 most recent tweets of the authenticated user that have been retweeted by others

Twitter.retweets_of_me

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :page (Integer) —

    Specifies the page of results to retrieve.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, ‘t’ or 1.

Returns:

Raises:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • Yes



177
178
179
180
181
 
# File 'lib/twitter/client/timelines.rb', line 177

def retweets_of_me(options={})
  get("/1/statuses/retweets_of_me.json", options).map do |status|
    Twitter::Status.new(status)
  end
end

#user_timeline(user, options = {}) ⇒ Array<Twitter::Status>

Note:

This method can only return up to 3200 statuses. If the :include_rts option is set, only 3200 statuses, including retweets if they exist, can be returned.

Returns the 20 most recent statuses posted by the specified user

Examples:

Return the 20 most recent statuses posted by @sferik

Twitter.user_timeline("sferik")

Parameters:

  • user (Integer, String) —

    A Twitter user ID or screen name.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since_id (Integer) —

    Returns results with an ID greater than (that is, more recent than) the specified ID.

  • :max_id (Integer) —

    Returns results with an ID less than (that is, older than) or equal to the specified ID.

  • :count (Integer) —

    Specifies the number of records to retrieve. Must be less than or equal to 200.

  • :page (Integer) —

    Specifies the page of results to retrieve.

  • :trim_user (Boolean, String, Integer) —

    Each tweet returned in a timeline will include a user object with only the author’s numerical ID when set to true, ‘t’ or 1.

  • :include_rts (Boolean, String, Integer) —

    The timeline will contain native retweets (if they exist) in addition to the standard stream of tweets when set to true, ‘t’ or 1.

  • :include_entities (Boolean, String, Integer) —

    Include Tweet Entities when set to true, ‘t’ or 1.

  • :exclude_replies (Boolean, String, Integer) —

    This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets — this is because the count parameter retrieves that many tweets before filtering out retweets and replies.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No unless the user whose timeline you’re trying to view is protected



203
204
205
206
207
208
209
210
211
 
# File 'lib/twitter/client/timelines.rb', line 203

def user_timeline(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  if user = args.pop
    options.merge_user!(user)
  end
  get("/1/statuses/user_timeline.json", options).map do |status|
    Twitter::Status.new(status)
  end
end