search

EmilioBarradas / tiktok-app-api

🎵 Unofficial TikTok Node.js API
130 stars 21 forks source link

readme

TikTok API

This is an unofficial TypeScript and Node.js implementation of the TikTok API. This module is not endorsed by, directly affiliated with, maintained, authorized, or sponsored by TikTok. Their internal API could change at any moment, and break this module's code. I try my best to maintain it, and keep it up-to-date. If you find bugs or have any questions, please submit an issue, and I will try my best to help you out.

Table of Contents

Quick Examples

Get the follower count of a TikTok user:

const tiktok = require('tiktok-app-api');

let tiktokApp;

(async () => {
  tiktokApp = await tiktok();

  const user = await tiktokApp.getUserByName('example');
  const userInfo = await tiktokApp.getUserInfo(user);

  console.log(userInfo.followerCount);
})();

Get the tags of the top trending videos:

const tiktok = require('tiktok-app-api');

let tiktokApp;

(async () => {
  tiktokApp = await tiktok();

  const iterator = tiktokApp.getTrendingVideos();
  const videosResult = await iterator.next();
  const trendingVideos = videosResult.value;

  const tags = trendingVideos.map(v => v.tags);

  console.log(tags);
})();

Take a look at tiktok-web-api-example for an up-to-date web API using this module.

Installation

Install the API:

npm i tiktok-app-api

Import into your program.

const tiktok = require('tiktok-app-api');

// Or, if you are using TypeScript:
import tiktok = require('tiktok-app-api'):

Usage

At the moment, the majority of the API returns promises, and may throw errors in certain situations. When a promise is not returned, or if a function may throw an error, it will be mentioned.

Application Instance

To start using the API, you must first instantiate an instance of the application.

const tiktok = require('tiktok-app-api');

let tiktokApp;

(async () => {
  tiktokApp = await tiktok();
})();

While instantiating a new instance of the application, the application's settings will be set up.

Options

If you would like to use your own signature service instead of the default option, you can specify this in a TikTokOptions object. See TikTokOptions for a definition of the TikTokOptions object.

const tiktokApp = await tiktok({
  signatureService: 'http://localhost:8000/api/sign',
});

Search Options

Throughout the API, you may want to modify the starting point or count of a request. This is possible by specifying a SearchOptions object in a request. See SeachOptions for a definition of the SearchOptions object.

const options = {
  cursor: '0',
  count: 30,
};
// usage examples:
const trendingIterator = tiktokApp.getTrendingVideos(options);
const uploadedIterator = tiktokApp.getUploadedVideos(user, options);
const likedIterator = tiktokApp.getLikedVideos(user, options);
// etc.

Any request which takes a SearchOptions object will return an async iterator, which will lazily load the next batch of videos when requested.

Trending

To get the top trending videos using the API is as simple as:

const iterator = tiktokApp.getTrendingVideos();
const videosResult = await iterator.next();
const trendingVideos = videosResult.value;

console.log(trendingVideos);

Users

To retrieve User information within the API, you will first need to get a User object. See User for a definition of the User object.

Get a User object from a TikTok user's username:

Will fetch ID of user from TikTok API. May throw an error in certain situations, see here.

const user = await tiktokApp.getUserByName('example');

Get a User object from a TikTok user's id:

Will not fetch username of user from TikTok API.

const user = tiktokApp.getUserByID('6828402025898902533');

Take note that getUserByID(id) does not return a promise, as it does not fetch any information from the TikTok API.

Now that we have a User object, we can retrieve some information from the TikTok user:

See UserInfo for a defintion of the UserInfo object. May throw an error in certain situations, see here.

const userInfo = await tiktokApp.getUserInfo(user);

console.log(userInfo.followingCount, userInfo.followerCount, userInfo.likeCount);

Now, let's get the user's uploaded videos:

See VideoInfo for a definition of the VideoInfo object. May throw an error in certain situations, see here.

const iterator = tiktokApp.getUploadedVideos(user);
const videosResult = await iterator.next();
const uploadedVideos = videosResult.value;

console.log(uploadedVideos);

Same idea, we can get the user's liked videos:

May throw an error in certain situations, see here.

const iterator = tiktokApp.getLikedVideos(user);
const videosResult = await iterator.next();
const likedVideos = videosResult.value;

console.log(likedVideos);

That covers users. Let's move on to TikTok videos.

Videos

Just like how previously we needed our User object, we now need our Video object. See Video for a definition of the Video object.

const video = tiktokApp.getVideo('6829280471411674374');

Take note that getVideo(id) does not return a promise, as it does not fetch any information from the TikTok API.

Now to get the information of this video:

May throw an error in certain situations, see here.

const videoInfo = await tiktokApp.getVideoInfo(video);

console.log(videoInfo.commentCount, videoInfo.author, videoInfo.video.id);

That's all there is for videos, for now. Now on to Tiktok audios.

Audios

Just like Users and Videos, we first need an Audio object.

const audio = tiktokApp.getAudio('6829280451471969029');

Take note that getAudio(id) does not return a promise, as it does not fetch any information from the TikTok API.

To get the information related to the audio:

See AudioInfo for a definition of the AudioInfo object. May throw an error in certain situations, see here.

const audioInfo = await tiktokApp.getAudioInfo(audio);

console.log(audioInfo.title, audioInfo.audio.title);

To get the top videos related to an audio:

The first object of this VideoInfo array will be the original video with the audio. May throw an error in certain situations, see here.

const iterator = tiktokApp.getAudioTopVideos(audio);
const videosResult = await iterator.next();
const topVideos = videosResult.value;

console.log(topVideos[0]);

Finally we have TikTok tags.

Tags

Just like Users, Videos, and Audios, we need a Tag object.

Will fetch the title from the TikTok API, therefore this function returns a promise. May throw an error in certain situations, see here.

const tag = await tiktokApp.getTag('fyp');

To retrieve the information associated with the tag:

See TagInfo for a definition of the TagInfo object. May throw an error in certain situations, see here.

const tagInfo = await tiktokApp.getTagInfo(tag);

console.log(tagInfo.description, tagInfo.videoCount, tagInfo.viewCount);

To get the top videos of a tag:

May throw an error in certain situations, see here.

const iterator = tiktokApp.getTagTopVideos(tag);
const videosResult = await iterator.next();
const topVideos = videosResult.value;

console.log(topVideos);

Object Reference

Below you will find the data that each object contains.

TikTokOptions

TikTokOptions {
  signatureService?: string, // Not required.
}

SearchOptions

SearchOptions {
  count?: number, // Not required.
  cusrsor?: string, // Not required.
}

User

User {
  id: string,
  username?: string, // Not required initially.
}

UserInfo

UserInfo {
  user: User,
  avatar: string,
  nickname: string,
  signature: string,
  followingCount: number,
  followerCount: number,
  likeCount: number,
  videoCount: number,
}

Video

Video {
  id: string,
}

VideoInfo

VideoInfo {
  video: Video,
  author: User,
  playCount: number,
  likeCount: number,
  commentCount: number,
  shareCount: number,
  description: string,
  tags: Tag[],
  audio: AudioInfo,
}

Audio

Audio {
  id: string,
}

AudioInfo

AudioInfo {
  id: string,
  title: string,
}

Tag

Tag {
  id: string,
  title: string,
}

TagInfo

TagInfo {
  tag: Tag,
  description: string,
  videoCount: number,
  viewCount: number,
}