Go
Clone or download
Permalink
Failed to load latest commit information.
json Support the new `extended tweet_mode` API (#200) Sep 2, 2017
vendor/github.com Add gofmt check to build (#202) Sep 2, 2017
.appveyor.yml Add race detector to tests in CI build (#208) Sep 3, 2017
.gitignore Add anaconda.test (test binary) to .gitignore Dec 24, 2014
.travis.yml Use exclude instead of include directive for Travis (#235) Mar 4, 2018
COPYING Add LICENSE (symlinked from COPYING). MIT/X11. Mar 4, 2013
Gopkg.lock Add support for dep (#201) Sep 2, 2017
Gopkg.toml Add support for dep (#201) Sep 2, 2017
LICENSE Add LICENSE (symlinked from COPYING). MIT/X11. Mar 4, 2013
README Update README for streaming API. (#241) Mar 5, 2018
README.md Add README Mar 4, 2013
account.go Use cleanValues more consistently (#204) Sep 2, 2017
backoff.go Update docs to fix broken Twitter API reference links (#227) Nov 25, 2017
blocks.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
configuration.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
directmessage.go Change TwitterUser->User and remove unnecessary logging statements Dec 29, 2013
directmessages.go Implement IndicateTyping endpoint (#236) Feb 26, 2018
errors.go Update docs to fix broken Twitter API reference links (#227) Nov 25, 2017
example_test.go Store OAuth credentials per TwitterApi instance (#222) Feb 26, 2018
favorites.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
friends_followers.go Implement GetListMembers (#240) Mar 4, 2018
geosearch.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
list.go Allow additional values to be passed in to /list endpoints via url.Va… Dec 24, 2014
lists.go Add method to fetch list tweets by slug and owner_screen_name (#207) Sep 3, 2017
log.go Correctly pass arguments in BasicLogger (#109) Nov 20, 2017
media.go Run gofmt (#140) Jun 3, 2016
mutes.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
oembed.go Use cleanValues more consistently (#204) Sep 2, 2017
oembed_test.go Update URL field returned by OEmbed test Jun 4, 2016
place.go Differentiate between GeoSearch PlaceResult and Tweet Place Jul 19, 2015
rate_limit_status.go Add application/rate_limit_status (#205) Sep 3, 2017
relationship.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
search.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
streaming.go Store OAuth credentials per TwitterApi instance (#222) Feb 26, 2018
timeline.go Update docs for timeline methods with links (#212) Nov 12, 2017
trends.go Update docs to fix broken Twitter API reference links (#227) Nov 25, 2017
tweet.go Support the new `extended tweet_mode` API (#200) Sep 2, 2017
tweets.go Update docs to fix broken Twitter API reference links (#227) Nov 25, 2017
twitter.go Enforce a default HTTP client timeout (#226) Feb 26, 2018
twitter_entities.go Add Category struct and change GetUsersSuggestions to use it (#228) Mar 4, 2018
twitter_test.go Store OAuth credentials per TwitterApi instance (#222) Feb 26, 2018
twitter_user.go Add email field (#164) Oct 15, 2017
users.go Add Category struct and change GetUsersSuggestions to use it (#228) Mar 4, 2018
webhook.go Enforce a default HTTP client timeout (#226) Feb 26, 2018

README.md

Anaconda

Build Status Build Status GoDoc

Anaconda is a simple, transparent Go package for accessing version 1.1 of the Twitter API.

Successful API queries return native Go structs that can be used immediately, with no need for type assertions.

Examples

Authentication

If you already have the access token (and secret) for your user (Twitter provides this for your own account on the developer portal), creating the client is simple:

api := anaconda.NewTwitterApiWithCredentials("your-access-token", "your-access-token-secret", "your-consumer-key", "your-consumer-secret")

Queries

Queries are conducted using a pointer to an authenticated TwitterApi struct. In v1.1 of Twitter's API, all requests should be authenticated.

searchResult, _ := api.GetSearch("golang", nil)
for _ , tweet := range searchResult.Statuses {
    fmt.Println(tweet.Text)
}

Certain endpoints allow separate optional parameter; if desired, these can be passed as the final parameter.

//Perhaps we want 30 values instead of the default 15
v := url.Values{}
v.Set("count", "30")
result, err := api.GetSearch("golang", v)

(Remember that url.Values is equivalent to a map[string][]string, if you find that more convenient notation when specifying values). Otherwise, nil suffices.

Streaming

Anaconda supports the Streaming APIs. You can use PublicStream* or UserStream API methods. A go loop is started an gives you an stream that sends interface{} objects through it's chan C Objects which you can cast into a tweet, event and more.

v := url.Values{}
s := api.UserStream(v)

for t := range s.C {
  switch v := t.(type) {
  case anaconda.Tweet:
    fmt.Printf("%-15s: %s\n", v.User.ScreenName, v.Text)
  case anaconda.EventTweet:
    switch v.Event.Event {
    case "favorite":
      sn := v.Source.ScreenName
      tw := v.TargetObject.Text
      fmt.Printf("Favorited by %-15s: %s\n", sn, tw)
    case "unfavorite":
      sn := v.Source.ScreenName
      tw := v.TargetObject.Text
      fmt.Printf("UnFavorited by %-15s: %s\n", sn, tw)
    }
  }
}

Endpoints

Anaconda implements most of the endpoints defined in the Twitter API documentation. For clarity, in most cases, the function name is simply the name of the HTTP method and the endpoint (e.g., the endpoint GET /friendships/incoming is provided by the function GetFriendshipsIncoming).

In a few cases, a shortened form has been chosen to make life easier (for example, retweeting is simply the function Retweet)

Error Handling, Rate Limiting, and Throttling

Error Handling

Twitter errors are returned as an ApiError, which satisfies the error interface and can be treated as a vanilla error. However, it also contains the additional information returned by the Twitter API that may be useful in deciding how to proceed after encountering an error.

If you make queries too quickly, you may bump against Twitter's rate limits. If this happens, anaconda automatically retries the query when the rate limit resets, using the X-Rate-Limit-Reset header that Twitter provides to determine how long to wait.

In other words, users of the anaconda library should not need to handle rate limiting errors themselves; this is handled seamlessly behind-the-scenes. If an error is returned by a function, another form of error must have occurred (which can be checked by using the fields provided by the ApiError struct).

(If desired, this feature can be turned off by calling ReturnRateLimitError(true).)

Throttling

Anaconda now supports automatic client-side throttling of queries to avoid hitting the Twitter rate-limit.

This is currently off by default; however, it may be turned on by default in future versions of the library, as the implementation is improved.

To set a delay between queries, use the SetDelay method:

api.SetDelay(10 * time.Second)

Delays are set specific to each TwitterApi struct, so queries that use different users' access credentials are completely independent.

To turn off automatic throttling, set the delay to 0:

api.SetDelay(0 * time.Second)

Query Queue Persistence

If your code creates a NewTwitterApi in a regularly called function, you'll need to call .Close() on the API struct to clear the queryQueue and allow the goroutine to exit. Otherwise you could see goroutine and therefor heap memory leaks in long-running applications.

Google App Engine

Since Google App Engine doesn't make the standard http.Transport available, it's necessary to tell Anaconda to use a different client context.

api = anaconda.NewTwitterApi("", "")
c := appengine.NewContext(r)
api.HttpClient.Transport = &urlfetch.Transport{Context: c}

License

Anaconda is free software licensed under the MIT/X11 license. Details provided in the LICENSE file.