Title: Load Data from 'tiktok Marketing API'
Version: 0.3.2
Description: Loading data from 'tiktok Marketing API' https://business-api.tiktok.com/portal by business centers, advertisers, budgets and reports.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2
Imports: cli, dplyr, httr2, jsonlite, purrr, rappdirs, stringr, tidyr, utils
Depends: R (≥ 4.1.0)
URL: https://github.com/selesnow/rtiktokads
BugReports: https://github.com/selesnow/rtiktokads/issues
NeedsCompilation: no
Packaged: 2025-08-29 14:11:37 UTC; User
Author: Alexey Seleznev ORCID iD [aut, cre], Netpeak [cph]
Maintainer: Alexey Seleznev <selesnow@gmail.com>
Repository: CRAN
Date/Publication: 2025-09-03 21:00:09 UTC

rtiktokads: Load Data from 'tiktok Marketing API'

Description

Loading data from 'tiktok Marketing API' https://business-api.tiktok.com/portal by business centers, advertisers, budgets and reports.

Loading data from 'tiktok Marketing API' https://business-api.tiktok.com/portal by business centers, advertisers, budgets and reports.

Author(s)

Maintainer: Alexey Seleznev selesnow@gmail.com (ORCID)

Other contributors:

See Also

Useful links:

Useful links:

Authorization in 'TikTok Marketing API'

Description

Authorization in 'TikTok Marketing API'

Usage

tik_auth(username = tik_get_username(), token_path = tik_get_token_path())

Arguments

username

TikTok login

token_path

auth cache folder

Value

tik_access_token object

Get Ad Groups

Description

Get Ad Groups

Usage

tik_get_ad_groups(advertiser_id, fields = NULL)

Arguments

advertiser_id

Advertiser ID.

fields

Fields that you want to get.

Value

tibble with AdGroup meta data

Get Ads

Description

Get Ads

Usage

tik_get_ads(advertiser_id, fields = NULL)

Arguments

advertiser_id

Advertiser ID.

fields

Fields that you want to get.

Value

tibble with Ads metadata

Get Authorized Ad Accounts

Description

Get Authorized Ad Accounts

Usage

tik_get_advertiser_accounts()

Value

tibble with advertisers name and id

Examples

## Not run: 
advertisers <- tik_get_advertiser_accounts()

## End(Not run)

Get the Balance and Budget of Ad Accounts

Description

Use this endpoint to obtain the balance of ad accounts in the Business Center. You can also use this endpoint to obtain the budget of the ad accounts owned by the Business Center in auto-allocation mode.

Usage

tik_get_advertiser_balance(bc_id, fields = NULL)

Arguments

bc_id

Business Center ID.

fields

A list of additional fields to return in the response. Supported values:

  • budget_remaining: The remaining budget.

  • budget_frequency_restriction: Restrictions on the number of budget changes allowed for the current day.

  • budget_amount_restriction: Restrictions on the minimum amount that can be changed for the budget.

  • min_transferable_amount: Details of the minimal amount that you can transfer to the ad account.

Value

tibble with balance and budget info

Examples

## Not run: 
bc <- tik_get_business_centers()
acs_balance <- tik_get_advertiser_balance(bc$bc_id)

## End(Not run)

Get Ad Account Details

Description

Get Ad Account Details

Usage

tik_get_advertiser_info(advertiser_ids, fields = NULL)

Arguments

advertiser_ids

List of advertiser IDs to query. You can obtain Advertiser IDs through the tik_get_advertiser_accounts() function

fields

A list of information to be returned. Supported values:

  • telephone_number

  • contacter

  • currency

  • cellphone_number

  • timezone

  • advertiser_id

  • role

  • company

  • status

  • description

  • rejection_reason

  • address

  • name

  • language

  • industry

  • license_no

  • email

  • license_url

  • country

  • balance

  • create_time

  • display_timezone

  • owner_bc_id

  • company_name_editable.

Value

tibble with advertisers onfo

Examples

## Not run: 
advertisers <- tik_get_advertiser_accounts()
advertisers_info <- tik_get_advertiser_info(advertisers$advertiser_id)

## End(Not run)

Get the Partners of a BC

Description

Get the Partners of a BC

Usage

tik_get_bc_partners(bc_id)

Arguments

bc_id

Business Center ID.

Value

tibble with list of partners

Get Business Centers

Description

Get Business Centers

Usage

tik_get_business_centers()

Value

tibble with business centers info

Examples

## Not run: 
bc <- tik_get_business_centers()

## End(Not run)

Get Campaigns

Description

Get Campaigns

Usage

tik_get_campaigns(advertiser_id, fields = NULL)

Arguments

advertiser_id

Advertiser ID.

fields

Fields that you want to get.

Value

tibble with campaigns metadata

Get Marketing Report

Description

Use this function to create a synchronous report task. This function can currently return the reporting data of up to 20,000 advertisements. If your number of advertisements exceeds 20,000, please use campaign_ids / adgroup_ids / ad_ids as a filter to obtain the reporting data of all advertisements in batches. If you use campaign_ids / adgroup_ids / ad_ids as a filter, you can pass in up to 100 IDs at a time.

Usage

tik_get_report(
  advertiser_id = NULL,
  advertiser_ids = NULL,
  bc_id = NULL,
  service_type = NULL,
  report_type = "BASIC",
  data_level = "AUCTION_ADVERTISER",
  dimensions = c("advertiser_id", "stat_time_day"),
  metrics = "spend",
  enable_total_metrics = FALSE,
  start_date = Sys.Date() - 7,
  end_date = Sys.Date() - 1,
  query_lifetime = FALSE,
  multi_adv_report_in_utc_time = FALSE,
  order_field = NULL,
  order_type = NULL
)

Arguments

advertiser_id

Advertiser ID. You need to pass in either advertiser_id/advertiser_ids or bc_id.

  • When report_type is set to BASIC or AUDIENCE, pass in advertiser_id or advertiser_ids. If you pass in both advertiser_id and advertiser_ids, advertiser_id will be ignored.

  • When report_type is set to PLAYABLE_MATERIAL, CATALOG, or TT_SHOP, pass in advertiser_id.

  • When report_type is set to BC, pass in bc_id.

advertiser_ids

A list of advertiser IDs.

bc_id

ID of a Business Center that you have access to.

service_type

Ad service type. Not supported when report_type is BC.

  • AUCTION: auction ads, or both auction ads and reservation ads.

  • RESERVATION (deprecated) : reservation ads.

report_type

Report type:

  • BASIC: basic report.

  • AUDIENCE: audience report.

  • PLAYABLE_MATERIAL: playable ads report.

  • CATALOG: DSA report.

  • BC: Business Center report.

  • TT_SHOP: GMV max ads report.

data_level

The data level that you'd like to query in reports.

  • AUCTION_AD: auction ads or both auction ads and reservation ads, ad level.

  • AUCTION_ADGROUP: auction ads or both auction ads and reservation ads, ad group level.

  • AUCTION_CAMPAIGN: auction ads or both auction ads and reservation ads, campaign level.

  • AUCTION_ADVERTISER: auction ads or both auction ads and reservation ads, advertiser level.

dimensions

Grouping conditions. For example: ("campaign_id", "stat_time_day") indicates that both campaign_id and stat_time_day (days) are grouped. Different report types support different dimensions.

metrics

Metrics to query. Different report types support different metrics. For supported metrics for each report type, see the corresponding articles under Report types.

enable_total_metrics

Whether to enable the total added-up data for your requested metrics. When enable_total_metrics is enabled, we will provide the aggregate data for all pages as you query different pages. Under this condition, you only need to specify this field when requesting data for the first page.

start_date

Query start date (closed interval) in the format of YYYY-MM-DD. The date is based on the ad account time zone.

end_date

Query end date (closed interval) in the format of YYYY-MM-DD. The date is based on the ad account time zone.

query_lifetime

Whether to request the lifetime metrics. Default value: False. If query_lifetime = True, the start_date and end_date parameters will be ignored. The lifetime metric name is the same as the normal one.

multi_adv_report_in_utc_time

Whether to set the returned metrics in the local timezone of each respective advertiser.

order_field

Sorting field.

order_type

Sorting order. ASC or DESC.

Details

To take more details see API documentation

Value

tibble with report data

Examples

## Not run: 
report <- tik_get_report(advertiser_id = '7499750467069771792')

## End(Not run)

Get Auth Cache Folder

Description

Get Auth Cache Folder

Usage

tik_get_token_path()

Value

character, cache folder path

Get Auth Username

Description

Get Auth Username

Usage

tik_get_username()

Value

character, current auth username

Change Session Token Path

Description

Change Session Token Path

Usage

tik_set_token_path(
  token_path = ifelse(getOption("tiktok.auth_cache_mode") == "global",
    rappdirs::site_data_dir("rtiktokads"), rappdirs::user_cache_dir("rtiktokads"))
)

Arguments

token_path

auth cache folder

Value

using for side effect, no return value

Set Session Auth Username

Description

Set Session Auth Username

Usage

tik_set_username(username)

Arguments

username

TikTok login

Value

using for side effect, no return value