Michael JohnsonL’équipe de support a besoin d’une liste de vidéos TikTok publiques dans lesquelles des personnes parlent d’une fonctionnalité difficile à comprendre ou posent des questions sur un produit. Les recherches manuelles sont difficiles à répéter de manière cohérente, et les réponses de l’API de recherche peuvent stocker les vidéos à différents endroits du JSON. Voici un script Python minimal qui recherche des vidéos par mots-clés, regroupe les deux structures, élimine les doublons par ID et enregistre les résultats dans un fichier CSV.
Résultat obtenu avec le script
Le tableau obtenu contient l’ID de la vidéo, son lien, sa description, sa date de publication, son auteur et les compteurs d’interactions disponibles. Les équipes de support ou de marketing peuvent indiquer manuellement quels sujets nécessitent une réponse, une mise à jour de la documentation ou une vérification dans leur CRM. Le tableau reflète uniquement les résultats renvoyés par l’API pour les requêtes indiquées ; considérez-le comme un échantillon de travail à examiner, et non comme un catalogue exhaustif de toutes les discussions.
Le script se charge de la collecte et du premier tri. Il ne détermine pas automatiquement si une description correspond à une question, une réclamation ou une plaisanterie : il vaut mieux ajouter cette étiquette après une vérification manuelle ou à l’aide d’un classificateur distinct, en conservant le texte d’origine et le motif de la décision.
Requête et structure de la réponse
Pour rechercher des vidéos, jsonscraper documente la route GET /searchVideo sur l’hôte https://tiktok.evelode.com. Le paramètre obligatoire est keyword ; il est possible de transmettre count, une région, un ordre de tri, une période de publication et le curseur de la page suivante. Par exemple, vous pouvez répéter la recherche pour plusieurs expressions définies à l’avance : le nom d’une fonctionnalité, une formulation courante d’un message d’erreur et une courte question sur un réglage. Les paramètres et leurs valeurs autorisées sont répertoriés dans le guide de l’API TikTok.
La recherche présente une particularité importante pour l’analyse : le tableau aweme_list peut être vide, tandis que les objets trouvés se trouvent dans search_item_list, avec aweme_info à l’intérieur de chaque élément. Le gestionnaire ci-dessous vérifie donc les deux formats. Un exemple de réponse et les champs observés lors d’une vérification le 25 octobre 2026 sont présentés dans la spécification primaire de jsonscraper ; les champs de statistiques peuvent être absents, le code ne leur attribue donc aucune valeur inventée.
Préparez la clé et la liste de requêtes
Enregistrez la clé dans la variable d’environnement JSONSCRAPER_TIKTOK_LICENSE_KEY, plutôt que dans le fichier source. Dans un terminal Linux ou macOS, vous pouvez procéder ainsi :
export JSONSCRAPER_TIKTOK_LICENSE_KEY="votre_clé"Installez la bibliothèque de requêtes et créez le fichier queries.txt, avec une expression de recherche par ligne, par exemple nom du produit configuration et nom de la fonctionnalité ne fonctionne pas. Choisissez les formulations en fonction de la langue du public et conservez une liste distincte afin de comparer les mêmes requêtes d’une collecte hebdomadaire à l’autre.
python -m pip install requestsCollectez et normalisez les vidéos trouvées
L’exemple est compatible avec Python 3.8 ou une version ultérieure. Il effectue une requête par expression, avec une limite de résultats, vérifie les erreurs HTTP et le statut renvoyé, puis n’enregistre que les champs réellement présents. Les doublons sont regroupés à l’aide de aweme_id, et toutes les requêtes ayant permis de trouver une vidéo sont consignées dans le champ keywords. Le champ distinct collected_at_utc indique l’heure de collecte afin de permettre les comparaisons avec les exécutions suivantes.
import csv
import os
import sys
from datetime import datetime, timezone
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not API_KEY:
raise SystemExit("Définissez JSONSCRAPER_TIKTOK_LICENSE_KEY")
def get_items(tiktok):
"""Extrait les vidéos des deux formats documentés de réponse de recherche."""
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info") if isinstance(entry, dict) else None
if info:
items.append(info)
return items
with open("queries.txt", encoding="utf-8") as query_file:
queries = [line.strip() for line in query_file if line.strip()]
collected_at = datetime.now(timezone.utc).isoformat()
videos = {}
for keyword in queries:
response = requests.get(
BASE_URL,
params={
"license_key": API_KEY,
"keyword": keyword,
"count": 30,
"region": "US",
"sort_by": "relevance",
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
print("Statut API en échec pour la requête :", keyword, file=sys.stderr)
continue
tiktok = payload.get("tiktok") or {}
for item in get_items(tiktok):
video_id = item.get("aweme_id")
if not video_id:
continue
if video_id not in videos:
author = item.get("author") or {}
stats = item.get("statistics") or {}
videos[video_id] = {
"aweme_id": video_id,
"keywords": [keyword],
"description": item.get("desc"),
"share_url": item.get("share_url"),
"create_time": item.get("create_time"),
"author": author.get("unique_id") or author.get("nickname"),
"play_count": stats.get("play_count"),
"digg_count": stats.get("digg_count"),
"comment_count": stats.get("comment_count"),
"share_count": stats.get("share_count"),
"collected_at_utc": collected_at,
}
elif keyword not in videos[video_id]["keywords"]:
videos[video_id]["keywords"].append(keyword)
columns = [
"aweme_id", "keywords", "description", "share_url", "create_time",
"author", "play_count", "digg_count", "comment_count", "share_count",
"collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
writer = csv.DictWriter(output, fieldnames=columns)
writer.writeheader()
for video in videos.values():
row = dict(video)
row["keywords"] = " | ".join(row["keywords"])
writer.writerow(row)
print("Nombre de vidéos uniques trouvées et enregistrées :", len(videos))La requête est envoyée à l’aide du paramètre params, de sorte que la bibliothèque encode correctement les expressions textuelles dans l’URL. La clé se trouve toutefois dans un paramètre de requête, comme l’indique la documentation ; n’affichez pas l’URL complète dans les journaux de l’application. Pour le diagnostic, conservez le code de réponse HTTP, l’expression de recherche et l’heure d’exécution, mais excluez les secrets et les données personnelles inutiles à cette tâche.
Lire le CSV sans tirer de conclusions hâtives
La colonne keywords contient toutes les expressions ayant permis de trouver une vidéo ; collected_at_utc permet de distinguer l’heure de publication de l’heure de collecte. L’ID facilite la déduplication et le lien permet une vérification humaine. Un compteur vide signifie que le champ était absent de la réponse concernée, et non que sa valeur est nulle.
Pour commencer le tri, ajoutez à une copie de travail du CSV les colonnes sujet, type de signal, réponse nécessaire et lien vers une ressource interne. Les sujets proposés doivent correspondre à votre produit : installation, paiement, compatibilité ou résolution d’erreurs, par exemple. Ce schéma transforme l’export en une file d’examen tout en permettant de vérifier la décision à partir de la vidéo d’origine.
Planifier la collecte
Commencez par exécuter le script manuellement et vérifiez quelques lignes et liens. Ajoutez-le ensuite à cron, à une tâche CI ou à un scénario d’automatisation capable de lancer un processus Python. Pour les rapports réguliers, enregistrez chaque export ou ajoutez les lignes à un entrepôt de données avec une clé unique pour la vidéo et la date de l’instantané. L’équipe pourra ainsi distinguer les nouvelles publications trouvées des observations répétées et suivre l’évolution des compteurs disponibles entre les exécutions.
Le paramètre cursor est prévu pour parcourir les résultats ; il faut transmettre celui de la réponse de l’appel précédent. La pagination est volontairement exclue de cet exemple minimal : un ensemble limité de requêtes est plus facile à vérifier et à reproduire. Si vous ajoutez des pages, traitez le curseur comme une valeur opaque, arrêtez-vous selon l’indicateur de continuation et fixez un nombre maximal d’appels par exécution. L’API renvoie un échantillon ; n’interprétez pas le nombre de lignes comme une couverture complète de TikTok.
Limites pratiques d’utilisation
Les résultats de recherche conviennent pour repérer des vidéos à partir de formulations déjà connues de l’équipe. Ils aident à rassembler du contenu à classer, mais ne remplacent ni les demandes entrantes, ni les statistiques de votre site, ni l’examen du contexte des vidéos. Une description peut ne pas rendre compte du contenu de la vidéo, et les métriques disponibles reflètent l’état des données au moment de la collecte. Notez les sujets et les conclusions séparément des champs d’origine afin que les collaborateurs puissent réexaminer la classification.
Avant de lancer une veille régulière, déterminez qui peut accéder à l’export, combien de temps les données seront conservées et à quelles fins les informations publiques seront utilisées. Ne conservez que les champs nécessaires à l’analyse du produit et privilégiez les liens vers les publications originales plutôt que la copie des fichiers multimédias. Pour envoyer une requête et vérifier les options d’intégration disponibles, consultez la page TikTok Scraper API et la documentation de la route de recherche.
