TikTokMarketing 0.1.5

A package designed to connect to the TikTok Marketing API and return data to report on.

TikTokMarketing

This package enables efficient querying and retrieval of performance metrics from the TikTok Marketing API on different levels of granularity.

Build status

Requirements

• Python 3.8+

Installation

pip install TikTokMarketing

Features

• Distributed via PyPI.
• Wrapper around the TikTok Marketing API to assist marketers on a budget with their reporting.
• Under the hood TikTokMarketing makes use of the requests and json modules.
• It has no additional dependencies.
• TikTokMarketing supports the latest version of the API v1.3
• Supports both basic and audience reporting
• Includes human-readable interest category mapping

Data Levels

The API returns data on 4 distinct levels:

1. AUCTION_ADVERTISER
2. AUCTION_CAMPAIGN
3. AUCTION_ADGROUP
4. AUCTION_AD

For available dimensions and metrics, refer to the official documentation:

• Dimensions
• Metrics

Example Usage

Basic Setup

from TikTokMarketing import TikTokAPI, InterestCategories
from datetime import datetime, timedelta

# Initialize the API
api = TikTokAPI('YOUR_ACCESS_TOKEN')

# Set up date range
end_date = datetime.now().strftime('%Y-%m-%d')
start_date = (datetime.now() - timedelta(days=7)).strftime('%Y-%m-%d')

Basic Reporting

# Basic reporting at advertiser level
basic_result = api.get_data(
    start_date=start_date,
    end_date=end_date,
    dimensions=['advertiser_id', 'stat_time_day'],
    metrics=['spend', 'impressions', 'clicks'],
    advertiser_id='YOUR_ADVERTISER_ID',
    data_level='AUCTION_ADVERTISER'
)

Audience Reporting

Age Distribution

age_result = api.get_data(
    start_date=start_date,
    end_date=end_date,
    dimensions=['age'],
    metrics=['spend', 'impressions', 'clicks'],
    advertiser_id='YOUR_ADVERTISER_ID',
    data_level='AUCTION_ADVERTISER',
    report_type='AUDIENCE',
    audience_dimensions=['age'],
    order_field='spend',
    order_type='ASC'
)

Gender and Age Combined

gender_age_result = api.get_data(
    start_date=start_date,
    end_date=end_date,
    dimensions=['gender', 'age', 'stat_time_day'],
    metrics=['spend', 'impressions', 'reach'],
    advertiser_id='YOUR_ADVERTISER_ID',
    data_level='AUCTION_ADVERTISER',
    report_type='AUDIENCE',
    audience_dimensions=['gender', 'age']
)

Geographic Distribution

country_result = api.get_data(
    start_date=start_date,
    end_date=end_date,
    dimensions=['country_code'],
    metrics=['impressions', 'reach', 'spend'],
    advertiser_id='YOUR_ADVERTISER_ID',
    data_level='AUCTION_ADVERTISER',
    report_type='AUDIENCE',
    audience_dimensions=['country_code'],
    order_field='impressions',
    order_type='DESC'
)

Audience Network Analysis

network_result = api.get_data(
    start_date=start_date,
    end_date=end_date,
    dimensions=['ac'],
    metrics=['impressions', 'reach', 'spend'],
    advertiser_id='YOUR_ADVERTISER_ID',
    data_level='AUCTION_ADVERTISER',
    report_type='AUDIENCE',
    audience_dimensions=['ac'],
    order_field='impressions',
    order_type='DESC'
)

Interest Categories

# Get and map interest categories
interest_result = InterestCategories.map_response(
    api.get_data(
        start_date=start_date,
        end_date=end_date,
        dimensions=['interest_category'],
        metrics=['impressions', 'reach', 'spend', 'clicks'],
        advertiser_id='YOUR_ADVERTISER_ID',
        data_level='AUCTION_ADVERTISER',
        report_type='AUDIENCE',
        audience_dimensions=['interest_category'],
        order_field='impressions',
        order_type='DESC'
    )
)

Converting Results to Pandas DataFrame

import pandas as pd

# Create empty dictionary with column names
dimensions = ['stat_time_day', 'advertiser_id']
metrics = ['spend', 'impressions', 'clicks']
all_fields = dimensions + metrics

TikTok_Data = TikTokAPI.create_dict(input_list=all_fields)

# Populate dictionary from API response
result_list = basic_result.get('data', {}).get('list', [])
for entry in result_list:
    for fieldname in TikTok_Data.keys():
        if fieldname in entry.get('dimensions', {}):
            TikTok_Data[fieldname].append(entry['dimensions'][fieldname])
        else:
            TikTok_Data[fieldname].append(entry['metrics'][fieldname])

# Convert to DataFrame
df = pd.DataFrame(TikTok_Data)

Note

When running TikTokMarketing in a docker container, the ip address might be blocked with the API response: Client IP address is in banned Country list

Available Parameters

Report Types

• BASIC
• AUDIENCE

Audience Dimensions

• gender
• age
• country_code
• ac (Audience network)
• platform
• interest_category
• language
• device_brand
• device_model
• device_price
• network

Order Types

• ASC
• DESC