A Go client library for the Twitter 1.1 API
Go
Latest commit 00ecb7b Jun 5, 2016 @ChimeraCoder Merge pull request #148 from ChimeraCoder/ahamidi-include-quoted-fields
Include quoted tweet fields
Permalink
Failed to load latest commit information.
json Add test for quoted tweet Jun 4, 2016
.gitignore Add anaconda.test (test binary) to .gitignore Dec 24, 2014
.travis.yml Add Go 1.5 and 1.6 to build (#139) May 9, 2016
COPYING Add LICENSE (symlinked from COPYING). MIT/X11. Mar 4, 2013
LICENSE Add LICENSE (symlinked from COPYING). MIT/X11. Mar 4, 2013
README Add Travis CI build status to README (#151) Jun 4, 2016
README.md Add README Mar 4, 2013
account.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
backoff.go Update streaming funcs for latest version of azr/backoff Jan 15, 2016
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 Use client baseUrl instead of constant BaseUrl Nov 17, 2015
errors.go Add error code that Twitter sometimes returns Feb 6, 2015
example_test.go Add Go 1.5 and 1.6 to build (#139) May 9, 2016
favorites.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
friends_followers.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
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 Use client baseUrl instead of constant BaseUrl Nov 17, 2015
log.go Update documentation for logging Mar 30, 2015
media.go Run gofmt (#140) Jun 3, 2016
mutes.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
oembed.go Revert "Record response for OEmbed test" Jun 4, 2016
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
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 feat(streaming): backoff as defined in docs ! Oct 27, 2015
timeline.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
trends.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
tweet.go include quoted tweet fields Jun 4, 2016
tweets.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015
twitter.go Run gofmt (#140) Jun 3, 2016
twitter_entities.go Add status_source_id and status_source_id_str fields to EntityMedia Jul 28, 2015
twitter_test.go Allow multiple recorded form responses for the same endpoint Jun 4, 2016
twitter_user.go withheld_in_countries field became array of string, same as in tweet … Jul 8, 2015
users.go Use client baseUrl instead of constant BaseUrl Nov 17, 2015

README.md

Anaconda

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:

anaconda.SetConsumerKey("your-consumer-key")
anaconda.SetConsumerSecret("your-consumer-secret")
api := anaconda.NewTwitterApi("your-access-token", "your-access-token-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.

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.