Go Twitter REST and Streaming API v1.1


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.


  • 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


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


Read GoDoc



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 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 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 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 {

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.


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) {
demux.DM = func(dm *twitter.DirectMessage) {

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

for message := range stream.Messages {
// or pass the channel


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.


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 {

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)

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)

ch := make(chan os.Signal)
signal.Notify(ch, syscall.SIGINT, syscall.SIGTERM)



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 (

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 (

// 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.


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


See the Contributing Guide.


MIT License

  • Add `Retweeters` support for retweeters ids

    Add `Retweeters` support for retweeters ids

    Hi Dalton,

    I have added a Retweeters to support Statuses.Retweeters. It contains Retweeters function in statuses.go to get user_ids which retweet specific tweet. I have also added unit tests in the style of exist tests to test the functions.

    It's my pleasure for your pulling.


    opened by keaising 9
  • 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
  • Add AccountService UpdateProfileImage

    Add AccountService UpdateProfileImage

    • POST to account/update_profile_image.json to set specified user profile image
    • https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_image
    opened by jyap808 7
  • 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



    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.


    opened by preslavrachev 2
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 Oct 6, 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 Jan 1, 2023
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 311 Dec 29, 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 84 Dec 28, 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 15 Nov 9, 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 72 Nov 26, 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 2 Sep 26, 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
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 18 Dec 15, 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
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 3 Jul 9, 2022
Using Golang to complete ChatGPT streaming, making it easier to join your own project

chatGPT_streaming go语言使用openai的ChatGPT接口实践,使用流式传输,类似ChatGPT网页效果,并且可以让ChatGPT的服务单独部署(单独部署到非大中华区的服务器),并用grpc streaming 做中间层,保证不受墙的影响。使用websocket最终通信,后端考

费腾 6 May 11, 2023
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