omarthing

JavaScript / TypeScript client for the Omar-Thing TikTok API: profiles, followers, videos, comments, stories, hashtags, search and live data. No dependencies, Node 18+.

npm install omarthing

You need an API key from https://dev.omar-thing.site. Pass it in, or set OMARTHING_API_KEY.

import { Client } from 'omarthing';      // or: const { Client } = require('omarthing');

const api = new Client('YOUR_API_KEY');

const profile = await api.profile({ username: 'tiktok', format: 'clean' });
console.log(profile.nickname, profile.followers);

// paginated endpoints: feed next_cursor back in until has_more is false
let cursor;
do {
  const page = await api.posts({ username: 'tiktok', cursor, format: 'clean' });
  for (const post of page.posts) console.log(post.id, post.desc.slice(0, 60));
  cursor = page.has_more ? page.next_cursor : undefined;
} while (cursor);

Every method takes one object of query parameters and returns the data part of the response. Missing required parameters throw a TypeError before any request is made. Types for every endpoint are included.

Errors

import { Client, OmarThingError } from 'omarthing';

try {
  await new Client('YOUR_API_KEY').profile({ username: 'tiktok' });
} catch (err) {
  if (err instanceof OmarThingError) console.log(err.statusCode, err.code, err.message, err.requestId);
}

429 and 502/503/504 are retried (retries: 2, respects Retry-After). api.usage() shows your quota.

new Client('KEY', { baseUrl, timeout: 60000, retries: 2, fetch });   // all optional
new Client({ apiKey: 'KEY', timeout: 10000 });

api.request('endpoint_name', { ...params }) calls any endpoint by name, handy for endpoints added after this version.

Methods

Parameters for each endpoint are documented at https://dev.omar-thing.site/docs.html (OpenAPI spec: omarthing-openapi, Python: omarthing-python).

Content

| Method (* = required) | What it does | |---|---| | collectionVideos({ *collection_id, cursor, format }) | List the videos inside a TikTok collection (one raw page per call, cursor-paginated). | | collections({ *username, cursor, format }) | List a user's TikTok collections (cursor-paginated). | | commentReplies({ *video, *comment_id, cursor, format }) | All replies under one comment (one raw page per call, cursor-paginated). | | comments({ *video, filter, cursor, format }) | Fetch the comments on a video (id or URL). | | hashtagInfo({ name, id, format }) | Details of a hashtag - total views, number of videos, id and share link. | | hashtagVideos({ name, id, cursor, format }) | Videos posted under a hashtag (one page per call, cursor-paginated). | | highlights({ *username, format }) | Get a user's highlights - all collections and the stories inside each. | | mix({ *mix_id, cursor, format }) | Mix (creator playlist) details + the videos in it (one raw page per call, cursor-paginated). | | music({ *id, cursor, format }) | Sound/music details + the videos that use it (one raw page per call, cursor-paginated). | | posts({ *username, cursor, format }) | List the videos a user has posted (one raw page per call, cursor-paginated). | | reposts({ *username, cursor, with_repost_date, format }) | List the videos a user has reposted (one raw page per call, cursor-paginated). | | stories({ *username, cursor, format }) | Fetch a user's active stories. | | videoDownload({ *video }) | Get a video's download URLs per quality (including the original file) by id or URL. | | videoInfo({ *video, format }) | Full info for a video by id or URL (raw object, or clean subset). | | videoStatus({ *videos }) | Check up to 40 videos in one call - is each still available (not deleted/removed)? |

Live

| Method (* = required) | What it does | |---|---| | lastLive({ *username }) | Get a user's most recent live room by username - live now OR already ended - with its stats, duration, and top_fans (top | | live({ username, room_id }) | Check if a user is live and get the stream URLs (HLS + FLV) per quality. | | liveAudience({ *room_id, anchor_id, format }) | Top viewers currently in a live stream (the online-audience ranking, by contribution). | | liveChat({ *room_id, cursor }) | Live chat & events of a LIVE room (comments, gifts, joins, likes). | | liveGifts({ *room_id, cursor }) | Gifts being sent in a LIVE room right now (sender, gift name, coins, combo). | | liveStats({ username, user_id, history_limit }) | A creator's live-centre stats: live status, fans club and gifts, and the full broadcast history with per-stream likes an | | roomId({ *username }) | Get a user's live room_id by username (null if they're not live right now). |

Profiles & Users

| Method (* = required) | What it does | |---|---| | analytics({ username, user_id, sec_uid, days, video, format }) | Audience insights for a public creator account: follower breakdown by country, age and gender, an overview for a date ra | | currentRegion({ username, user_id, sec_uid }) | Get an account's current region (country) by its numeric user id. | | followers({ *username, cursor, format }) | List an account's followers. | | following({ *username, cursor, format }) | List the accounts a user follows. | | profile({ username, sec_uid, user_id, format }) | Fetch a user's profile by username. |

Search

| Method (* = required) | What it does | |---|---| | relatedSearches({ *video, query, format }) | Related search terms suggested under a video ("others searched for"). | | searchHashtags({ *query, cursor, format }) | Search hashtags (one page per call, cursor-paginated). | | searchMusic({ *query, cursor, format }) | Search sounds/music (one page per call, cursor-paginated). | | searchPhotos({ *query, cursor, format }) | Search photo/slideshow posts (one page per call, cursor-paginated). | | searchPlaces({ *query, country, cursor, format }) | Search places/POIs (venues, landmarks, restaurants). | | searchSuggest({ *query, format }) | Search autocomplete - the suggestions shown while you type. | | searchUsers({ *query, followers, verified, match, cursor, format }) | Search users/accounts (one page per call, cursor-paginated). | | searchVideos({ *query, date, sort, cursor, format }) | Search videos (one page per call, cursor-paginated). | | trendingSearches({ region, count }) | TikTok's rising search keywords for a region (what is being searched now). |

Utilities

| Method (* = required) | What it does | |---|---| | resolveUrl({ *url }) | Expand a TikTok share/short link and extract the user, video, and share info. |

Your Key

| Method (* = required) | What it does | |---|---| | usage() | Check your own key status: plan, remaining quota, and expiry. |

liveChat and liveGifts are polled: call them in a loop and pass the returned cursor back in.

License

MIT. Unofficial: not affiliated with or endorsed by TikTok or ByteDance.