Query TikTok videos using the research API

This is the version of tt_search that explicitly uses Research API. Use tt_search_hidden for the unofficial API version.

Usage

tt_search_api(
  query,
  start_date = Sys.Date() - 1,
  end_date = Sys.Date(),
  fields = "all",
  start_cursor = 0L,
  search_id = NULL,
  is_random = FALSE,
  max_pages = 1,
  parse = TRUE,
  cache = TRUE,
  verbose = interactive(),
  token = NULL
)

tt_query_videos(
  query,
  start_date = Sys.Date() - 1,
  end_date = Sys.Date(),
  fields = "all",
  start_cursor = 0L,
  search_id = NULL,
  is_random = FALSE,
  max_pages = 1,
  parse = TRUE,
  cache = TRUE,
  verbose = interactive(),
  token = NULL
)

Arguments

query

A query string or object (see query).

start_date, end_date

A start and end date to narrow the search (required). Can be Date objects or strings like "20210102". If they are more than 30 days apart, the search is split into 30 day windows (see Details).

fields

The fields to be returned (defaults to all)

start_cursor

The starting cursor, i.e., how many results to skip (for picking up an old search).

search_id

The search id (for picking up an old search).

is_random

Whether the query is random (defaults to FALSE).

max_pages

results are returned in batches/pages with 100 videos. How many should be requested before the function stops?

parse

Should the results be parsed? Otherwise, the original JSON object is returned as a nested list.

cache

should progress be saved in the current session? It can then be retrieved with last_query() if an error occurs. But the function will use extra memory.

verbose

should the function print status updates to the screen?

token

The authentication token (usually supplied automatically after running auth_research once).

Value

A data.frame of parsed TikTok videos (or a nested list).

Details

The Research API only accepts a start_date and end_date that are at most 30 days apart. If you request a longer time span, the function splits it into consecutive windows of at most 30 days, queries them one after the other and combines the results. Note that max_pages then applies to each window separately (i.e., you get up to max_pages pages per window) and that start_cursor and search_id are only used for the first window.

To pick a search back up, use the search_id, cursor, start_date and end_date attributes of the returned object (or of last_query if the search failed). They always refer to the last window that was queried, so that you can resume with start_date = attr(x, "start_date") and the original end_date.

Examples

if (FALSE) { # \dontrun{
# look for a keyword or hashtag by default
tt_search_api("rstats")

# longer time spans are automatically split into 30 day windows
rstats <- tt_search_api("rstats",
                        start_date = "20240101",
                        end_date = "20240630",
                        max_pages = 10)

# when a search fails after a while, get the results and pick it back up
# (only works with the same parameters). The attributes tell you where the
# search stopped
last_pull <- last_query()
rstats2 <- tt_search_api("rstats",
                         start_date = attr(last_pull, "start_date"),
                         end_date = "20240630", # the original end date
                         start_cursor = attr(last_pull, "cursor"),
                         search_id = attr(last_pull, "search_id"),
                         max_pages = 10)

# or build a more elaborate query
query() |>
  query_and(field_name = "region_code",
            operation = "IN",
            field_values = c("JP", "US")) |>
  query_or(field_name = "hashtag_name",
            operation = "EQ", # rstats is the only hashtag
            field_values = "rstats") |>
  query_or(field_name = "keyword",
           operation = "IN", # rstats is one of the keywords
           field_values = "rstats") |>
  query_not(operation = "EQ",
            field_name = "video_length",
            field_values = "SHORT") |>
  tt_search_api()
} # }