Twitter API v2 Client for Go

twitter is a Go package for the Twitter v2 API, inspired by ChimeraCoder/anaconda. This library uses channels for both, to retrieve data from Twitter API and return the results, with a built-in throttle to avoid rate-limit errors return from Twitter. You can bypass the throttling by usgin twitter.WithRate(time.Duration) option. The library will auto paginate results unless you use the twitter.WithAuto(false) option.

Installation

go get github.com/cvcio/twitter

Supported Endpoints

Method	Implemented	OAuth	Rate Limit	Official Documentation
VerifyCredentials	Yes	OAuth 1.0a User Context, OAuth 2.0 Bearer Token	-	-
GetUserFollowers	Yes	OAuth 2.0 Bearer Token	15/15m (app), 15/15m (user)	Get User Followers
GetUserFollowing	Yes	OAuth 2.0 Bearer Token	15/15m (app), 15/15m (user)	Get User Following
GetUsers	Yes	OAuth 2.0 Bearer Token	300/15m (app), 900/15m (user)	Get Users
GetUsersBy	Yes	OAuth 2.0 Bearer Token	300/15m (app), 900/15m (user)	Get Users By
GetUserByID	Yes	OAuth 2.0 Bearer Token	300/15m (app), 900/15m (user)	Get User By Id
GetUsersByUserName	Yes	OAuth 2.0 Bearer Token	300/15m (app), 900/15m (user)	Get Users By Screen Name
GetUserTweets	Yes	OAuth 1.0a User Context, OAuth 2.0 Bearer Token	1500/15m (app), 900/15m (user)	Get User Tweets
GetUserMentions	Yes	OAuth 1.0a User Context, OAuth 2.0 Bearer Token	450/15m (app), 180/15m (user)	Get User Mentions
GetTweets	Yes	OAuth 2.0 Bearer Token	300/15m (app), 900/15m (user)	Get Tweets
GetTweetByID	Yes	OAuth 2.0 Bearer Token	300/15m (app), 900/15m (user)	Get Tweets By Id
GetFilterStream	Yes	OAuth 2.0 Bearer Token	50/15m (app)	Filter Stream
GetFilterStreamRules	Yes	OAuth 2.0 Bearer Token	450/15m (app)	Get Filter Stream Rules
PostFilterStreamRules	Yes	OAuth 2.0 Bearer Token	450/15m (app)	Post Filter Stream Rules
GetSampleStream	Yes	OAuth 2.0 Bearer Token	50/15m (app)	Sample Stream
GetTweetsSearchRecent	Yes	OAuth 2.0 Bearer Token	450/15m (app), 180/15m (user)	Search Tweets - Recent
GetTweetsSearchAll	-	OAuth 2.0 Bearer Token	300/15m (app), 1/1s (user)	Search Tweets - All

Usage

Authentication

api, err := twitter.NewTwitterWithContext(*consumerKey, *consumerSecret, *accessToken, *accessTokenSecret)
if err != nil {
	panic(err)
}

Methods

Each method returns 2 channels, one for results and one for errors (twitter.APIError).

v := url.Values{}
v.Add("max_results", "1000")
resultsChannel, _ := api.GetUserFollowers(*id, v)
for {
	// resultsChannel
	r, ok := <-resultsChannel
	if !ok {
		break
	}
	...
}

Implement with error channel

v := url.Values{}
v.Add("max_results", "1000")
res, errs := api.GetUserFollowing(*id, v, twitter.WithRate(time.Minute/6), twitter.WithAuto(true))

for {
	select {
	case r, ok := <-res:
		if !ok {
			res = nil
			break
		}

		var d []*twitter.User
		b, err := json.Marshal(r.Data)
		if err != nil {
			t.Fatalf("json Marshar Error: %v", err)
		}

		json.Unmarshal(b, &d)

	case e, ok := <-errs:
		if !ok {
			errs = nil
			break
		}
		t.Errorf("Twitter API Error: %v", e)
	}

	if res == nil && errs == nil {
		break
	}

}

Options

cvcio/twitter supports the following options for all methods. You can pass any option during the method contrstruction.

followers, _ := api.GetUserFollowers(*id, url.Values{}, twitter.WithDelay(1*time.Minute), twitter.WithRate(1*time.Minute) ...)

WithDealy

Adjust the the duration between each errored requests due to rate limit errors from Twitter API by using the WithDelay option.

twitter.WithDelay(time.Duration)

WithRate

Throttle requests (distinct for each method) to avoid rate limit errors from Twitter API.

twitter.WithRate(time.Duration)

WithAuto

Auto paginate results (if available) when pagination_token is present in the response object.

twitter.WithAuto(Bool)

Streaming

api, _ := twitter.NewTwitter(*consumerKey, *consumerSecret,)
rules := new(twitter.Rules)
rules.Add = append(rules.Add, &twitter.RulesData{
	Value: "greece",
	Tag:   "test-client",
})

res, _ := api.PostFilterStreamRules(nil, rules)

v := url.Values{}
v.Add("user.fields", "created_at,description,id,location,name,pinned_tweet_id,profile_image_url,protected,public_metrics,url,username,verified")
v.Add("expansions", "author_id,in_reply_to_user_id")
v.Add("tweet.fields", "created_at,id,lang,source,public_metrics")

s, _ := api.GetFilterStream(v)
for t := range s.C {
	f, _ := t.(twitter.StreamData)
	fmt.Println(f.Tweet)
	break
}
s.Stop()

Examples

// get all followers for a specific user id 
// and print the results
package main

import (
	"encoding/json"
	"flag"
	"fmt"
	"net/url"
	"time"

	"github.com/cvcio/twitter"
)

func main() {
	consumerKey := flag.String("consumer-key", "", "twitter API consumer key")
	consumerSecret := flag.String("consumer-secret", "", "twitter API consumer secret")

	id := flag.String("id", "", "user id")

	flag.Parse()

	start := time.Now()

	api, err := twitter.NewTwitter(*consumerKey, *consumerSecret)
	if err != nil {
		panic(err)
	}

	v := url.Values{}
	v.Add("max_results", "1000")
	followers, _ := api.GetUserFollowers(*id, v)

	for {
		r, ok := <-followers

		if !ok {
			break
		}

		b, err := json.Marshal(r.Data)
		if err != nil {
			panic(err)
		}

		var data []*twitter.User
		json.Unmarshal(b, &data)
		for _, v := range data {
			fmt.Printf("%s,%s,%s\n", v.ID, v.UserName, v.Name)
		}

		fmt.Println()
		fmt.Printf("Result Count: %d Next Token: %s\n", r.Meta.ResultCount, r.Meta.NextToken)
	}

	end := time.Now()

	fmt.Printf("Done in %s", end.Sub(start))
}

Contribution

If you're new to contributing to Open Source on Github, this guide can help you get started. Please check out the contribution guide for more details on how issues and pull requests work. Before contributing be sure to review the code of conduct.

Contributors

License

This library is distributed under the MIT license found in the LICENSE file.