Documentation ¶
Overview ¶
Package anaconda provides structs and functions 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.
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 ¶
Executing queries on an authenticated TwitterApi struct is simple.
searchResult, _ := api.GetSearch("golang", nil) for _ , tweet := range searchResult { fmt.Print(tweet.Text) }
Certain endpoints allow separate optional parameter; if desired, these can be passed as the final parameter.
v := url.Values{} v.Set("count", "30") result, err := api.GetSearch("golang", v)
Endpoints ¶
Anaconda implements most of the endpoints defined in the Twitter API documentation: https://dev.twitter.com/docs/api/1.1. 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`)
More detailed information about the behavior of each particular endpoint can be found at the official Twitter API documentation.
Index ¶
- Constants
- func AuthorizationURL(callback string) (string, *oauth.Credentials, error)
- func GetCredentials(tempCred *oauth.Credentials, verifier string) (*oauth.Credentials, url.Values, error)
- func SetConsumerKey(consumer_key string)
- func SetConsumerSecret(consumer_secret string)
- type ApiError
- type Cursor
- type DirectMessage
- type Entities
- type FollowersPage
- type Friendship
- type MediaSize
- type MediaSizes
- type OEmbed
- type Place
- type Tweet
- type TwitterApi
- func (c *TwitterApi) Close()
- func (a TwitterApi) DeleteTweet(id int64, trimUser bool) (tweet Tweet, err error)
- func (c *TwitterApi) DisableThrottling()
- func (c *TwitterApi) EnableThrottling(rate time.Duration, bufferSize int64)
- func (a TwitterApi) Favorite(id int64) (rt Tweet, err error)
- func (c *TwitterApi) GetDelay() time.Duration
- func (a TwitterApi) GetDirectMessages(v url.Values) (messages []DirectMessage, err error)
- func (a TwitterApi) GetDirectMessagesSent(v url.Values) (messages []DirectMessage, err error)
- func (a TwitterApi) GetDirectMessagesShow(v url.Values) (messages []DirectMessage, err error)
- func (a TwitterApi) GetFavorites(v url.Values) (favorites []Tweet, err error)
- func (a TwitterApi) GetFollowersIds(v url.Values) (c Cursor, err error)
- func (a TwitterApi) GetFollowersList(v url.Values) (c UserCursor, err error)
- func (a TwitterApi) GetFollowersListAll(v url.Values) (result chan FollowersPage)
- func (a TwitterApi) GetFriendsIds(v url.Values) (c Cursor, err error)
- func (a TwitterApi) GetFriendsIdsAll(v url.Values) (c Cursor, err error)
- func (a TwitterApi) GetFriendsList(v url.Values) (c UserCursor, err error)
- func (a TwitterApi) GetFriendshipsIncoming(v url.Values) (c Cursor, err error)
- func (a TwitterApi) GetFriendshipsLookup(v url.Values) (friendships []Friendship, err error)
- func (a TwitterApi) GetFriendshipsNoRetweets() (ids []int64, err error)
- func (a TwitterApi) GetFriendshipsOutgoing(v url.Values) (c Cursor, err error)
- func (a TwitterApi) GetHomeTimeline(v url.Values) (timeline []Tweet, err error)
- func (a TwitterApi) GetMentionsTimeline(v url.Values) (timeline []Tweet, err error)
- func (a TwitterApi) GetOEmbed(v url.Values) (o OEmbed, err error)
- func (a TwitterApi) GetOEmbedId(id int64, v url.Values) (o OEmbed, err error)
- func (a TwitterApi) GetRetweets(id int64, v url.Values) (tweets []Tweet, err error)
- func (a TwitterApi) GetRetweetsOfMe(v url.Values) (tweets []Tweet, err error)
- func (a TwitterApi) GetSearch(queryString string, v url.Values) (timeline []Tweet, err error)
- func (a TwitterApi) GetSelf(v url.Values) (u User, err error)
- func (a TwitterApi) GetTweet(id int64, v url.Values) (tweet Tweet, err error)
- func (a TwitterApi) GetUserSearch(searchTerm string, v url.Values) (u []User, err error)
- func (a TwitterApi) GetUserTimeline(v url.Values) (timeline []Tweet, err error)
- func (a TwitterApi) GetUsersLookup(usernames string, v url.Values) (u []User, err error)
- func (a TwitterApi) GetUsersLookupByIds(ids []int64, v url.Values) (u []User, err error)
- func (a TwitterApi) GetUsersShow(username string, v url.Values) (u User, err error)
- func (a TwitterApi) GetUsersShowById(id int64, v url.Values) (u User, err error)
- func (a TwitterApi) PostDMToScreenName(text, screenName string) (message DirectMessage, err error)
- func (a TwitterApi) PostDMToUserId(text string, userId int64) (message DirectMessage, err error)
- func (a TwitterApi) PostTweet(status string, v url.Values) (tweet Tweet, err error)
- func (c *TwitterApi) ReturnRateLimitError(b bool)
- func (a TwitterApi) Retweet(id int64, trimUser bool) (rt Tweet, err error)
- func (c *TwitterApi) SetDelay(t time.Duration)
- func (a TwitterApi) VerifyCredentials() (ok bool, err error)
- type TwitterError
- type TwitterErrorResponse
- type User
- type UserCursor
Examples ¶
Constants ¶
const ( //Error code defintions match the Twitter documentation //https://dev.twitter.com/docs/error-codes-responses TwitterErrorCouldNotAuthenticate = 32 TwitterErrorDoesNotExist = 34 TwitterErrorAccountSuspended = 64 TwitterErrorApi1Deprecation = 68 //This should never be needed TwitterErrorRateLimitExceeded = 88 TwitterErrorInvalidToken = 89 TwitterErrorOverCapacity = 130 TwitterErrorInternalError = 131 TwitterErrorCouldNotAuthenticateYou = 135 TwitterErrorStatusIsADuplicate = 187 TwitterErrorBadAuthenticationData = 215 TwitterErrorUserMustVerifyLogin = 231 )
const ( BaseUrlV1 = "https://api.twitter.com/1" BaseUrl = "https://api.twitter.com/1.1" )
const DEFAULT_CAPACITY = 5
const DEFAULT_DELAY = 0 * time.Second
Variables ¶
This section is empty.
Functions ¶
func AuthorizationURL ¶
func AuthorizationURL(callback string) (string, *oauth.Credentials, error)
AuthorizationURL generates the authorization URL for the first part of the OAuth handshake. Redirect the user to this URL. This assumes that the consumer key has already been set (using SetConsumerKey).
func GetCredentials ¶
func GetCredentials(tempCred *oauth.Credentials, verifier string) (*oauth.Credentials, url.Values, error)
func SetConsumerKey ¶
func SetConsumerKey(consumer_key string)
SetConsumerKey will set the application-specific consumer_key used in the initial OAuth process This key is listed on https://dev.twitter.com/apps/YOUR_APP_ID/show
func SetConsumerSecret ¶
func SetConsumerSecret(consumer_secret string)
SetConsumerSecret will set the application-specific secret used in the initial OAuth process This secret is listed on https://dev.twitter.com/apps/YOUR_APP_ID/show
Types ¶
type ApiError ¶
type ApiError struct { StatusCode int Header http.Header Body string Decoded TwitterErrorResponse URL *url.URL }
func NewApiError ¶
func (*ApiError) RateLimitCheck ¶
Check to see if an error is a Rate Limiting error. If so, find the next available window in the header. Use like so:
if aerr, ok := err.(*ApiError); ok { if isRateLimitError, nextWindow := aerr.RateLimitCheck(); isRateLimitError { <-time.After(nextWindow.Sub(time.Now())) } }
type DirectMessage ¶
type DirectMessage struct { CreatedAt string `json:"created_at"` Entities Entities `json:"entities"` Id int64 `json:"id"` IdStr string `json:"id_str"` Recipient User `json:"recipient"` RecipientId int64 `json:"recipient_id"` RecipientScreenName string `json:"recipient_screen_name"` Sender User `json:"sender"` SenderId int64 `json:"sender_id"` SenderScreenName string `json:"sender_screen_name"` Text string `json:"text"` }
type Entities ¶
type Entities struct { int Text string } Urls []struct { Indices []int Url string Display_url string Expanded_url string } User_mentions []struct { Name string Indices []int Screen_name string Id int64 Id_str string } Media []struct { Id int64 Id_str string Media_url string Media_url_https string Url string Display_url string Expanded_url string Sizes MediaSizes Type string Indices []int } }Indices []
type FollowersPage ¶
type Friendship ¶
type MediaSizes ¶
type Place ¶
type Place struct { Attributes map[string]string `json:"attributes"` BoundingBox struct { Coordinates [][][]float64 `json:"coordinates"` Type string `json:"type"` } `json:"bounding_box"` ContainedWithin []struct { Attributes map[string]string `json:"attributes"` BoundingBox struct { Coordinates [][][]float64 `json:"coordinates"` Type string `json:"type"` } `json:"bounding_box"` Country string `json:"country"` CountryCode string `json:"country_code"` FullName string `json:"full_name"` ID string `json:"id"` Name string `json:"name"` PlaceType string `json:"place_type"` URL string `json:"url"` } `json:"contained_within"` Country string `json:"country"` CountryCode string `json:"country_code"` FullName string `json:"full_name"` Geometry struct { Coordinates [][][]float64 `json:"coordinates"` Type string `json:"type"` } `json:"geometry"` ID string `json:"id"` Name string `json:"name"` PlaceType string `json:"place_type"` Polylines []string `json:"polylines"` URL string `json:"url"` }
type Tweet ¶
type Tweet struct { Contributors []int64 `json:"contributors"` Coordinates interface{} `json:"coordinates"` CreatedAt string `json:"created_at"` Entities Entities `json:"entities"` FavoriteCount int `json:"favorite_count"` Favorited bool `json:"favorited"` Geo interface{} `json:"geo"` Id int64 `json:"id"` IdStr string `json:"id_str"` InReplyToScreenName string `json:"in_reply_to_screen_name"` InReplyToStatusID int64 `json:"in_reply_to_status_id"` InReplyToStatusIdStr string `json:"in_reply_to_status_id_str"` InReplyToUserID int64 `json:"in_reply_to_user_id"` InReplyToUserIdStr string `json:"in_reply_to_user_id_str"` Place Place `json:"place"` PossiblySensitive bool `json:"possibly_sensitive"` RetweetCount int `json:"retweet_count"` Retweeted bool `json:"retweeted"` RetweetedStatus *Tweet `json:"retweeted_status"` Source string `json:"source"` Text string `json:"text"` Truncated bool `json:"truncated"` User User `json:"user"` }
type TwitterApi ¶
type TwitterApi struct { Credentials *oauth.Credentials HttpClient *http.Client // contains filtered or unexported fields }
func NewTwitterApi ¶
func NewTwitterApi(access_token string, access_token_secret string) *TwitterApi
NewTwitterApi takes an user-specific access token and secret and returns a TwitterApi struct for that user. The TwitterApi struct can be used for accessing any of the endpoints available.
func (TwitterApi) DeleteTweet ¶
func (a TwitterApi) DeleteTweet(id int64, trimUser bool) (tweet Tweet, err error)
DeleteTweet will destroy (delete) the status (tweet) with the specified ID, assuming that the authenticated user is the author of the status (tweet). If trimUser is set to true, only the user's Id will be provided in the user object returned.
func (*TwitterApi) DisableThrottling ¶
func (c *TwitterApi) DisableThrottling()
Disable query throttling
func (*TwitterApi) EnableThrottling ¶
func (c *TwitterApi) EnableThrottling(rate time.Duration, bufferSize int64)
Enable query throttling using the tokenbucket algorithm
func (TwitterApi) Favorite ¶
func (a TwitterApi) Favorite(id int64) (rt Tweet, err error)
Favorite will favorite the status (tweet) with the specified ID. https://dev.twitter.com/docs/api/1.1/post/favorites/create
func (*TwitterApi) GetDelay ¶
func (c *TwitterApi) GetDelay() time.Duration
func (TwitterApi) GetDirectMessages ¶
func (a TwitterApi) GetDirectMessages(v url.Values) (messages []DirectMessage, err error)
func (TwitterApi) GetDirectMessagesSent ¶
func (a TwitterApi) GetDirectMessagesSent(v url.Values) (messages []DirectMessage, err error)
func (TwitterApi) GetDirectMessagesShow ¶
func (a TwitterApi) GetDirectMessagesShow(v url.Values) (messages []DirectMessage, err error)
func (TwitterApi) GetFavorites ¶
func (a TwitterApi) GetFavorites(v url.Values) (favorites []Tweet, err error)
func (TwitterApi) GetFollowersIds ¶
func (a TwitterApi) GetFollowersIds(v url.Values) (c Cursor, err error)
func (TwitterApi) GetFollowersList ¶
func (a TwitterApi) GetFollowersList(v url.Values) (c UserCursor, err error)
func (TwitterApi) GetFollowersListAll ¶
func (a TwitterApi) GetFollowersListAll(v url.Values) (result chan FollowersPage)
Like GetFollowersList, but returns a channel instead of a cursor and pre-fetches the remaining results This channel is closed once all values have been fetched
Example ¶
Fetch a list of all followers without any need for managing cursors (Each page is automatically fetched when the previous one is read)
pages := api.GetFollowersListAll(nil) for page := range pages { //Print the current page of followers fmt.Println(page.Followers) }
Output:
func (TwitterApi) GetFriendsIds ¶
func (a TwitterApi) GetFriendsIds(v url.Values) (c Cursor, err error)
func (TwitterApi) GetFriendsIdsAll ¶
func (a TwitterApi) GetFriendsIdsAll(v url.Values) (c Cursor, err error)
Like GetFriendsIds, but returns a channel instead of a cursor and pre-fetches the remaining results This channel is closed once all values have been fetched
func (TwitterApi) GetFriendsList ¶
func (a TwitterApi) GetFriendsList(v url.Values) (c UserCursor, err error)
func (TwitterApi) GetFriendshipsIncoming ¶
func (a TwitterApi) GetFriendshipsIncoming(v url.Values) (c Cursor, err error)
func (TwitterApi) GetFriendshipsLookup ¶
func (a TwitterApi) GetFriendshipsLookup(v url.Values) (friendships []Friendship, err error)
func (TwitterApi) GetFriendshipsNoRetweets ¶
func (a TwitterApi) GetFriendshipsNoRetweets() (ids []int64, err error)
GetFriendshipsNoRetweets s a collection of user_ids that the currently authenticated user does not want to receive retweets from. It does not currently support the stringify_ids parameter
func (TwitterApi) GetFriendshipsOutgoing ¶
func (a TwitterApi) GetFriendshipsOutgoing(v url.Values) (c Cursor, err error)
func (TwitterApi) GetHomeTimeline ¶
func (a TwitterApi) GetHomeTimeline(v url.Values) (timeline []Tweet, err error)
GetHomeTimeline returns the most recent tweets and retweets posted by the user and the users that they follow. https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline By default, include_entities is set to "true"
func (TwitterApi) GetMentionsTimeline ¶
func (a TwitterApi) GetMentionsTimeline(v url.Values) (timeline []Tweet, err error)
func (TwitterApi) GetOEmbed ¶
func (a TwitterApi) GetOEmbed(v url.Values) (o OEmbed, err error)
No authorization on this endpoint. Its the only one.
func (TwitterApi) GetOEmbedId ¶
Calls GetOEmbed with the corresponding id. Convenience wrapper for GetOEmbed()
func (TwitterApi) GetRetweets ¶
func (TwitterApi) GetRetweetsOfMe ¶
func (a TwitterApi) GetRetweetsOfMe(v url.Values) (tweets []Tweet, err error)
func (TwitterApi) GetSearch ¶
Example ¶
package main import ( "fmt" "github.com/ChimeraCoder/anaconda" ) func main() { anaconda.SetConsumerKey("your-consumer-key") anaconda.SetConsumerSecret("your-consumer-secret") api := anaconda.NewTwitterApi("your-access-token", "your-access-token-secret") search_result, err := api.GetSearch("golang", nil) if err != nil { panic(err) } for _, tweet := range search_result { fmt.Print(tweet.Text) } }
Output:
func (TwitterApi) GetSelf ¶
func (a TwitterApi) GetSelf(v url.Values) (u User, err error)
Get the user object for the authenticated user. Requests /account/verify_credentials
func (TwitterApi) GetUserSearch ¶
func (TwitterApi) GetUserTimeline ¶
func (a TwitterApi) GetUserTimeline(v url.Values) (timeline []Tweet, err error)
func (TwitterApi) GetUsersLookup ¶
func (TwitterApi) GetUsersLookupByIds ¶
func (TwitterApi) GetUsersShow ¶
func (TwitterApi) GetUsersShowById ¶
func (TwitterApi) PostDMToScreenName ¶
func (a TwitterApi) PostDMToScreenName(text, screenName string) (message DirectMessage, err error)
https://dev.twitter.com/docs/api/1.1/post/direct_messages/new
func (TwitterApi) PostDMToUserId ¶
func (a TwitterApi) PostDMToUserId(text string, userId int64) (message DirectMessage, err error)
https://dev.twitter.com/docs/api/1.1/post/direct_messages/new
func (*TwitterApi) ReturnRateLimitError ¶
func (c *TwitterApi) ReturnRateLimitError(b bool)
ReturnRateLimitError specifies behavior when the Twitter API returns a rate-limit error. If set to true, the query will fail and return the error instead of automatically queuing and retrying the query when the rate limit expires
func (TwitterApi) Retweet ¶
func (a TwitterApi) Retweet(id int64, trimUser bool) (rt Tweet, err error)
Retweet will retweet the status (tweet) with the specified ID. trimUser functions as in DeleteTweet
func (*TwitterApi) SetDelay ¶
func (c *TwitterApi) SetDelay(t time.Duration)
SetDelay will set the delay between throttled queries To turn of throttling, set it to 0 seconds
func (TwitterApi) VerifyCredentials ¶
func (a TwitterApi) VerifyCredentials() (ok bool, err error)
Verify the credentials by making a very small request
type TwitterError ¶
TwitterError represents a single Twitter error messages/code pair
func (TwitterError) Error ¶
func (te TwitterError) Error() string
type TwitterErrorResponse ¶
type TwitterErrorResponse struct {
Errors []TwitterError `json:"errors"`
}
TwitterErrorResponse has an array of Twitter error messages It satisfies the "error" interface For the most part, Twitter seems to return only a single error message Currently, we assume that this always contains exactly one error message
func (TwitterErrorResponse) Error ¶
func (tr TwitterErrorResponse) Error() string
func (TwitterErrorResponse) First ¶
func (tr TwitterErrorResponse) First() error
type User ¶
type User struct { ContributorsEnabled bool `json:"contributors_enabled"` CreatedAt string `json:"created_at"` DefaultProfile bool `json:"default_profile"` DefaultProfileImage bool `json:"default_profile_image"` Description string `json:"description"` FavouritesCount int `json:"favourites_count"` FollowRequestSent bool `json:"follow_request_sent"` FollowersCount int `json:"followers_count"` Following bool `json:"following"` FriendsCount int `json:"friends_count"` GeoEnabled bool `json:"geo_enabled"` Id int64 `json:"id"` IdStr string `json:"id_str"` IsTranslator bool `json:"is_translator"` Lang string `json:"lang"` ListedCount int64 `json:"listed_count"` Location string `json:"location"` Name string `json:"name"` Notifications bool `json:"notifications"` ProfileBackgroundColor string `json:"profile_background_color"` ProfileBackgroundImageURL string `json:"profile_background_image_url"` ProfileBackgroundImageUrlHttps string `json:"profile_background_image_url_https"` ProfileBackgroundTile bool `json:"profile_background_tile"` ProfileImageURL string `json:"profile_image_url"` ProfileImageUrlHttps string `json:"profile_image_url_https"` ProfileLinkColor string `json:"profile_link_color"` ProfileSidebarBorderColor string `json:"profile_sidebar_border_color"` ProfileSidebarFillColor string `json:"profile_sidebar_fill_color"` ProfileTextColor string `json:"profile_text_color"` ProfileUseBackgroundImage bool `json:"profile_use_background_image"` Protected bool `json:"protected"` ScreenName string `json:"screen_name"` ShowAllInlineMedia bool `json:"show_all_inline_media"` Status *Tweet `json:"status"` // Only included if the user is a friend StatusesCount int64 `json:"statuses_count"` TimeZone string `json:"time_zone"` URL string `json:"url"` UtcOffset int `json:"utc_offset"` Verified bool `json:"verified"` }