twitter

README

go-birdsite / twitter

A pure-Go (CGO=0), dependency-free, best-effort read client for public Twitter/X profile timelines. It reads the public syndication timeline endpoint that powers embedded timeline widgets and extracts tweets from the __NEXT_DATA__ JSON blob.

c := twitter.New()
tl, err := c.UserTweets(context.Background(), "jack")
for _, tw := range tl.Tweets {
    fmt.Printf("@%s: %s (%d likes)\n", tw.Author, tw.Text, tw.Likes)
}

⚠️ Fragility & Terms of Service

This is inherently fragile. Twitter/X changes and locks these endpoints, and many profiles or rate states require a valid auth token (WithAuthToken). Blocked requests (403/429) surface as errors. Respect Twitter/X's Terms of Service and applicable law when using this library.

License

BSD-3-Clause © the go-birdsite/twitter authors.

Documentation

Overview

Package twitter is a dependency-free, best-effort read client for public Twitter/X profile timelines. It uses the public syndication timeline endpoint that powers embedded timeline widgets, extracting the tweets from the __NEXT_DATA__ JSON blob in the returned HTML.

This is inherently fragile: Twitter/X changes and locks these endpoints, and some profiles or rate states require a valid auth token. Requests that are blocked surface as errors rather than pretending to be reliable. Expect to need WithAuthToken for anything beyond light public reads.

Index

• Constants
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) UserTweets(ctx context.Context, screenName string) (*Timeline, error)
• type Media
• type Option
  • func WithAuthToken(t string) Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithUserAgent(ua string) Option
• type Timeline
• type Tweet

Constants

const DefaultBaseURL = "https://syndication.twitter.com"

DefaultBaseURL is the public syndication host.

Types

type Client

type Client struct {
	// BaseURL is the syndication host; defaults to DefaultBaseURL.
	BaseURL string
	// HTTPClient is used for all requests; defaults to http.DefaultClient.
	HTTPClient *http.Client
	// UserAgent is sent with every request.
	UserAgent string
	// AuthToken, when set, is sent as a bearer token for authenticated reads.
	AuthToken string
}

Client reads public profile timelines.

func New

func New(opts ...Option) *Client

New returns a Client with sane defaults.

func (*Client) UserTweets

func (c *Client) UserTweets(ctx context.Context, screenName string) (*Timeline, error)

UserTweets fetches the public profile timeline for screenName.

type Media

type Media struct {
	URL  string
	Type string // "photo" | "video" | "animated_gif"
}

Media is an attachment on a tweet.

type Option

type Option func(*Client)

Option configures a Client.

func WithAuthToken

func WithAuthToken(t string) Option

WithAuthToken sets an optional bearer token for authenticated reads.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the syndication host (used in tests).

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets the http.Client used for requests.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header.

type Timeline

type Timeline struct {
	Tweets []Tweet
}

Timeline is a page of tweets.

type Tweet

type Tweet struct {
	ID        string
	Text      string
	Author    string // screen name
	Permalink string
	CreatedAt time.Time
	Likes     int
	Retweets  int
	Replies   int
	Media     []Media
}

Tweet is a single normalized tweet.