tiktok

README

go-tiktok/tiktok

A pure-Go, dependency-free, best-effort read client for public TikTok content, talking to TikTok's undocumented web JSON endpoints.

• CGO_ENABLED=0, standard library only, zero third-party dependencies.
• Stable, small Go API with an overridable base URL for network-free testing.
• 100% test coverage against a mock server.

⚠️ Fragility & Terms-of-Service caveat

Read this before depending on the library.

TikTok does not publish or support a public web API. This client calls the same internal endpoints TikTok's own website uses, and TikTok actively defends them. In practice you should expect:

• Requests often need a valid msToken (query parameter and cookie) and a signed parameter (X-Bogus / _signature) that this library does not compute. Many reads additionally require a logged-in sessionid cookie.
• TikTok returns anti-bot responses — HTTP 403/429, or an HTTP 200 with an empty or {} body — when it decides a request looks automated.
• The endpoint shape, parameters, and response schema can change without notice, breaking this library at any time.

This project is therefore best-effort: the code builds correct requests and parses correct responses, but working end-to-end against live TikTok is not guaranteed and is not something the maintainers can promise to keep working.

You are responsible for complying with TikTok's Terms of Service and all applicable law and rate limits. Do not use this for anything abusive, high-volume, or that TikTok's terms prohibit.

Install

go get github.com/go-tiktok/tiktok

Usage

package main

import (
	"context"
	"fmt"
	"log"

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

func main() {
	c := tiktok.New(
		tiktok.WithMSToken("...msToken from a browser session..."),
		tiktok.WithSessionID("...sessionid cookie for authed reads..."),
	)

	// secUid is TikTok's opaque per-user id; obtain it once from a profile
	// page's embedded JSON, then pass it here.
	feed, err := c.UserPosts(context.Background(), "MS4wLjABAAAA...", 20, "0")
	if err != nil {
		log.Fatal(err)
	}

	for _, v := range feed.Videos {
		fmt.Printf("%s  %d likes  %s\n", v.Permalink, v.Likes, v.Description)
	}
	fmt.Printf("cursor=%s hasMore=%v\n", feed.Cursor, feed.HasMore)
}

An empty page (no videos, HasMore == false) is returned without error. A non-2xx status, an empty/anti-bot body, or malformed JSON returns a descriptive error including the HTTP status where relevant.

API

Symbol	Purpose
New(...Option) *Client	Construct a client.
WithHTTPClient, WithBaseURL, WithUserAgent, WithMSToken, WithSessionID	Options.
(*Client).UserPosts(ctx, secUid, count, cursor) (*UserFeed, error)	Fetch a user's recent videos via the web item_list API.
Video, UserFeed	Result types.

License

BSD-3-Clause. Copyright the go-tiktok/tiktok authors. See LICENSE.

Documentation

Overview

Package tiktok is a pure-Go, dependency-free, best-effort read client for public TikTok content, talking to TikTok's undocumented web JSON endpoints.

Best-effort and fragile by nature

TikTok does not publish or support a stable public web API. The endpoints used here are the ones its own website calls, and TikTok actively defends them: requests frequently require a valid msToken query parameter/cookie, a signed "X-Bogus"/"_signature" parameter, and often a logged-in sessionid cookie. TikTok also returns anti-bot responses (HTTP 403/429, or a 200 with an empty "{}" body) when it decides a request looks automated.

Consequently this client is BEST-EFFORT: it builds correct requests and parses correct responses, but it can and will break without notice when TikTok changes its web API or tightens its bot defenses. Use it accordingly, respect TikTok's Terms of Service, and do not rely on it for anything critical. Supplying msToken via WithMSToken and a sessionid via WithSessionID improves — but does not guarantee — success.

Index

• Constants
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) UserPosts(ctx context.Context, secUid string, count int, cursor string) (*UserFeed, error)
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithMSToken(t string) Option
  • func WithSessionID(s string) Option
  • func WithUserAgent(ua string) Option
• type UserFeed
• type Video

Constants

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

DefaultBaseURL is the default TikTok web origin.

const DefaultUserAgent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) " +
	"AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"

DefaultUserAgent is a plausible desktop browser User-Agent. TikTok inspects this header; an empty or obviously automated value is more likely blocked.

Types

type Client

type Client struct {
	// BaseURL is the TikTok web origin (default https://www.tiktok.com).
	BaseURL string
	// HTTPClient performs requests (default http.DefaultClient).
	HTTPClient *http.Client
	// UserAgent is sent as the User-Agent header.
	UserAgent string
	// MSToken is TikTok's msToken, sent as both a query param and a cookie
	// when non-empty.
	MSToken string
	// SessionID is the sessionid cookie for authenticated reads, sent when
	// non-empty.
	SessionID string
}

Client is a best-effort read client for public TikTok content.

A zero Client is not ready for use; construct one with New.

func New

func New(opts ...Option) *Client

New constructs a Client with the given options applied.

func (*Client) UserPosts

func (c *Client) UserPosts(ctx context.Context, secUid string, count int, cursor string) (*UserFeed, error)

UserPosts fetches a user's recent videos via TikTok's web item_list API:

GET {BaseURL}/api/post/item_list/?secUid=<secUid>&count=<n>&cursor=<c>&...

The secUid is TikTok's opaque secondary user id; the caller obtains it once (for example from a profile page's embedded JSON) and passes it here. count is the requested page size and cursor is the pagination cursor ("0" or "" for the first page). Headers (User-Agent, Referer) and cookies (sessionid, msToken) are set when configured.

An empty result (no videos, HasMore=false) is returned without error. A non-2xx status, an empty/anti-bot body, or malformed JSON returns an error.

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the TikTok web origin (useful for testing).

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets the underlying http.Client.

func WithMSToken

func WithMSToken(t string) Option

WithMSToken sets the msToken query param / cookie.

func WithSessionID

func WithSessionID(s string) Option

WithSessionID sets the sessionid cookie for authenticated reads.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent overrides the User-Agent header.

type UserFeed

type UserFeed struct {
	Username string
	Videos   []Video
	Cursor   string
	HasMore  bool
}

UserFeed is a page of a user's videos.

type Video

type Video struct {
	ID          string
	Description string
	Author      string // unique_id / username
	Permalink   string // https://www.tiktok.com/@<author>/video/<id>
	CoverURL    string // thumbnail
	PlayURL     string // video URL (often expiring)
	Likes       int
	Comments    int
	Shares      int
	Plays       int
	CreateTime  time.Time
}

Video is a single public TikTok video.