tweets

Documentation

Overview

Package tweets supports queries for tweet lookup and search.

Lookup

To look up one or more tweets by ID, use tweets.Lookup. Additional IDs can be given in the options:

single := tweets.Lookup(id, nil)
multi := tweets.Lookup(id1, &tweets.LookupOpts{
   More: []string{id2, id3},
})

By default only the default fields are returned (see types.Tweet). To request additional fields or expansions, include them in the options:

q := tweets.Lookup(id, &tweets.LookupOpts{
   Optional: []types.Fields{
      types.TweetFields{AuthorID: true, PublicMetrics: true},
      types.MediaFields{Duration: true},
      types.Expansions{types.Expand_AuthorID},
   },
})

Invoke the query to fetch the tweets:

rsp, err := q.Invoke(ctx, cli)

The Tweets field of the response contains the requested tweets. In addition, any attachments resulting from expansions can be fetched using methods on the *Reply, e.g., rsp.IncludedTweets. Note that tweet IDs that could not be found or accessed (e.g., for deleted or protected tweets) are not reported as an error. Instead. the caller should examine the ErrorDetail messages in the Errors field of the Reply, if requested tweets are not listed.

Search

To search recent tweets, use tweets.SearchRecent:

q := tweets.SearchRecent(`from:jack has:mentions -has:media`, nil)

For search query syntax, see https://developer.twitter.com/en/docs/twitter-api/tweets/search/integrate/build-a-rule

Search results can be paginated. Specifically, if there are more results available than the requested cap (max_results), the server response will contain a pagination token that can be used to fetch more. Invoking a search query automatically updates the query with this pagination token, so invoking the query again will fetch the remaining results:

for q.HasMorePages() {
   rsp, err := q.Invoke(ctx, cli)
   // ...
}

Use q.ResetPageToken to reset the query.

Streaming

Streaming queries take a callback that receives each response sent by the server. Streaming continues as long as there are more results, or until the callback reports an error. The tweets.SearchStream and tweets.SampleStream functions use this interface.

For example:

q := tweets.SearchStream(func(rsp *tweets.Reply) error {
   handle(rsp)
   if !wantMore() {
      return jape.ErrStopStreaming
   }
   return nil
}, nil)

If the callback returns jape.ErrStopStreaming, the stream is terminated without error; otherwise the error returned by the callback is reported to the caller of the query. For the common and simple case of limiting the number of results, you can use the MaxResults stream option.

Expansions and non-default fields can be requested using *StreamOpts:

opts := &tweets.StreamOpts{
   Optional: []types.Fields{
      types.Expansions{types.Expand_MediaKeys},
      types.MediaFields{PublicMetrics: true},
   },
}

Index

• type Callback
• type CreateOpts
• type ListOpts
• type LookupOpts
• type Query
  • func BookmarkedBy(userID string, opts *ListOpts) Query
  • func Create(opts CreateOpts) Query
  • func FromUser(userID string, opts *ListOpts) Query
  • func LikedBy(userID string, opts *ListOpts) Query
  • func Lookup(id string, opts *LookupOpts) Query
  • func MentioningUser(userID string, opts *ListOpts) Query
  • func Quotes(id string, opts *ListOpts) Query
  • func SearchRecent(query string, opts *SearchOpts) Query
  • func (q Query) HasMorePages() bool
  • func (q Query) Invoke(ctx context.Context, cli *twitter.Client) (*Reply, error)
  • func (q Query) ResetPageToken()
• type Reply
• type SearchOpts
• type Stream
  • func SampleStream(f Callback, opts *StreamOpts) Stream
  • func SearchStream(f Callback, opts *StreamOpts) Stream
  • func (s Stream) Invoke(ctx context.Context, cli *twitter.Client) error
• type StreamOpts

Types

type Callback

type Callback func(*Reply) error

A Callback receives streaming replies from a sample or streaming search query. If the callback returns an error, the stream is terminated. If the error is not jape.ErrStopStreaming, that error is reported to the caller.

type CreateOpts

type CreateOpts struct {
	Text         string        // the text of the tweet (required)
	QuoteOf      string        // the ID of a tweet to quote
	InReplyTo    string        // the ID of a tweet to reply to
	PollOptions  []string      // options to create a poll (if non-empty)
	PollDuration time.Duration // poll duration (required with poll options)
}

CreateOpts are the settings needed to create a new tweet.

type ListOpts

type ListOpts struct {
	// A pagination token provided by the server.
	PageToken string

	// The maximum number of results to return; 0 means let the server choose.
	// The service will accept values up to 100.
	MaxResults int

	// Optional response fields and expansions.
	Optional []types.Fields
}

ListOpts provide parameters for listing tweets. A nil *ListOpts provides empty values for all fields.

type LookupOpts

type LookupOpts struct {
	More      []string       // additional tweet IDs to query
	PageToken string         // a pagination token
	Optional  []types.Fields // optional response fields, expansions
}

LookupOpts provides parameters for tweet lookup. A nil *LookupOpts provides empty values for all fields.

type Query

type Query struct {
	*jape.Request
	// contains filtered or unexported fields
}

A Query performs a lookup or search query.

func BookmarkedBy

func BookmarkedBy(userID string, opts *ListOpts) Query

BookmarkedBy constructs a query for tweets bookmarked by the given user ID.

API: 2/users/:id/bookmarks

func Create

func Create(opts CreateOpts) Query

Create constructs a query to create a new tweet from the given settings.

API: POST 2/tweets

func FromUser

func FromUser(userID string, opts *ListOpts) Query

FromUser constructs a query for tweets posted by the given user ID.

API: 2/users/:id/tweets

func LikedBy

func LikedBy(userID string, opts *ListOpts) Query

LikedBy constructs a query for the tweets liked by a given user.

API: 2/users/:id/liked_tweets

func Lookup

func Lookup(id string, opts *LookupOpts) Query

Lookup constructs a lookup query for one or more tweet IDs. To look up multiple IDs, add subsequent values the opts.More field.

API: 2/tweets

func MentioningUser

func MentioningUser(userID string, opts *ListOpts) Query

MentioningUser constructs a query for tweets that mention the given user ID.

API: 2/users/:id/mentions

func Quotes

func Quotes(id string, opts *ListOpts) Query

Quotes consstructs a query for the quotes of a given tweet ID.

API: 2/tweets/:id/quote_tweets

func SearchRecent

func SearchRecent(query string, opts *SearchOpts) Query

SearchRecent conducts a search query on recent tweets matching the specified query filter.

For query syntax, see https://developer.twitter.com/en/docs/twitter-api/tweets/search/integrate/build-a-rule

API: 2/tweets/search/recent

func (Query) HasMorePages

func (q Query) HasMorePages() bool

HasMorePages reports whether the query has more pages to fetch. This is true for a freshly-constructed query, and for an invoked query where the server has not reported a next-page token.

func (Query) Invoke

func (q Query) Invoke(ctx context.Context, cli *twitter.Client) (*Reply, error)

Invoke executes the query on the given context and client. If the reply contains a pagination token, q is updated in-place so that invoking the query again will fetch the next page.

func (Query) ResetPageToken

func (q Query) ResetPageToken()

ResetPageToken clears (resets) the query's current page token. Subsequently invoking the query will then fetch the first page of results.

type Reply

type Reply struct {
	*twitter.Reply
	Tweets types.Tweets
	Meta   *twitter.Pagination
}

A Reply is the response from a Query.

type SearchOpts

type SearchOpts struct {
	// A pagination token provided by the server.
	PageToken string

	// The oldest UTC time from which results will be provided.
	StartTime time.Time

	// The latest (most recent) UTC time to which results will be provided.
	EndTime time.Time

	// The maximum number of results to return; 0 means let the server choose.
	// Non-zero values < 10 or > 100 are invalid.
	MaxResults int

	// If set, return results with IDs greater than this (exclusive).
	SinceID string

	// If set, return results with IDs smaller than this (exclusive).
	UntilID string

	// Optional response fields and expansions
	Optional []types.Fields
}

SearchOpts provides parameters for tweet search. A nil *SearchOpts provides empty or zero values for all fields.

type Stream

type Stream struct {
	*jape.Request
	// contains filtered or unexported fields
}

A Stream performs a streaming search or sampling query.

func SampleStream

func SampleStream(f Callback, opts *StreamOpts) Stream

SampleStream constructs a streaming sample query that delivers results to f.

API: 2/tweets/sample/stream

func SearchStream

func SearchStream(f Callback, opts *StreamOpts) Stream

SearchStream constructs a streaming search query that delivers results to f.

API: 2/tweets/search/stream

func (Stream) Invoke

func (s Stream) Invoke(ctx context.Context, cli *twitter.Client) error

Invoke executes the streaming query on the given context and client.

type StreamOpts

type StreamOpts struct {
	// If positive, stop streaming after this many results have been reported.
	MaxResults int

	// Optional response fields and expansions.
	Optional []types.Fields
}

StreamOpts provides parameters for tweet streaming. A nil *StreamOpts provides empty values for all fields.