ResearchTikPy 0.2.2

Python API wrapper for the TikTok Research API

ResearchTikPy is a Python library designed to facilitate access to TikTok's Research API, providing a simple and intuitive interface for collecting data on videos, users, comments, and more. This library is intended for academic and research purposes, aiming to streamline the data collection process from TikTok without directly interfering with the API.

You need to have access to the Research API to use this library

Features of ResearchTikPy:

Available Functions
Query videos using custom conditions
Fetch video infos by key term(s)
Fetch user infos
Search for videos by user(s)
Collect comments from video(s)
Fetch the followers of account(s)
Fetch account(s) followed by a user
Fetch videos liked by a user
Fetch videos pinned by a user

What you need to consider before getting started:

1. This package is in active development! Please report bugs & errors, and feel free to suggest additional functions!
2. Read TikTok's guide about the research API to inform you about restrictions, daily quotas, and FAQs.
3. Currently, The Research API does not allow the download of videos. You need to use other sources for this outside the spectrum of the official API.
4. Splitting your requests into smaller chunks is generally advised to avoid longer fetching times and data loss.
5. The library uses automatic rate-limiting (pausing when TikTok returns HTTP 429 errors), but manual adjustments to wait times may improve performance.

Installation

Generating access token

Before using ResearchTikPy, you must obtain access credentials (client key and secret) from TikTok's developer platform. Navigate to manage apps on TikToks developer webpage to find your client_key and client_secret

Currently, the most efficient method is to install the package via pip.

# Install
pip install researchtikpy

# Import
import researchtikpy as rtk


# Or import individual modules: F.e.

from researchtikpy import get_access_token  # This way you could leave out the `rtk.` at the beginning of every researchtikpy function.

Once you have your credentials, you can use the library to generate an access token that you need to reference every time you run a command in this library:

# It is advised to store your tokens in separate objects or save them in your system's environment to avoid accidental publication of the credentials.

client_key = 'your_client_key'
client_secret = 'your_client_secret'

access_token = rtk.get_access_token(client_key, client_secret)

# OR paste the credentials within the command

access_token_dict = rtk.get_access_token(client_key, client_secret)  # Get the full dictionary
access_token = access_token_dict["access_token"] # stores the access token string as a separate object that you can reference in every command.

# print(access_token_dict) # Testing, if necessary. It should look something like this:


#Access Token: clt.Vl7HEasdfdeX28Z0G4wervRoPpY5f3zAGgYmGAAyGkowkYCusgbwqmb4NtNzn2QstXh
#Expires In: 7200
#Token Type: Bearer

Features

This package features every possible query currently provided by the Researcher API of TikTok. For the full documentation, including a list of variables, see the official Codebook.

Field Paramaters

• query/hashtag(s)/username(s)/video_id(s)/shop_id(s)/product_id(s): A list of strings to search for, e.g., "FYP" or ["FYP", "FORYOURPAGE"].
• access_token: Your valid access token for the TikTok Research API. Stored as a string.
• start_date: The start date for the search. The format should be 'YYYYMMDD'.
• end_date: The end date for the search. The format should be 'YYYYMMDD'.
• max_count (Optional): Maximum units per request is 100 (the default). It is advised to keep it like this or specify a smaller value.
• total_max_count (Optional): The total maximum number of videos to collect. Keeping this within a manageable range is advised because of the fetching duration and daily quota limit! The default is infinite. Stored as an integer, e.g., 500.
• region_code (Optional): The region code to filter videos by. See list of region_codes.
• music_id (Optional): The music ID to filter videos by. Stored as a string.
• effect_id (Optional): The effect ID to filter videos by. Stored as a string.
• max_count (Optional): The maximum number of videos to return per individual get request (default & max is 100).
• rate_limit_pause (Optional): Time in seconds to wait when a rate limit error is encountered. The default is 60 seconds. It can be adjusted as you like, e.g., 30.
• verbose (Optional): If True (default), prints detailed logs; if False, suppresses most print statements.

Function: get_videos_query

Fetches video information using a custom query in a more flexible way (e.g. combining usernames, hashtags and other conditions) than the specialized features that follow beneath. See TikTok's guide for possible parameters. If you only want to collect data on users use Fetch user infos instead.

videos_df = rtk.get_videos_query(query, access_token, start_date, end_date, total_max_count, max_count=100)

Example call

from researchtikpy.query_lang import Query, Condition, Operators, Fields

query = Query(
    and_=[
        Condition(Fields.username, Operators.equals, ["username1"]),
        Condition(Fields.hashtag_name, Operators.equals, ["hashtag"]) 
    ]
)
start_date = "20250101"
end_date = "20250131"
total_max_count = 100

data = rtk.get_videos_query(query, access_token, start_date, end_date, total_max_count)

Function: Keyterm search

Fetches video information by hashtag.

videos_df = rtk.get_videos_hashtag(hashtags, access_token, start_date, end_date, total_max_count (optional),
     region_code (optional), music_id (optional), effect_id (optional), max_count (optional),  rate_limit_pause (optional))

Example Call

access_token = "clt.rasddUatUsHasdnHYV2zGw7aQasdxpYpxNz3zjaMfBksdfxXA7" # Randomized token. Don't share your access token! 
hashtags = ["fyp", "FYP"]
start_date = "20230101"
end_date = "20240131"

videos_df = rtk.get_videos_hashtag(hashtags, access_token, start_date, end_date, total_max_count = 500)

Function: get_users_info

Fetches account information for given usernames within the specified date range and compiles them into a single data frame.

user_df = rtk.get_users_info(usernames, access_token, start_date, end_date)

Function: get_videos_info

Fetches all videos & video metadata of an account or accounts and compiles them into a single data frame (with account IDs).

videos_df = rtk.get_videos_info(usernames, access_token, start_date, end_date, total_max_count (optional), fields (optional), max_count(optional))

Function: get_video_comments

Fetches comments on video(s) and compiles them into a single data frame (with video IDs).

comments_df = rtk.get_video_comments(videos_df, access_token, fields (optional), max_count (optional), verbose (optional))

Function: get_pinned_videos

Fetches pinned videos of accounts and compiles them into a single DataFrame.

pinned_df = rtk.get_pinned_videos(usernames, access_token, fields (optional), max_count (optional), verbose (optional))

• usernames: List of usernames to fetch videos for. Reports no pinned videos if the account has none.
• access_token: Authorization token for TikTok Research API.
• fields (optional)
• verbose (optional)

Function: get_liked_videos

Fetches metadata of videos accounts have like. Only works if the user has enabled public access to liked videos. This is disabled by default on most accounts.

liked_df = rtk.get_liked_videos(usernames, access_token, fields (optional), max_count (optional), verbose (optional))

Function: get_following_users

Fetches followers of accounts and compiles them into a single data frame. It is advised to keep the list of usernames short to avoid longer runtimes and account for a large number of possible followers! Compiles them into a single data frame with the variable target_account indicating the seed account.

following = rtk.get_following (usernames, access_token, fields (optional), max_count (optional), verbose (optional))

Function: get_followers

Fetches followers for multiple users and compiles them into a single data frame. It is advised to keep the list of usernames short to avoid longer runtimes OR to use the total_count parameter to avoid reaching daily quotas rather quickly.

followers = rtk.get_followers (usernames, access_token, total_count (optional) fields (optional), max_count (optional), verbose (optional))

TikTok Shops API

Function: get_shop_info

Fetches shop-level metadata.

shop_info = rtk.get_shop_info(shop_name, access_token)

Function: get_product_info

Fetches product details from a given shop.

product_info = rtk.get_product_info(shop_id, access_token)

Function: get_product_reviews

Fetches reviews for a given product.

product_reviews = rtk.get_product_reviews(product_id, access_token)

Cite

Please feel free to cite me when using the package:

Hohner, J., Ruiz, Tomas & Kessling, Philipp (2024). ResearchPikTy (Python Library). GitHub Repository: https://github.com/HohnerJulian/ResearchTikPy doi:10.13140/RG.2.2.24209.03682

or Bibtex:
@misc{Hohner2024ResearchTikPy, author = {Hohner, Julian; Ruiz, Tomas; Kessling, Philipp}, title = {{ResearchTikPy: Python Library for TikTok's Research API}}, year = {2024}, howpublished = {\url{https://github.com/HohnerJulian/ResearchTikPy}}, note = {Accessed: yyyy-mm-dd}, doi = {10.13140/RG.2.2.24209.03682} }