search

HohnerJulian / ResearchTikPy

Python API wrapper for the TikTok Research API
MIT License
14 stars 1 forks source link
api apiwrapper researchtiktok researchtiktokapi tiktok tiktok-api tiktok-followers tiktok-views tiktokapi

readme

Python Version Build Status PyPI Version License LinkedIn X

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.

Features of ResearchTikPy:

| Includes | Does Not Yet Include (Working on it =) ) | |-------------------------------------------------|--------------------------------------------------------| | [Fetch video infos by key term(s)](#keyterm_search) | Downloading videos | | [Fetch user infos](#get_users_info) | Extracting text from videos (OCR) | | [Search for videos by user(s)](#get_videos_info) | Downloading sounds of videos | | [Collect comments from video(s)](#get_video_comments) | | | [Fetch the followers of account(s)](#get_followers) | | | [Fetch account(s) followed by a user](#get_following_users) | | | [Fetch videos liked by a user](#get_liked_videos) | | | [Fetch videos pinned by a user](#get_pinned_videos) | |



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. Splitting your requests into smaller chunks is generally advised to avoid longer fetching times and data loss.
  4. If you still have problems getting access to the Research TikTok API because TikTok is ghosting you or does not accept your application, raise your voice by reporting your case to this survey by the #DSA40 Data Access Collaboratory

Installation

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_acces_token()  # This way you could leave out the `rtk.` at the beginning of every researchtikpy function.

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

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 = rtk.get_access_token('your_client_key', 'your_client_secret')

# print(access_token) # 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.


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" # Dont share you 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)

Parameters:



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)

Parameters:



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(optional), end_date(optional), fields (optional), max_count(optional))

Parameters:



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))

Parameters:



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))



Function: get_liked_videos

Fetches metadata of videos accounts have like. Only works if accounts enable this feature. If an account has not enabled this, the section on his profil pages is keyed out and a lock symbol is placed there. 

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

Parameters:



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))

Parameters:



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))

Parameters:

Cite

Please feel free to cite me when using the package:

Hohner, J. & Ruiz, Thomas (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}, 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} }