README
1Anaconda
2====================
3
4[](https://travis-ci.org/ChimeraCoder/anaconda) [](https://ci.appveyor.com/project/ChimeraCoder/anaconda/branch/master) [](https://godoc.org/github.com/ChimeraCoder/anaconda)
5
6Anaconda is a simple, transparent Go package for accessing version 1.1 of the Twitter API.
7
8Successful API queries return native Go structs that can be used immediately, with no need for type assertions.
9
10
11
12Examples
13-------------
14
15### Authentication
16
17If 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:
18
19````go
20api := anaconda.NewTwitterApiWithCredentials("your-access-token", "your-access-token-secret", "your-consumer-key", "your-consumer-secret")
21````
22
23### Queries
24
25Queries are conducted using a pointer to an authenticated `TwitterApi` struct. In v1.1 of Twitter's API, all requests should be authenticated.
26
27````go
28searchResult, _ := api.GetSearch("golang", nil)
29for _ , tweet := range searchResult.Statuses {
30 fmt.Println(tweet.Text)
31}
32````
33Certain endpoints allow separate optional parameter; if desired, these can be passed as the final parameter.
34
35````go
36//Perhaps we want 30 values instead of the default 15
37v := url.Values{}
38v.Set("count", "30")
39result, err := api.GetSearch("golang", v)
40````
41
42(Remember that `url.Values` is equivalent to a `map[string][]string`, if you find that more convenient notation when specifying values). Otherwise, `nil` suffices.
43
44
45
46Endpoints
47------------
48
49Anaconda implements most of the endpoints defined in the [Twitter API documentation](https://developer.twitter.com/en/docs). 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`).
50
51In a few cases, a shortened form has been chosen to make life easier (for example, retweeting is simply the function `Retweet`)
52
53
54
55Error Handling, Rate Limiting, and Throttling
56---------------------------------
57
58### Error Handling
59
60Twitter 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.
61
62
63If you make queries too quickly, you may bump against Twitter's [rate limits](https://developer.twitter.com/en/docs/basics/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.
64
65In 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).
66
67
68(If desired, this feature can be turned off by calling `ReturnRateLimitError(true)`.)
69
70
71### Throttling
72
73Anaconda now supports automatic client-side throttling of queries to avoid hitting the Twitter rate-limit.
74
75This is currently *off* by default; however, it may be turned on by default in future versions of the library, as the implementation is improved.
76
77
78To set a delay between queries, use the `SetDelay` method:
79
80````go
81 api.SetDelay(10 * time.Second)
82````
83
84Delays are set specific to each `TwitterApi` struct, so queries that use different users' access credentials are completely independent.
85
86
87To turn off automatic throttling, set the delay to `0`:
88
89````go
90 api.SetDelay(0 * time.Second)
91````
92
93### Query Queue Persistence
94
95If 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.
96
97### Google App Engine
98
99Since Google App Engine doesn't make the standard `http.Transport` available, it's necessary to tell Anaconda to use a different client context.
100
101````go
102 api = anaconda.NewTwitterApi("", "")
103 c := appengine.NewContext(r)
104 api.HttpClient.Transport = &urlfetch.Transport{Context: c}
105````
106
107
108License
109-----------
110Anaconda is free software licensed under the MIT/X11 license. Details provided in the LICENSE file.
111
README.md
1Anaconda
2====================
3
4[](https://travis-ci.org/ChimeraCoder/anaconda) [](https://ci.appveyor.com/project/ChimeraCoder/anaconda/branch/master) [](https://godoc.org/github.com/ChimeraCoder/anaconda)
5
6Anaconda is a simple, transparent Go package for accessing version 1.1 of the Twitter API.
7
8Successful API queries return native Go structs that can be used immediately, with no need for type assertions.
9
10
11
12Examples
13-------------
14
15### Authentication
16
17If 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:
18
19````go
20api := anaconda.NewTwitterApiWithCredentials("your-access-token", "your-access-token-secret", "your-consumer-key", "your-consumer-secret")
21````
22
23### Queries
24
25Queries are conducted using a pointer to an authenticated `TwitterApi` struct. In v1.1 of Twitter's API, all requests should be authenticated.
26
27````go
28searchResult, _ := api.GetSearch("golang", nil)
29for _ , tweet := range searchResult.Statuses {
30 fmt.Println(tweet.Text)
31}
32````
33Certain endpoints allow separate optional parameter; if desired, these can be passed as the final parameter.
34
35````go
36//Perhaps we want 30 values instead of the default 15
37v := url.Values{}
38v.Set("count", "30")
39result, err := api.GetSearch("golang", v)
40````
41
42(Remember that `url.Values` is equivalent to a `map[string][]string`, if you find that more convenient notation when specifying values). Otherwise, `nil` suffices.
43
44
45
46Endpoints
47------------
48
49Anaconda implements most of the endpoints defined in the [Twitter API documentation](https://developer.twitter.com/en/docs). 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`).
50
51In a few cases, a shortened form has been chosen to make life easier (for example, retweeting is simply the function `Retweet`)
52
53
54
55Error Handling, Rate Limiting, and Throttling
56---------------------------------
57
58### Error Handling
59
60Twitter 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.
61
62
63If you make queries too quickly, you may bump against Twitter's [rate limits](https://developer.twitter.com/en/docs/basics/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.
64
65In 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).
66
67
68(If desired, this feature can be turned off by calling `ReturnRateLimitError(true)`.)
69
70
71### Throttling
72
73Anaconda now supports automatic client-side throttling of queries to avoid hitting the Twitter rate-limit.
74
75This is currently *off* by default; however, it may be turned on by default in future versions of the library, as the implementation is improved.
76
77
78To set a delay between queries, use the `SetDelay` method:
79
80````go
81 api.SetDelay(10 * time.Second)
82````
83
84Delays are set specific to each `TwitterApi` struct, so queries that use different users' access credentials are completely independent.
85
86
87To turn off automatic throttling, set the delay to `0`:
88
89````go
90 api.SetDelay(0 * time.Second)
91````
92
93### Query Queue Persistence
94
95If 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.
96
97### Google App Engine
98
99Since Google App Engine doesn't make the standard `http.Transport` available, it's necessary to tell Anaconda to use a different client context.
100
101````go
102 api = anaconda.NewTwitterApi("", "")
103 c := appengine.NewContext(r)
104 api.HttpClient.Transport = &urlfetch.Transport{Context: c}
105````
106
107
108License
109-----------
110Anaconda is free software licensed under the MIT/X11 license. Details provided in the LICENSE file.
111
){kind=link}
){kind=link}