Module: Twitter::REST::API::Timelines

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

Constant Summary collapse

DEFAULT_TWEETS_PER_REQUEST = 
20
MAX_TWEETS_PER_REQUEST = 
200

Constants included from Utils

Utils::DEFAULT_CURSOR, Utils::URI_SUBSTRING

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

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



114
115
116
 
# File 'lib/twitter/rest/api/timelines.rb', line 114

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

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



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

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

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



91
92
93
94
95
 
# File 'lib/twitter/rest/api/timelines.rb', line 91

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

Parameters:

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

    A Twitter user ID, screen name, URI, 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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



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

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.

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



134
135
136
137
138
 
# File 'lib/twitter/rest/api/timelines.rb', line 134

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

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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



154
155
156
 
# File 'lib/twitter/rest/api/timelines.rb', line 154

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

Parameters:

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

    A Twitter user ID, screen name, URI, 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:

Rate Limited?:

  • Yes

Authentication:

  • Requires user context



49
50
51
 
# File 'lib/twitter/rest/api/timelines.rb', line 49

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