twitter

README

twitter

Note: It is no longer practical or worthwhile for me to continue work on this library, as Twitter now charges $100 per month for minimal API access. I have therefore archived the repository.

This repository provides Go package that implements an experimental client for the Twitter API v2. It is no longer under active development.

This was an experiment, and is not ready for production use. In particular, test coverage is not nearly as good as it should be. There are replay tests using responses captured from the production service, but a lot of invariants remain unverified.

The documentation could also use more work. All the packages and exported types have doc comments, but working examples are lacking. Normal test-based examples are tricky because there is not (as far as I know) a good test double for the API.

API Index

Here is the current status of v2 API endpoint implementations.

Edits

• DELETE 2/tweets/:id
• PUT 2/tweets/:id/hidden
• POST 2/users/:id/blocking
• DELETE 2/users/:id/blocking/:other
• POST 2/users/:id/bookmarks
• DELETE 2/users/:id/bookmarks/:tid
• POST 2/users/:id/following
• DELETE 2/users/:id/following/:other
• POST 2/users/:id/likes
• DELETE 2/users/:id/likes/:tid
• POST 2/users/:id/muting
• DELETE 2/users/:id/muting/:other
• POST 2/users/:id/pinned_lists
• DELETE 2/users/:id/pinned_lists/:lid
• POST 2/users/:id/retweets
• DELETE 2/users/:id/retweets/:tid

Lists

• GET 2/lists
• POST 2/lists
• DELETE 2/lists/:id
• PUT 2/lists/:id
• GET 2/lists/:id/followers
• GET 2/lists/:id/members
• POST 2/lists/:id/members
• DELETE 2/lists/:id/members/:userid
• GET 2/lists/:id/tweets
• GET 2/lists/:id/pinned_lists

Rules

• GET 2/tweets/search/stream/rules
• POST 2/tweets/search/stream/rules
• POST 2/tweets/search/stream/rules, dry_run=true

Tweets

• GET 2/tweets
• POST 2/tweets
• GET 2/tweets/:id/liking_users
• GET 2/tweets/:id/quote_tweets
• GET 2/tweets/count/all (requires academic access)
• GET 2/tweets/count/recent
• GET 2/tweets/sample/stream
• GET 2/tweets/search/all (requires academic access)
• GET 2/tweets/search/recent
• GET 2/tweets/search/stream

Users

• GET 2/users
• GET 2/users/:id/blocking
• GET 2/users/:id/bookmarks
• GET 2/users/:id/followed_lists
• GET 2/users/:id/followers
• GET 2/users/:id/following
• GET 2/users/:id/liked_tweets
• GET 2/users/:id/list_memberships
• GET 2/users/:id/mentions
• GET 2/users/:id/muting
• GET 2/users/:id/owned_lists
• GET 2/users/:id/retweeted_by
• GET 2/users/:id/tweets
• GET 2/users/by
• GET 2/users/me

Documentation

Overview

Package twitter implements a client for the Twitter API v2. This package is in development and is not yet ready for production use.

Usage outline

The general structure of an API call is to first construct a query, then invoke that query with a context on a client:

cli := twitter.NewClient(&jape.Client{
   Authorize: jape.BearerTokenAuthorizer(token),
})

ctx := context.Background()
rsp, err := users.LookupByName("jack", nil).Invoke(ctx, cli)
if err != nil {
   log.Fatalf("Request failed: %v", err)
} else if len(rsp.Users) == 0 {
   log.Fatal("No matches")
}
process(rsp.Users)

Packages

Package "types" contains the type and constant definitions for the API.

Queries to look up tweets by ID or username, to search recent tweets, and to search or sample streams of tweets are defined in package "tweets".

Queries to look up users by ID or user name are defined in package "users".

Queries to read or update search rules are defined in package "rules".

Queries to create, edit, delete, and show the contents of lists are defined in package "lists".

Index

• Constants
• type Callback
• type Client
  • func NewClient(cli *jape.Client) *Client
  • func (c *Client) Call(ctx context.Context, req *jape.Request) (*Reply, error)
  • func (c *Client) CallRaw(ctx context.Context, req *jape.Request) ([]byte, error)
  • func (c *Client) Stream(ctx context.Context, req *jape.Request, f Callback) error
• type Pagination
• type RateLimit
• type Reply
  • func (r *Reply) IncludedMedia() (types.Medias, error)
  • func (r *Reply) IncludedPlaces() (types.Places, error)
  • func (r *Reply) IncludedPolls() (types.Polls, error)
  • func (r *Reply) IncludedTweets() (types.Tweets, error)
  • func (r *Reply) IncludedUsers() (types.Users, error)

Constants

const (
	// BaseURL is the default base URL for the production Twitter API.
	// This is the default base URL if one is not given in the client.
	BaseURL = "https://api.twitter.com"

	// NextTokenParam is the name of the query parameter used to send a page
	// token to the service.
	NextTokenParam = "pagination_token"
)

Types

type Callback

type Callback func(*Reply) error

A Callback function is invoked for each reply received in a stream. If the callback reports a non-nil error, the stream is terminated. If the error is anything other than ErrStopStreaming, it is reported to the caller.

type Client

type Client jape.Client

A Client serves as a client for the Twitter API v2.

func NewClient

func NewClient(cli *jape.Client) *Client

NewClient returns a new client for the Twitter API. If cli == nil, default client options are used targeting the production API at BaseURL.

func (*Client) Call

func (c *Client) Call(ctx context.Context, req *jape.Request) (*Reply, error)

Call issues the specified API request and returns the decoded reply. Errors from Call have concrete type *jape.Error.

func (*Client) CallRaw

func (c *Client) CallRaw(ctx context.Context, req *jape.Request) ([]byte, error)

CallRaw issues the specified API request and returns the raw response body without decoding. Errors from CallRaw have concrete type *jape.Error

func (*Client) Stream

func (c *Client) Stream(ctx context.Context, req *jape.Request, f Callback) error

Stream issues the specified API request and streams results to the given callback. Errors from Stream have concrete type *jape.Error.

type Pagination

type Pagination struct {
	ResultCount int    `json:"result_count"`
	NextToken   string `json:"next_token"`
}

Pagination records metadata about pagination of results.

type RateLimit

type RateLimit struct {
	Ceiling   int       // rate limit ceiling for this endpoint
	Remaining int       // requests remaining in the current window
	Reset     time.Time // time of next window reset
}

RateLimit records metadata about API rate limits reported by the server.

type Reply

type Reply struct {
	// The root reply object from a successful query.
	Data json.RawMessage `json:"data,omitempty"`

	// For expansions that generate attachments, a map of attachment type to
	// JSON arrays of attachment objects.
	Includes map[string]json.RawMessage `json:"includes,omitempty"`

	// Server metadata reported with search replies.
	Meta json.RawMessage `json:"meta,omitempty"`

	// Error details reported with lookup or search replies.
	Errors []*types.ErrorDetail `json:"errors,omitempty"`

	// Rate limit metadata reported by the server. If the server did not return
	// these data, this field will be nil.
	RateLimit *RateLimit `json:"-"`
}

A Reply is a wrapper for the reply object returned by successful calls to the Twitter API v2.

func (*Reply) IncludedMedia

func (r *Reply) IncludedMedia() (types.Medias, error)

IncludedMedia decodes any media objects in the includes of r. It returns nil without error if there are no media inclusions.

func (*Reply) IncludedPlaces

func (r *Reply) IncludedPlaces() (types.Places, error)

IncludedPlaces decodes any place objects in the includes of r. It returns nil without error if there are no place inclusions.

func (*Reply) IncludedPolls

func (r *Reply) IncludedPolls() (types.Polls, error)

IncludedPolls decodes any poll objects in the includes of r. It returns nil without error if there are no poll inclusions.

func (*Reply) IncludedTweets

func (r *Reply) IncludedTweets() (types.Tweets, error)

IncludedTweets decodes any tweet objects in the includes of r. It returns nil without error if there are no tweet inclusions.

func (*Reply) IncludedUsers

func (r *Reply) IncludedUsers() (types.Users, error)

IncludedUsers decodes any user objects in the includes of r. It returns nil without error if there are no user inclusions.