TikTok Research Client

TikTok Research Client

TikTok Research Client is a command-line tool for collecting data from TikTok using the TikTok Research API. This tool provides a streamlined way to fetch information about users, search for videos by, and collect comments on specific videos.

YOU NEED TO HAVE ACCESS TO THE TIKTOK RESEARCH API TO USE THIS TOOL.

Requirements

• Requires granted access to the TikTok Research API. Once permisison has been granted, fill out the .env file.

Installation

You can install TikTok Research Client via pip from PyPI:

$ pip install tiktok-research-client

Usage

Please see the Command-line Reference for details.

To run the script, navigate to the folder containing main.py and execute the following command:

tiktok-research-client [OPTIONS]

or

python -m tiktok-research-client [OPTIONS]

Options

• -q, --query_option: What do you want to query? Choose from user, search, or comments.
• -i, --query_input: What is the input? For user, enter the username. For search, enter the keywords separated by commas. For comments, enter the video ID.
• -m, --collect_max: Maximum number of videos to collect (default is 100).
• -d, --start_date: The start date for data collection, formatted as YYYY-MM-DD (default is 2023-01-01).

Examples

1. To get user information for the username john_doe:

tiktok-research-client -q user -i john_doe

2. To search for videos related to coding:

tiktok-research-client -q search -i "climate,global warming" -m 50

3. To get comments for a video with ID 123456789:

tiktok-research-client -q comments -i 123456789

Use custom query

Check out the documentation on how to construct you own custom query.

from tiktok_research_client.data_collection.collect import TiktokClient

client = TiktokClient()

query = {
    "query": {
        "and": [
            {
                "operation": "IN",
                "field_name": "region_code",
                "field_values": ["US"],
            },
            {
                "operation": "EQ",
                "field_name": "hashtag_name",
                "field_values": ["climate"],
            },
        ],
        "not": [
            {"operation": "EQ", "field_name": "video_length", "field_values": ["SHORT"]}
        ],
    },
    "max_count": 100,
    "start_date": "20230101",
    "end_date": "20230115",
}

url = "https://open.tiktokapis.com/v2/research/video/query/?fields=id,region_code,like_count,username,video_description,music_id,comment_count,share_count,view_count"

data = client.query(query=query, url=url)

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, TikTok Research Client is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Known Issues

Many. This is a super lightweight and simple client, and has not been tested extensively - actually not at all. Will do at some point. If the pre-defined CLI commands are insufficient, then just make your own query and use query function.

Credits

This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.