diff --git a/README b/README index 47200eb..09081b2 100644 --- a/README +++ b/README @@ -7,7 +7,7 @@ Anaconda is a simple, transparent Go package for accessing version 1.1 of the Tw Successful API queries return native Go structs that can be used immediately, with no need for type assertions. - +For more information and a complete api please see the [GoDoc.](https://godoc.org/github.com/ChimeraCoder/anaconda) Examples -------- @@ -17,12 +17,13 @@ Examples 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: ```go -api := anaconda.NewTwitterApiWithCredentials("your-access-token", "your-access-token-secret", "your-consumer-key", "your-consumer-secret") +api := anaconda.NewTwitterApiWithCredentials("user-token", "user-token-secret", "your-consumer-key", "your-consumer-secret") ``` ### Queries +Almost all of anaconda's methods require the Values struct from the ["net/url" package](https://golang.org/pkg/net/url/) -Queries are conducted using a pointer to an authenticated `TwitterApi` struct. In v1.1 of Twitter's API, all requests should be authenticated. +Queries are methods of an authenticated `TwitterApi` struct. In v1.1 of Twitter's API, all requests should be authenticated. ```go searchResult, _ := api.GetSearch("golang", nil) @@ -44,43 +45,64 @@ result, err := api.GetSearch("golang", v) ### 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` +A go loop is started and gives you a stream that sends `interface{}` objects through it's `chan` `C` Objects which you can cast into a tweet, event and more. +Some services like [FireHose](https://developer.twitter.com/en/docs/tweets/compliance/api-reference/compliance-firehose) and [Decahose](https://developer.twitter.com/en/docs/tweets/sample-realtime/overview/decahose) require enterprise access to the twitter api. +Example for the PublicStreamFilter ([statuses/filter](https://developer.twitter.com/en/docs/tweets/filter-realtime/overview)) ````go -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) - } - } +values := url.Values{} +values.Set("track", "#golang,#go,#anaconda,#ChimeraCoder,#fakenews,#twitter-dev") +stream := api.UserStream(values) +counter := 0 + +for data := range s.C { + tweet, ok := data.(anaconda.Tweet) + if ok { + fmt.Println(tweet.Text) + counter += 1 + if(counter == 50) { + // close the channel and release resources of this stream + api.Close() + } + } } ```` +Example for the UserStream +````go +values := url.Values{} +stream := api.UserStream(values) + + +for data := range stream.C { + switch tweet := data.(type) { + case anaconda.Tweet: + fmt.Printf("%-15s: %s\n", tweet.User.ScreenName, tweet.Text) + case anaconda.EventTweet: + switch tweet.Event.Event { + case "favorite": + screenName := tweet.Source.ScreenName + text := tweet.TargetObject.Text + fmt.Printf("Favorited by %-15s: %s\n", screenName, text) + case "unfavorite": + screenName := tweet.Source.ScreenName + text := tweet.TargetObject.Text + fmt.Printf("UnFavorited by %-15s: %s\n", screenName, text) + } + } +} +```` +For more information about streaming and streaming parameter please view the [Standard streaming API request parameters](https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters) Endpoints --------- Anaconda 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`). -In a few cases, a shortened form has been chosen to make life easier (for example, retweeting is simply the function `Retweet`) - - +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 --------------------------------------------- @@ -89,14 +111,11 @@ Error Handling, Rate Limiting, and Throttling 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](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. 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)`.) - +(If desired, this feature can be turned off by calling `api.ReturnRateLimitError(true)`.) ### Throttling @@ -104,7 +123,6 @@ Anaconda now supports automatic client-side throttling of queries to avoid hitti 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: ```go @@ -113,7 +131,6 @@ 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`: ```go @@ -122,18 +139,36 @@ 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. +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. + ```go api = anaconda.NewTwitterApi("", "") c := appengine.NewContext(r) api.HttpClient.Transport = &urlfetch.Transport{Context: c} ``` +### Twitter Media api + +Anaconda support the media api, currently file uploads to the new media api ([media/upload](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload)) is available only in base64. + +```go +// this is a one pixel png image from: http://png-pixel.com/ +myBase64Image := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" + +media, err := api.UploadMedia(myBase64Image) +if(err == nil){ + // use this string id when referencing twitter media + fmt.Println(media.MediaIDString) +} +``` + +Video uploads can be made using the media api by calling UploadMedia, or by using the ``UploadVideoInit``, ``UploadVideoAppend`` and ``UploadVideoFinalize`` methods. License -------