Module: Twitter::API::Timelines

Includes:
Utils
Included in:
Client
Defined in:
lib/twitter/api/timelines.rb

Constant Summary collapse

DEFAULT_TWEETS_PER_REQUEST = 
20
MAX_TWEETS_PER_REQUEST = 
200

Constants included from Utils

Utils::DEFAULT_CURSOR

Instance Method Summary collapse

Instance Method Details

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

Note:

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

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

Examples:

Return the 20 most recent Tweets, 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.

  • :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.

  • :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.

  • :include_rts (Boolean, String, Integer) —

    Specifies that the timeline should include native retweets in addition to regular tweets. Note: If you're using the trim_user parameter in conjunction with include_rts, the retweets will no longer contain a full user object.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

  • :include_entities (Boolean, String, Integer) —

    The tweet entities node will be disincluded when set to false.

Returns:

Raises:

See Also:

Authentication:

  • Requires user context

Rate Limited?:

  • Yes



123
124
125
 
# File 'lib/twitter/api/timelines.rb', line 123

def home_timeline(options={})
  objects_from_response(Twitter::Tweet, :get, "/1.1/statuses/home_timeline.json", options)
end

#mentions_timeline(options = {}) ⇒ Array<Twitter::Tweet> Also known as: mentions

Note:

This method can only return up to 800 Tweets.

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.

  • :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.

Returns:

Raises:

See Also:

Authentication:

  • Requires user context

Rate Limited?:

  • Yes



27
28
29
 
# File 'lib/twitter/api/timelines.rb', line 27

def mentions_timeline(options={})
  objects_from_response(Twitter::Tweet, :get, "/1.1/statuses/mentions_timeline.json", options)
end

#retweeted_by_me(options = {}) ⇒ Array<Twitter::Tweet>

Note:

This method can only return up to 3,200 Tweets.

Returns the 20 most recent retweets posted by the authenticating user

Examples:

Return the 20 most recent retweets posted by the authenticating user

Twitter.retweeted_by_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.

  • :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.

  • :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.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

Returns:

Raises:

See Also:

Authentication:

  • Requires user context

Rate Limited?:

  • Yes



98
99
100
101
102
 
# File 'lib/twitter/api/timelines.rb', line 98

def retweeted_by_me(options={})
  retweets_from_timeline(options) do |opts|
    user_timeline(opts)
  end
end

#retweeted_by_user(user, options = {}) ⇒ Array<Twitter::Tweet> Also known as: retweeted_by

Note:

This method can only return up to 3,200 Tweets.

Returns the 20 most recent retweets posted by the specified user

Examples:

Return the 20 most recent retweets posted by @sferik

Twitter.retweeted_by_user('sferik')

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, or object.

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

  • :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.

  • :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.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

Returns:

Raises:

See Also:

Authentication:

  • Requires user context

Rate Limited?:

  • Yes



74
75
76
77
78
 
# File 'lib/twitter/api/timelines.rb', line 74

def retweeted_by_user(user, options={})
  retweets_from_timeline(options) do |opts|
    user_timeline(user, opts)
  end
end

#retweeted_to_me(options = {}) ⇒ Array<Twitter::Tweet>

Note:

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

Returns the 20 most recent retweets posted by users the authenticating user follow.

Examples:

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

Twitter.retweeted_to_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.

  • :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.

  • :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.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

  • :include_entities (Boolean, String, Integer) —

    The tweet entities node will be disincluded when set to false.

Returns:

Raises:

See Also:

Authentication:

  • Requires user context

Rate Limited?:

  • Yes



145
146
147
148
149
 
# File 'lib/twitter/api/timelines.rb', line 145

def retweeted_to_me(options={})
  retweets_from_timeline(options) do |opts|
    home_timeline(opts)
  end
end

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

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):

  • :count (Integer) —

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

  • :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.

  • :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) —

    The tweet entities node will be disincluded when set to false.

  • :include_user_entities (Boolean, String, Integer) —

    The user entities node will be disincluded when set to false.

Returns:

Raises:

See Also:

Authentication:

  • Requires user context

Rate Limited?:

  • Yes



167
168
169
 
# File 'lib/twitter/api/timelines.rb', line 167

def retweets_of_me(options={})
  objects_from_response(Twitter::Tweet, :get, "/1.1/statuses/retweets_of_me.json", options)
end

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

Note:

This method can only return up to 3,200 Tweets.

Returns the 20 most recent Tweets posted by the specified user

Examples:

Return the 20 most recent Tweets posted by @sferik

Twitter.user_timeline('sferik')

Parameters:

  • user (Integer, String, Twitter::User) —

    A Twitter user ID, screen name, or object.

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

  • :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.

  • :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.

  • :contributor_details (Boolean, String, Integer) —

    Specifies that the contributors element should be enhanced to include the screen_name of the contributor.

  • :include_rts (Boolean, String, Integer) —

    Specifies that the timeline should include native retweets in addition to regular tweets. Note: If you're using the trim_user parameter in conjunction with include_rts, the retweets will no longer contain a full user object.

Returns:

Raises:

See Also:

Authentication:

  • Requires user context

Rate Limited?:

  • Yes



52
53
54
 
# File 'lib/twitter/api/timelines.rb', line 52

def user_timeline(*args)
  objects_from_response_with_user(Twitter::Tweet, :get, "/1.1/statuses/user_timeline.json", args)
end