reddit

README

go-reddit/reddit

A dependency-free (stdlib-only, CGO=0) Go client for Reddit's public JSON API. It powers the go-reddit/reader macOS app and the go-ruby-reddit Ruby binding, but stands on its own.

• Zero dependencies — only the Go standard library, so it builds for every Go target (all six 64-bit arches) with CGO_ENABLED=0.
• Anonymous or OAuth — read public listings anonymously, or authenticate with the app-only (client_credentials) or script (password) grant. Reddit increasingly blocks the anonymous .json endpoints with a 403; OAuth is the reliable path for server-side and datacenter callers.
• 100% test coverage, including every error branch.

Install

go get github.com/go-reddit/reddit

Usage

package main

import (
	"context"
	"fmt"

	"github.com/go-reddit/reddit"
)

func main() {
	// A descriptive User-Agent is required; Reddit rate-limits generic ones.
	c := reddit.NewClient(reddit.WithUserAgent("myapp/1.0 (by /u/you)"))

	page, err := c.Subreddit(context.Background(), "golang", reddit.SortHot,
		reddit.ListingOptions{Limit: 25})
	if err != nil {
		panic(err)
	}
	for _, p := range page.Posts {
		fmt.Printf("%5d  %s  (u/%s)\n", p.Score, p.Title, p.Author)
	}

	// Page with the returned cursor:
	next, _ := c.Subreddit(context.Background(), "golang", reddit.SortHot,
		reddit.ListingOptions{Limit: 25, After: page.After})
	_ = next
}

OAuth (recommended for anything server-side)

Register an app at https://www.reddit.com/prefs/apps to get a client id and secret, then:

// Application-only: read public content, no user account.
c := reddit.NewClient(
	reddit.WithUserAgent("myapp/1.0 (by /u/you)"),
	reddit.WithOAuth(clientID, clientSecret),
)

// Or the "script app" grant, acting as a specific user:
c = reddit.NewClient(
	reddit.WithUserAgent("myapp/1.0 (by /u/you)"),
	reddit.WithOAuthScript(clientID, clientSecret, username, password),
)

The client fetches and caches the bearer token automatically, refreshing it before expiry, and routes requests through oauth.reddit.com.

Comments

res, _ := c.Comments(context.Background(), "golang", "abc123",
	reddit.ListingOptions{Limit: 100})
fmt.Println(res.Post.Title)
for _, cm := range res.Comments {   // Replies nested recursively
	fmt.Printf("u/%s: %s\n", cm.Author, cm.Body)
}

API

Method	Endpoint
Subreddit(ctx, name, sort, opts)	r/<name>/<sort>.json
Frontpage(ctx, sort, opts)	/<sort>.json (logged-out front page)
Comments(ctx, subreddit, id, opts)	r/<sub>/comments/<id>.json

Sorts: SortHot, SortNew, SortTop, SortRising, SortControvers, SortBest. Time windows for top/controversial: TimeHour … TimeAll.

Non-2xx responses surface as a typed *reddit.APIError carrying the status code, so callers can distinguish a 429 (rate limit) from a 403 (blocked) or a 404 (gone).

License

BSD-3-Clause — see LICENSE. Copyright the go-reddit/reddit authors.

Documentation

Overview

Package reddit is a dependency-free (stdlib-only, CGO=0) client for Reddit's public read-only JSON API.

It targets the anonymous endpoints that back every subreddit and post page — appending ".json" to any Reddit URL returns the same listing the site renders. No OAuth, no API key: the only requirement Reddit enforces on anonymous traffic is a descriptive, non-generic User-Agent (a missing or browser-mimicking UA earns a 429). Set one with WithUserAgent.

The client is deliberately small and allocation-light so it can be reused unchanged from a native binary, a wasm proxy, or a Ruby binding (github.com/go-ruby-reddit). It builds for every Go target, cgo disabled.

Index

• Constants
• type APIError
  • func (e *APIError) Error() string
• type Client
  • func NewClient(opts ...Option) *Client
  • func (c *Client) Comments(ctx context.Context, subreddit, id string, opts ListingOptions) (*PostWithComments, error)
  • func (c *Client) Frontpage(ctx context.Context, sort Sort, opts ListingOptions) (*Page, error)
  • func (c *Client) SearchSubreddits(ctx context.Context, query string, opts ListingOptions) (*SubredditPage, error)
  • func (c *Client) Subreddit(ctx context.Context, name string, sort Sort, opts ListingOptions) (*Page, error)
• type Comment
  • func (c Comment) Created() time.Time
• type ListingOptions
• type Option
  • func WithBaseURL(base string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithOAuth(clientID, clientSecret string) Option
  • func WithOAuthScript(clientID, clientSecret, username, password string) Option
  • func WithSessionCookie(cookie string) Option
  • func WithUserAgent(ua string) Option
• type Page
• type Post
  • func (p Post) Created() time.Time
  • func (p Post) FullPermalink() string
  • func (p Post) HasThumbnail() bool
• type PostWithComments
• type Sort
• type SubredditInfo
• type SubredditPage
• type TimeRange

Constants

const DefaultBaseURL = "https://www.reddit.com"

DefaultBaseURL is Reddit's canonical JSON host. The "www" host (rather than "old" or "api") returns the modern listing schema this package decodes.

const DefaultUserAgent = "go-reddit/reddit (+https://github.com/go-reddit/reddit)"

DefaultUserAgent identifies this library. Reddit rate-limits anonymous requests that omit a UA or impersonate a browser, so callers are strongly encouraged to override this with WithUserAgent using their own contact string (Reddit's guidance: "<platform>:<app-id>:<version> (by /u/<name>)").

Types

type APIError

type APIError struct {
	StatusCode int
	Status     string
	Body       string
}

APIError is returned when Reddit responds with a non-2xx status. It carries the HTTP status code and a short snippet of the body for diagnosis (Reddit serves an HTML or JSON error page on 403/429/5xx).

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client fetches listings and comments from Reddit's public JSON API. The zero value is not usable; construct one with NewClient. A Client is safe for concurrent use as long as the underlying http.Client is.

func NewClient

func NewClient(opts ...Option) *Client

NewClient returns a Client with sensible defaults (a 30-second HTTP timeout, the canonical base URL, and DefaultUserAgent), then applies each Option in order.

func (*Client) Comments

func (c *Client) Comments(ctx context.Context, subreddit, id string, opts ListingOptions) (*PostWithComments, error)

Comments fetches a post and its comment tree. The comments endpoint returns a two-element array: [ Listing(the post), Listing(the comments) ]. subreddit may be blank (Reddit resolves the post by id alone) but supplying it avoids a redirect. id is the base-36 post id ("abc123"), with or without the "t3_" prefix.

func (*Client) Frontpage

func (c *Client) Frontpage(ctx context.Context, sort Sort, opts ListingOptions) (*Page, error)

Frontpage fetches the logged-out front page under the given sort (blank defaults to SortHot). This is r/all-ish aggregate content, not a personalised feed (anonymous access has no account).

func (*Client) SearchSubreddits

func (c *Client) SearchSubreddits(ctx context.Context, query string, opts ListingOptions) (*SubredditPage, error)

SearchSubreddits searches Reddit for subreddits whose name, title or description matches query, returning a page of results. Subreddit names cannot be enumerated, so this search endpoint is how a UI discovers them; a caller can further filter the returned names/descriptions locally (e.g. by a regular expression). A blank query is rejected. ListingOptions.Limit (Reddit clamps to 100) and After paginate. Works anonymously or with a configured session cookie / OAuth.

func (*Client) Subreddit

func (c *Client) Subreddit(ctx context.Context, name string, sort Sort, opts ListingOptions) (*Page, error)

Subreddit fetches a page of posts from r/<name> under the given sort. A blank sort defaults to SortHot; a blank name is rejected. The special name "all" and "popular" resolve to Reddit's aggregate feeds.

type Comment

type Comment struct {
	ID         string    `json:"id"`
	Fullname   string    `json:"name"`
	Author     string    `json:"author"`
	Body       string    `json:"body"`
	Score      int       `json:"score"`
	CreatedUTC float64   `json:"created_utc"`
	Stickied   bool      `json:"stickied"`
	Replies    []Comment `json:"-"`
}

Comment is a single "t1" thing in a comment tree. Replies is populated recursively; leaf comments (or the truncated "load more" frontier) have a nil slice.

func (Comment) Created

func (c Comment) Created() time.Time

Created returns the comment's creation time in UTC.

type ListingOptions

type ListingOptions struct {
	// Limit caps the number of posts returned (Reddit clamps to 100).
	Limit int
	// After is the fullname ("t3_xxxxxx") to page from; use [Page.After].
	After string
	// Time scopes SortTop / SortControvers; ignored otherwise.
	Time TimeRange
}

ListingOptions tunes a listing request. The zero value asks Reddit for its default page size starting at the top of the listing.

type Option

type Option func(*Client)

Option customises a Client at construction time.

func WithBaseURL

func WithBaseURL(base string) Option

WithBaseURL overrides the API host. Primarily a test seam (point it at an httptest server); an empty string is ignored. Any trailing slash is trimmed so path joining stays predictable.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient supplies the http.Client used for every request. Use it to inject timeouts, proxies, or a test transport. A nil client is ignored.

func WithOAuth

func WithOAuth(clientID, clientSecret string) Option

WithOAuth configures application-only ("client_credentials") OAuth using a registered script/web app's client id and secret. This grants read access to public listings without a user account and works from IPs where the anonymous ".json" endpoints are blocked. Empty credentials are ignored (the Client stays anonymous).

func WithOAuthScript

func WithOAuthScript(clientID, clientSecret, username, password string) Option

WithOAuthScript configures the resource-owner-password ("script app") grant, authenticating as a specific Reddit user. Use it when you need per-user context; otherwise prefer WithOAuth. Empty credentials are ignored.

func WithSessionCookie

func WithSessionCookie(cookie string) Option

WithSessionCookie authenticates reads with a logged-in browser's reddit_session cookie instead of OAuth. Reddit's self-serve OAuth registration is effectively closed to new personal projects, so supplying the cookie from an already-signed-in browser is the practical path for individual, read-only use.

The argument may be either the bare reddit_session value or a full "reddit_session=…; other=…" Cookie header string; both normalise to a Cookie header value (a bare value is wrapped as "reddit_session=<value>"; a string that already contains "name=value" pairs is used verbatim). Surrounding whitespace is trimmed and an empty (or whitespace-only) argument is ignored.

Unlike WithOAuth, this keeps the default www base URL — the cookie authenticates the same anonymous ".json" endpoints. When both a session cookie and OAuth are configured, the session cookie takes precedence: the request carries the Cookie header and no Bearer token.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header. An empty string is ignored so the DefaultUserAgent always remains in effect. Reddit blocks generic agents, so production callers should pass a unique, descriptive value.

type Page

type Page struct {
	Posts  []Post
	After  string
	Before string
}

Page is a decoded listing: the posts plus the paging cursors Reddit returns. After is the fullname to pass back via ListingOptions.After to fetch the next page ("" when the listing is exhausted).

type Post

type Post struct {
	ID          string  `json:"id"`
	Fullname    string  `json:"name"` // e.g. "t3_abc123", used for paging/After
	Title       string  `json:"title"`
	Author      string  `json:"author"`
	Subreddit   string  `json:"subreddit"`
	Permalink   string  `json:"permalink"`
	URL         string  `json:"url"`
	Domain      string  `json:"domain"`
	SelfText    string  `json:"selftext"`
	Thumbnail   string  `json:"thumbnail"`
	Score       int     `json:"score"`
	Ups         int     `json:"ups"`
	NumComments int     `json:"num_comments"`
	CreatedUTC  float64 `json:"created_utc"`
	IsSelf      bool    `json:"is_self"`
	Over18      bool    `json:"over_18"`
	Stickied    bool    `json:"stickied"`
	Flair       string  `json:"link_flair_text"`
}

Post is a single link or self-post ("t3" thing). Fields mirror the subset of Reddit's JSON that a reader UI needs; unmapped fields are dropped.

func (Post) Created

func (p Post) Created() time.Time

Created returns the post's creation time in UTC.

func (Post) FullPermalink

func (p Post) FullPermalink() string

FullPermalink joins the site-relative Permalink onto the canonical host so it is directly openable. Reddit's permalinks already begin with "/".

func (Post) HasThumbnail

func (p Post) HasThumbnail() bool

HasThumbnail reports whether Thumbnail is a real image URL rather than one of Reddit's sentinel strings ("self", "default", "nsfw", "spoiler", "").

type PostWithComments

type PostWithComments struct {
	Post     Post
	Comments []Comment
}

PostWithComments bundles a resolved post with its (partial) comment tree, as returned by the /comments/<id> endpoint.

type Sort

type Sort string

Sort selects the ordering of a listing endpoint.

const (
	SortHot        Sort = "hot"
	SortNew        Sort = "new"
	SortTop        Sort = "top"
	SortRising     Sort = "rising"
	SortControvers Sort = "controversial"
	SortBest       Sort = "best"
)

Listing sort orders understood by Reddit. Best is only meaningful on the logged-out front page; the rest apply to any subreddit.

type SubredditInfo

type SubredditInfo struct {
	Name              string // display_name, e.g. "golang" (subscribe as r/<Name>)
	Title             string // human title
	PublicDescription string // short public blurb
	Subscribers       int64  // subscriber count
	Over18            bool   // NSFW flag
	URL               string // path, e.g. "/r/golang/"
	Type              string // subreddit_type: public / restricted / private
}

SubredditInfo is a subreddit's metadata as returned by the search and listing endpoints (a Reddit "t5" thing). It carries what a discovery UI needs to show a result and let the user subscribe by Name.

type SubredditPage

type SubredditPage struct {
	Subreddits []SubredditInfo
	After      string
	Before     string
}

SubredditPage is a page of subreddit search results. After is the fullname to pass back via ListingOptions.After for the next page ("" when exhausted).

type TimeRange

type TimeRange string

TimeRange scopes SortTop / SortControvers to a window. Ignored by other sorts.

const (
	TimeHour  TimeRange = "hour"
	TimeDay   TimeRange = "day"
	TimeWeek  TimeRange = "week"
	TimeMonth TimeRange = "month"
	TimeYear  TimeRange = "year"
	TimeAll   TimeRange = "all"
)

Time windows for the "top" and "controversial" sorts.