Go Twitter REST and Streaming API v1.1

Overview

go-twitter Build Status GoDoc

go-twitter is a Go client library for the Twitter API. Check the usage section or try the examples to see how to access the Twitter API.

Features

  • Twitter REST API:
    • Accounts
    • DirectMessageEvents
    • Favorites
    • Friends
    • Friendships
    • Followers
    • Lists
    • PremiumSearch
    • RateLimits
    • Search
    • Statuses
    • Timelines
    • Users
  • Twitter Streaming API
    • Public Streams
    • User Streams
    • Site Streams
    • Firehose Streams

Install

go get github.com/dghubble/go-twitter/twitter

Documentation

Read GoDoc

Usage

REST API

The twitter package provides a Client for accessing the Twitter API. Here are some example requests.

config := oauth1.NewConfig("consumerKey", "consumerSecret")
token := oauth1.NewToken("accessToken", "accessSecret")
httpClient := config.Client(oauth1.NoContext, token)

// Twitter client
client := twitter.NewClient(httpClient)

// Home Timeline
tweets, resp, err := client.Timelines.HomeTimeline(&twitter.HomeTimelineParams{
    Count: 20,
})

// Send a Tweet
tweet, resp, err := client.Statuses.Update("just setting up my twttr", nil)

// Status Show
tweet, resp, err := client.Statuses.Show(585613041028431872, nil)

// Search Tweets
search, resp, err := client.Search.Tweets(&twitter.SearchTweetParams{
    Query: "gopher",
})

// User Show
user, resp, err := client.Users.Show(&twitter.UserShowParams{
    ScreenName: "dghubble",
})

// Followers
followers, resp, err := client.Followers.List(&twitter.FollowerListParams{})

Authentication is handled by the http.Client passed to NewClient to handle user auth (OAuth1) or application auth (OAuth2). See the Authentication section.

Required parameters are passed as positional arguments. Optional parameters are passed typed params structs (or nil).

Streaming API

The Twitter Public, User, Site, and Firehose Streaming APIs can be accessed through the Client StreamService which provides methods Filter, Sample, User, Site, and Firehose.

Create a Client with an authenticated http.Client. All stream endpoints require a user auth context so choose an OAuth1 http.Client.

client := twitter.NewClient(httpClient)

Next, request a managed Stream be started.

Filter

Filter Streams return Tweets that match one or more filtering predicates such as Track, Follow, and Locations.

params := &twitter.StreamFilterParams{
    Track: []string{"kitten"},
    StallWarnings: twitter.Bool(true),
}
stream, err := client.Streams.Filter(params)

User

User Streams provide messages specific to the authenticate User and possibly those they follow.

params := &twitter.StreamUserParams{
    With:          "followings",
    StallWarnings: twitter.Bool(true),
}
stream, err := client.Streams.User(params)

Note To see Direct Message events, your consumer application must ask Users for read/write/DM access to their account.

Sample

Sample Streams return a small sample of public Tweets.

params := &twitter.StreamSampleParams{
    StallWarnings: twitter.Bool(true),
}
stream, err := client.Streams.Sample(params)

Site, Firehose

Site and Firehose Streams require your application to have special permissions, but their API works the same way.

Receiving Messages

Each Stream maintains the connection to the Twitter Streaming API endpoint, receives messages, and sends them on the Stream.Messages channel.

Go channels support range iterations which allow you to read the messages which are of type interface{}.

for message := range stream.Messages {
    fmt.Println(message)
}

If you run this in your main goroutine, it will receive messages forever unless the stream stops. To continue execution, receive messages using a separate goroutine.

Demux

Receiving messages of type interface{} isn't very nice, it means you'll have to type switch and probably filter out message types you don't care about.

For this, try a Demux, like SwitchDemux, which receives messages and type switches them to call functions with typed messages.

For example, say you're only interested in Tweets and Direct Messages.

demux := twitter.NewSwitchDemux()
demux.Tweet = func(tweet *twitter.Tweet) {
    fmt.Println(tweet.Text)
}
demux.DM = func(dm *twitter.DirectMessage) {
    fmt.Println(dm.SenderID)
}

Pass the Demux each message or give it the entire Stream.Message channel.

for message := range stream.Messages {
    demux.Handle(message)
}
// or pass the channel
demux.HandleChan(stream.Messages)

Stopping

The Stream will stop itself if the stream disconnects and retrying produces unrecoverable errors. When this occurs, Stream will close the stream.Messages channel, so execution will break out of any message for range loops.

When you are finished receiving from a Stream, call Stop() which closes the connection, channels, and stops the goroutine before returning. This ensures resources are properly cleaned up.

Pitfalls

Bad: In this example, Stop() is unlikely to be reached. Control stays in the message loop unless the Stream becomes disconnected and cannot retry.

// program does not terminate :(
stream, _ := client.Streams.Sample(params)
for message := range stream.Messages {
    demux.Handle(message)
}
stream.Stop()

Bad: Here, messages are received on a non-main goroutine, but then Stop() is called immediately. The Stream is stopped and the program exits.

// got no messages :(
stream, _ := client.Streams.Sample(params)
go demux.HandleChan(stream.Messages)
stream.Stop()

Good: For main package scripts, one option is to receive messages in a goroutine and wait for CTRL-C to be pressed, then explicitly stop the Stream.

stream, err := client.Streams.Sample(params)
go demux.HandleChan(stream.Messages)

// Wait for SIGINT and SIGTERM (HIT CTRL-C)
ch := make(chan os.Signal)
signal.Notify(ch, syscall.SIGINT, syscall.SIGTERM)
log.Println(<-ch)

stream.Stop()

Authentication

The API client accepts an any http.Client capable of making user auth (OAuth1) or application auth (OAuth2) authorized requests. See the dghubble/oauth1 and golang/oauth2 packages which can provide such agnostic clients.

Passing an http.Client directly grants you control over the underlying transport, avoids dependencies on particular OAuth1 or OAuth2 packages, and keeps client APIs separate from authentication protocols.

See the google/go-github client which takes the same approach.

For example, make requests as a consumer application on behalf of a user who has granted access, with OAuth1.

// OAuth1
import (
    "github.com/dghubble/go-twitter/twitter"
    "github.com/dghubble/oauth1"
)

config := oauth1.NewConfig("consumerKey", "consumerSecret")
token := oauth1.NewToken("accessToken", "accessSecret")
// http.Client will automatically authorize Requests
httpClient := config.Client(oauth1.NoContext, token)

// Twitter client
client := twitter.NewClient(httpClient)

If no user auth context is needed, make requests as your application with application auth.

// OAuth2
import (
    "github.com/dghubble/go-twitter/twitter"
    "golang.org/x/oauth2"
    "golang.org/x/oauth2/clientcredentials"
)

// oauth2 configures a client that uses app credentials to keep a fresh token
config := &clientcredentials.Config{
    ClientID:     "consumerKey",
    ClientSecret: "consumerSecret",
    TokenURL:     "https://api.twitter.com/oauth2/token",
}
// http.Client will automatically authorize Requests
httpClient := config.Client(oauth2.NoContext)

// Twitter client
client := twitter.NewClient(httpClient)

To implement Login with Twitter for web or mobile, see the gologin package and examples.

Roadmap

  • Support gzipped streams
  • Auto-stop streams in the event of long stalls

Contributing

See the Contributing Guide.

License

MIT License

Issues
  • Support new Direct Message Events API

    Support new Direct Message Events API

    The existing API's for Direct Messages is being shut down on Aug 16st, 2018: https://twitter.com/TwitterDev/status/996783000741384192

    This pull request is based on @listonb work in https://github.com/dghubble/go-twitter/pull/87

    No tests have been written for this single, new API call. However, before I spend anymore time on this I would like to see this discussed/approved/merged so I can continue to use the this great library.

    opened by Xeoncross 9
  • Fix StreamService.User(): parse very long friend ID lists properly

    Fix StreamService.User(): parse very long friend ID lists properly

    Fixes #73 by replacing bufio.Scanner with bufio.Reader for parsing streaming data.

    bufio.Scanner has a line length limit (65,536 bytes by default), which will cause a problem when a user has a large number of friends (say 7,000) and Twitter sends the list of all friend IDs right after establishing User Stream connection. bufio.Reader doesn't have the limit and the same problem won't happen.

    opened by mickey24 9
  • Adding Place support

    Adding Place support

    Hey There,

    I saw you've got a lot of existing tests but no marshalling tests, so I've put some test json files from actual tweets into a test directory (I don't know whether you think this is clutter or not? I like to abstract out the parsing from the other components). I've added in place support with a test case that validates parsing. I've been using this library a lot and really like it so when I saw the TODO I thought "Bugger it, I'll do that!" Please let me know if you think this is just awful garbage but I'm happy to help build out this library and support it as I use it quite a lot

    Cheers!

    Dan

    opened by dannolan 7
  • Support media upload

    Support media upload

    Hello, I added the required functions to upload media to twitter. I'll work on testing & simple refactoring during the next 2 days. feel free to merge it now since refactoring and updates can be in a sperate PRs

    opened by ahmedash95 6
  • Feature/media upload

    Feature/media upload

    Add functionality to upload images to twitter to embed in tweet.

    Example code:

    	Ids := []int64{MediaId.MediaId}
    	UpdateParams := &twitter.StatusUpdateParams{MediaIds: Ids};
    	client.Statuses.Update("test", UpdateParams);
    

    Added unit tests.

    opened by jlentink 6
  • Add a bunch of missing video fields.

    Add a bunch of missing video fields.

    I didn't see any tests that verify the structure of the mapping, but I'll gladly add one if desired.

    Here's a tweet you can test this with: https://twitter.com/h__mutsu/status/748848827096895488

    opened by rubenv 6
  • Fix small memory leak while retrying streams

    Fix small memory leak while retrying streams

    The time.After docs call out that if you don't receive on the given timer it will never be GCd (similar to time.Tick which is more explicit in its warning).

    opened by euank 4
  • Remove comment to avoid IDE to identify Tweet type struct as deprecated

    Remove comment to avoid IDE to identify Tweet type struct as deprecated

    The comment on line 12 includes the word "Deprecated". This is causing some IDEs to mark the entire type struct as deprecated, causing warnings to be issued every time code using the type struct is committed.

    opened by ldconejo 3
  • Add support for fetching extended tweets in lists

    Add support for fetching extended tweets in lists

    While fetching tweets from Twitter lists, I realized that the current version of the parameters struct does not allow for requesting extended tweet text support. The result is that all tweets longer than 140 chars end up being cut at that mark.

    I wasn't really sure, whether the lists API supports that option, so I forked the repo, added it in and tested it out. I started receiving the full text right away.

    We are currently pointing our app's build at my fork, but it would be great to accept this change in the official repo.

    Thanks!

    opened by preslavrachev 2
  • Adds basic account account activities API and DM improvements

    Adds basic account account activities API and DM improvements

    I've ended up needing these endpoints for another project I'm working on. The account activities API isn't complete, but it's a starting point with the basics that people can use/base further work on.

    opened by stevenleeg 2
  • Add support for site stream messages

    Add support for site stream messages

    Fixes #69 and #66 by allowing the library to process {"for_user":...} type wrappers around Tweet and FriendsList structs and supporting the new {"control":...} entity.

    opened by Xeoncross 2
  • feat: add auto_populate_reply_metadata

    feat: add auto_populate_reply_metadata

    Hi @dghubble,

    this PR add support for auto_populate_reply_metadata in the StatusUpdateParamsstruct.

    From the docs:

    If set to true and used with in_reply_to_status_id, leading @mentions will be looked up from the original Tweet, and added to the new Tweet from there. This wil append @mentions into the metadata of an extended Tweet as a reply chain grows, until the limit on @mentions is reached.

    Would be cool to get this into your library.

    opened by dirien 0
  • Add struct for location attachment on DM.

    Add struct for location attachment on DM.

    Add support struct for location attachment. This struct is made from https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/message-attachments/guides/attaching-location .

    opened by toyo 0
  • Amend oembed param url tags for hide_thread and omit_script

    Amend oembed param url tags for hide_thread and omit_script

    The URL tags present on the StatusOEmbedParams struct for the HideThread and OmitScript field were both hide_media which results in unexpected behaviour when trying to use these options.

    With this PR I have set these to the correct URL tags, as outlined here: https://developer.twitter.com/en/docs/twitter-for-websites/timelines/guides/oembed-api.

    Thanks for your work and effort in maintaining this client!

    opened by chriskingnet 0
Owner
Dalton Hubble
Friends with the machines | Kubernetes | @poseidon Typhoon and Matchbox | Previously @lyft, @coreos, @twitter, MIT
Dalton Hubble
Go-twitter - Simple Prototype for Twitter with frontend and backend

Twitter Clone Introduction A Twitter clone created with Golang, PostgreSQL, Redi

James Hsu 3 Feb 21, 2022
A console based twitter client for displaying tweets from twitter lists

About I follow a bunch of people who span a bunch of topics and wanted a way to keep track of all the cool stuff they post. I figured there would cert

esell 30 May 23, 2022
wtf? paranormal twitter.com activity using Twitter Cards. Migros.tr #DoITYourself

GTKE - go-tweet-kart-ele wtf? paranormal twitter.com activity using Twitter Cards. Migros.tr #DoITYourself Just for fun. Go. # You have go. go install

Jan Hacker 0 Dec 7, 2021
A REST API microservices-based Twitter Clone server.

Simple API Twitter Clone A REST API microservices-based project to fetch, edit, post, and delete tweets. API documentation The API documentation is bu

null 1 May 13, 2022
A Go client library for the Twitter 1.1 API

Anaconda Anaconda is a simple, transparent Go package for accessing version 1.1 of the Twitter API. Successful API queries return native Go structs th

Aditya Mukerjee 1.1k Jun 15, 2022
Scrape the Twitter Frontend API without authentication with Golang.

Twitter Scraper Twitter's API is annoying to work with, and has lots of limitations — luckily their frontend (JavaScript) has it's own API, which I re

Nomadic 229 Jun 26, 2022
Periodically collect data about my Twitter account and check in to github to preserve an audit trail.

Twitter audit trail backup This repository backs up my follower list, following list, blocked accounts list and muted accounts list periodically using

Ahmet Alp Balkan 59 Jun 18, 2022
twitter clone front-end for Internet Engineering course - fall 99 built by go+echo

twitter backend build twitter-like back-end for internet engeering course - fall 99 with go+echo+gorm team mates Roozbeh Sharifnasab + Parsa Fadaee +

Roozbeh Sharifnasab 16 Mar 1, 2022
Twitter backend - Golang

A Twitter-like Website This repository contains the backend code for the final project of Fall 2020 Internet Engineering course. In this project,

ArmanAminian 68 Jun 24, 2022
Twitter ID Finder For Golang

Twitter ID Finder n文字の全数IDを探せます Usage $ make go build -o main main.go $ ./main Twitter ID Finder Creator: @_m_vt Digits: 2 Target IDs: 100 Really? [

null 0 Dec 12, 2021
An app/container built in Go to automate a Twitter account using Notion

Notion Tweeter Notion Tweeter is a utility I built using Go to help automate scheduling my tweets using Notion as a backend. More documentation coming

Brian Morrison II 1 Jan 13, 2022
Service that wrap up different movies-related APIs like IMDB and match it to streaming services

Service that wrap up different movies-related APIs like IMDB and match it to streaming services. That way you can check in which platforms you can find your favorite movies.

Xavier Graterol 2 Feb 10, 2022
This is a single-instance streaming server with chat.

Table of Contents AlbertoBroadcast stream server Build requirements Older Go Versions Compile and install Docker build Building the Container Running

Alberto van Eckeveld 0 Dec 24, 2021
StreamWall - WIP demo application which streams music in exchange for streaming sats

Stream Wall Music examples borrowed from https://ableandthewolf.com/ check them

null 2 Feb 14, 2022
go-whatsapp-rest-API is a Go library for the WhatsApp web which use Swagger as api interface

go-whatsapp-rest-API go-whatsapp-rest-API is a Go library for the WhatsApp web which use Swagger as api interface Multi-devices (MD) Support. This ver

null 16 May 13, 2022
Api-product - A basic REST-ish API that allows you to perform CRUD operations for Products

Description A basic REST-ish API that allows you to perform CRUD operations for

Abdul Salim 0 Jan 3, 2022
Lol-champions-api - A REST API app for CRUD' ing informations related to League of Legends champions, written with Go

LOL-CHAMPIONS-API Just a REST API app for CRUD' ing informations related to Leag

Furkan KARACA 3 Mar 17, 2022
Rest API to get KVB departures - Written in Go with hexagonal architecture and tracing via OpenTelemetry and Jaeger

KVB API Rest API to get upcoming departures per KVB train station Implemented in Go with hexagonal architecture and tracing via OpenTelemetry and Jaeg

Jan Ritter 3 May 7, 2022
Fluent JavaScript API for SharePoint and Microsoft Graph REST APIs

PnPjs is a fluent JavaScript API for consuming SharePoint and Microsoft Graph REST APIs in a type-safe way. You can use it with SharePoint Framework,

Microsoft 365 Community 595 Jun 21, 2022