Michael JohnsonIf a team needs to check how creators disclose brand relationships in public TikTok videos, a useful first result is not an automated verdict, but a compact queue of videos with captions, links, and detected keywords. Below is a practical workflow: send a search query through the TikTok Scraper API from jsonscraper, normalize the two response structures into a single format, and save a CSV for specialist review.
The task: find videos worth reviewing
Manually searching for a company name is difficult to repeat consistently: results have to be collected one at a time, and the reasons for selecting them remain in the browser. Automating the collection makes it possible to save the query, run date, and found items in a spreadsheet so the team can review videos from a consistent list.
In this scenario, “candidate for review” means only a video returned by search results whose description contains a predefined word or phrase. For example, this might be “advertisement,” “partnership,” or “sponsored.” This text filter helps direct a person’s attention, but it does not evaluate the video itself or determine whether applicable requirements have been met.
This distinction matters for a marketing team. The U.S. Federal Trade Commission’s guidance describes disclosure of a material connection to a brand as an obligation that depends on the context of the message; for video, the FTC recommends considering both visible and audible disclosure. Searching captions can identify some textual signals, but reaching a decision requires viewing the post and assessing its context. The FTC’s guidance for creators explains these conditions with examples.
The output: a CSV with the reason for selection
The pipeline will write one row per unique video ID and include the description text, link, creator name, available public counters, and matched markers. It will also record the original search query and collection time. This makes the spreadsheet suitable for a review queue and helps explain later why a particular video was included.
The marker vocabulary should be defined by an editor or compliance specialist. Start with the language and terms actually used in your campaign, then review the results and expand the list if needed. The values below are intentionally simple; replace them to suit the brand, market, and content language.
Connecting to the TikTok Scraper API
jsonscraper’s documentation specifies the GET /searchVideo route at the base address https://tiktok.evelode.com for video search. The required parameter is keyword; optional parameters include count, date_posted, sort_by, and region. The key is passed as license_key, so store it in an environment variable, not in code or the CSV. The exact parameter names and route appear in the TikTok endpoint reference; product and access information is available on the TikTok Scraper API page.
One response detail affects the completeness of a local parser: data may be located in tiktok.aweme_list or in tiktok.search_item_list[].aweme_info. The script therefore checks both arrays. If the search returns an empty list, it creates an empty CSV rather than filling it with fabricated rows.
Python example: search, filter, and CSV
The example uses only the Python 3.8+ standard library. Before running it, set JSONSCRAPER_TIKTOK_LICENSE_KEY in the environment. The request uses keyword, and the key is passed in the license_key query parameter, as specified.
import csv
import json
import os
import sys
from datetime import datetime, timezone
from urllib.parse import urlencode
from urllib.request import Request, urlopen
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORD = "Acme"
MARKERS = ["advertisement", "partnership", "partnership", "sponsor", "ad", "sponsored"]
params = {
"license_key": API_KEY,
"keyword": KEYWORD,
"count": 30,
"sort_by": "date-posted",
"date_posted": "this-month",
"region": "US",
}
url = "https://tiktok.evelode.com/searchVideo?" + urlencode(params)
request = Request(url, headers={"Accept": "application/json"})
with urlopen(request, timeout=30) as response:
payload = json.load(response)
if payload.get("status") != "ok":
raise RuntimeError("API returned a non-ok outer status")
tiktok = payload.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info") or {}
if info:
items.append(info)
seen = set()
rows = []
collected_at = datetime.now(timezone.utc).isoformat()
for item in items:
video_id = item.get("aweme_id")
if not video_id or video_id in seen:
continue
seen.add(video_id)
description = item.get("desc") or ""
lowered = description.casefold()
matched = [word for word in MARKERS if word.casefold() in lowered]
if not matched:
continue
author = item.get("author") or {}
stats = item.get("statistics") or {}
rows.append({
"collected_at_utc": collected_at,
"search_keyword": KEYWORD,
"video_id": video_id,
"share_url": item.get("share_url") or "",
"description": description,
"matched_markers": "; ".join(matched),
"author_name": author.get("nickname") or "",
"author_id": author.get("unique_id") or "",
"play_count": stats.get("play_count", ""),
"digg_count": stats.get("digg_count", ""),
"comment_count": stats.get("comment_count", ""),
"share_count": stats.get("share_count", ""),
})
fields = [
"collected_at_utc", "search_keyword", "video_id", "share_url",
"description", "matched_markers", "author_name", "author_id",
"play_count", "digg_count", "comment_count", "share_count",
]
with open("tiktok_review_queue.csv", "w", newline="", encoding="utf-8-sig") as output:
writer = csv.DictWriter(output, fieldnames=fields)
writer.writeheader()
writer.writerows(rows)
print(f"Saved {len(rows)} review candidates to tiktok_review_queue.csv")The script first checks the outer status, then reads the tiktok object and combines the available array formats. Deduplication by aweme_id prevents duplicate rows if a video appears in both response paths. Metrics are recorded as returned; missing values remain blank rather than being converted to zero.
The example uses parameters documented for /searchVideo: date_posted accepts this-month, sort_by accepts date-posted, and region accepts a country code. The count value sets the requested result size; it does not guarantee a complete list of posts. For pagination, preserve the returned cursor as an opaque value and pass it in the cursor parameter.
Human review and scheduled automation
Send the CSV to the responsible reviewer with brief instructions: open the link, watch the video and consider the caption’s context, record a conclusion, and add a comment if the marker is being used in a different sense. For example, automated filtering cannot distinguish an advertising disclosure from a discussion about how advertising works. Human review bridges this gap in meaning.
For repeatable collection, run the script on a schedule using cron, a CI scheduler, or a task orchestrator. Save the CSV with the run date, or load the rows into a table with a unique key made from the video ID and observation date. If you need an audit log, retain the original JSON response with access controls: it makes it possible to recheck the transformation and explain where each row came from.
For production use, add handling for network and HTTP errors, retry limits, and failure notifications. Do not print the full request URL: it contains the access key. For a team with multiple users, store the secret in the runtime environment’s secrets manager and restrict access to the output files in line with internal policies.
What this list can provide
After running the script, the team will have a reproducible selection of videos found by keyword, with a clear reason each candidate entered the queue. Reviewers can manually exclude irrelevant matches, assign a reviewer, and group results by marker or creator. Regular collection also builds a history of which videos appeared in the returned results on a specific date.
This approach is suitable for initial discovery and routing, not for automatically concluding whether rules have been followed. It is limited by the search results, selected keyword, request settings, and text markers. To review a specific collaboration, compare the video with the brief and information available to your team, then assess the message itself against applicable rules.
To get started, check current access and parameters on the TikTok Scraper API product page, and consult the official API documentation for the response format and integration options.
