Michael JohnsonAprès le lancement d’une application ou d’une nouvelle fonctionnalité, les commentaires se dispersent rapidement dans des vidéos courtes. Un spécialiste du marketing trouve manuellement quelques vidéos et en partage les liens dans un chat, puis l’analyste ne sait plus quelles publications ont déjà été prises en compte ni comment leur nombre de vues a évolué. Une solution pratique consiste à collecter régulièrement les résultats de recherche à partir de plusieurs requêtes stables, à conserver les réponses brutes et à établir un rapport à partir des champs confirmés.
Dans ce guide, nous allons configurer cette collecte pour un cas concret : une équipe vient de lancer une fonctionnalité et souhaite suivre chaque semaine les vidéos TikTok publiques dont la description mentionne le nom du produit, une fonctionnalité clé ou un problème courant rencontré par les utilisateurs. Il s’agit du suivi d’un échantillon trouvé par recherche : l’API renvoie les résultats correspondant à la requête et aux paramètres, et non une liste exhaustive garantie de toutes les publications relatives au lancement.
Définir d’abord le signal dont l’équipe a besoin
Un nombre élevé de vues n’indique pas, à lui seul, la marche à suivre. Il est plus utile à l’équipe de savoir quelles questions reviennent, quels scénarios les utilisateurs montrent et quelles vidéos suscitent des réactions publiques notables. Commencez donc par définir plusieurs expressions de recherche et par choisir les champs qui figureront dans le rapport.
Par exemple, pour le lancement d’un outil de planification de publications, vous pouvez essayer les requêtes « nom du produit », « planificateur de contenu » et « comment programmer une vidéo TikTok ». Les expressions doivent refléter les différentes façons dont les internautes peuvent décrire un même sujet. Notez-les avec la date de début du suivi et la région afin de pouvoir comparer les collectes ultérieures avec les mêmes paramètres.
Un tableau minimal peut inclure l’heure de collecte, l’expression de recherche, l’identifiant de la vidéo, son lien, sa description, le nom et l’identifiant de l’auteur, ainsi que les valeurs disponibles pour les vues, les mentions « J’aime » et les commentaires. Pour les résultats de recherche, TikTok Scraper API documente des champs tels que aweme_id, desc, share_url, des informations sur l’auteur et certaines statistiques. Vérifiez la présence de chaque champ dans chaque objet : certaines métriques peuvent être absentes.
Utiliser la recherche documentée
Pour rechercher des vidéos, utilisez la route GET /searchVideo à l’adresse de base https://tiktok.evelode.com. La documentation répertorie le paramètre obligatoire keyword et les paramètres facultatifs count, cursor, date_posted, sort_by, region et cache_timeout. Les valeurs possibles du filtre de date incluent this-week, et celles du tri incluent relevance, most-liked et date-posted. Consultez le guide des routes TikTok API pour vérifier leur rôle et leur nom.
La clé de licence se transmet sous la forme du paramètre de requête license_key. Dans un script de production, lisez-la depuis la variable d’environnement JSONSCRAPER_TIKTOK_LICENSE_KEY, ne l’inscrivez pas dans le code source et ne l’affichez pas dans les journaux. Cet exemple, prévu pour Python 3.8 ou une version ultérieure, utilise le paquet requests :
import os
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def search_videos(keyword, cursor=None):
params = {
"license_key": API_KEY,
"keyword": keyword,
"count": 20,
"date_posted": "this-week",
"sort_by": "date-posted",
"region": "US",
}
if cursor is not None:
params["cursor"] = cursor
response = requests.get(
f"{BASE_URL}/searchVideo",
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("L’API TikTok a renvoyé un statut différent de ok")
return payload["tiktok"]
result = search_videos("content planning app")
print("Objets trouvés :", len(result.get("aweme_list", [])))Le script vérifie les erreurs HTTP et le statut général de la réponse. Une réponse HTTP réussie ne garantit pas, à elle seule, que la recherche contient des vidéos : si l’échantillon est vide, la liste peut l’être aussi. Pour le premier lancement, il est utile de conserver la réponse complète dans un espace de stockage sécurisé afin de comparer les objets réels avec le tableau de champs normalisés.
Gérer les deux formats de réponse de recherche
La structure des résultats de recherche présente une particularité importante. Les vidéos peuvent se trouver directement dans tiktok.aweme_list ou être renvoyées dans tiktok.search_item_list[].aweme_info. Un processeur qui ne lit que la première liste risque de manquer les résultats présents dans le second format.
Ajoutez un petit normaliseur qui prend en charge les deux structures et ignore sans erreur les éléments dépourvus d’objet vidéo imbriqué :
def extract_awemes(tiktok):
items = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
aweme = item.get("aweme_info")
if aweme:
items.append(aweme)
return items
def normalize(aweme, keyword, collected_at):
author = aweme.get("author") or {}
stats = aweme.get("statistics") or {}
return {
"collected_at": collected_at,
"keyword": keyword,
"video_id": aweme.get("aweme_id"),
"posted_at": aweme.get("create_time"),
"description": aweme.get("desc"),
"share_url": aweme.get("share_url"),
"author_id": author.get("uid"),
"author_name": author.get("nickname"),
"views": stats.get("play_count"),
"likes": stats.get("digg_count"),
"comments": stats.get("comment_count"),
"shares": stats.get("share_count"),
}Une valeur manquante reste None. Ne la remplacez pas par zéro : zéro représente une valeur mesurée, tandis que None indique que le champ n’a pas été renvoyé. Cette distinction a une incidence sur les moyennes, les proportions et les conclusions de l’équipe.
Conserver l’historique plutôt qu’un simple instantané
Pour observer l’évolution, stockez des enregistrements distincts pour chaque observation. L’identifiant vidéo convient à la déduplication des publications, mais ne doit pas servir à supprimer l’historique : la réapparition d’une même vidéo lors de la collecte suivante constitue un nouveau point d’observation. Par exemple, vous pouvez créer une clé unique pour la table des observations à partir de video_id et collected_at, et conserver le lien et la description dans l’enregistrement pour faciliter la vérification.
Un schéma SQLite minimal convient à un prototype :
import sqlite3
conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
video_id TEXT NOT NULL,
collected_at TEXT NOT NULL,
keyword TEXT NOT NULL,
posted_at INTEGER,
description TEXT,
share_url TEXT,
author_id TEXT,
author_name TEXT,
views INTEGER,
likes INTEGER,
comments INTEGER,
shares INTEGER,
PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()En pratique, normalisez l’heure de collecte en UTC, conservez séparément le JSON brut et ajoutez une colonne indiquant la version du schéma. La réponse brute permet de vérifier la transformation lorsque la structure des nouveaux objets diffère de celle à laquelle vous êtes habitué. Pour les publications trouvées par plusieurs requêtes, conservez les expressions correspondantes dans une table liée distincte ou regroupez-les lors de la création du rapport.
Pagination : ne continuer qu’avec le curseur renvoyé
Le paramètre cursor sert à poursuivre une recherche. Sa valeur provient de la réponse précédente et doit être renvoyée sans transformation. La collecte s’arrête lorsque has_more n’indique plus de résultats supplémentaires ou lorsqu’une limite définie est atteinte. Le curseur doit être considéré comme opaque : ne le calculez pas vous-même et ne le remplacez pas par un numéro de page.
def collect_pages(keyword, max_pages=3):
cursor = None
collected = []
for _ in range(max_pages):
page = search_videos(keyword, cursor)
collected.extend(extract_awemes(page))
if not page.get("has_more"):
break
cursor = page.get("cursor")
if cursor is None:
break
return collectedLimiter le nombre de pages permet de rendre prévisible le volume de requêtes d’une tâche récurrente. Consignez le nombre de pages et la valeur de has_more dans le journal d’exécution : cela donne du contexte au rapport sur l’échantillon. Même avec la pagination, le résultat décrit les réponses reçues de l’API et la limite de collecte définie ; il ne constitue pas une estimation de l’ensemble des publications sur la plateforme.
Créer un rapport reproductible
Planifiez la collecte une fois par semaine, ou plus souvent si l’équipe a besoin de signaux plus fréquents. Pour chaque exécution, consignez la liste des requêtes, les paramètres, l’heure, le nombre d’objets reçus et le nombre d’identifiants uniques. Comptez séparément les publications repérées pour la première fois lors de cette exécution et celles déjà observées.
Quatre vues simples peuvent être utiles dans le rapport :
- Nouvelles vidéos : liens, descriptions, dates de publication et expression de recherche ayant permis de trouver la vidéo.
- Thèmes récurrents : regroupement des descriptions selon des catégories définies manuellement, par exemple « erreur de configuration », « demande de fonctionnalité » et « présentation d’un scénario d’utilisation ».
- Réactions publiques : vues, mentions « J’aime », commentaires et partages disponibles, affichés avec l’heure de l’observation.
- Signaux à vérifier : nouvelles formulations, questions fréquentes ou vidéos qu’un membre de l’équipe devrait examiner.
Ne qualifiez pas l’écart entre deux instantanés de « nouveaux J’aime » sans vérifier la nature et la fraîcheur des valeurs dans la réponse. Préférez une formulation exacte comme « valeur de la métrique dans la dernière réponse reçue » et « écart entre les instantanés enregistrés ». L’équipe sait ainsi précisément ce qui a été calculé et peut consulter la publication d’origine avant de prendre une décision.
Utiliser l’IA pour classifier, et non pour remplacer la collecte
Après la normalisation, vous pouvez transmettre les descriptions des vidéos à un modèle afin de les classer dans des catégories prédéfinies. N’envoyez que les champs textuels nécessaires et demandez un résultat structuré : catégorie, justification succincte, niveau de confiance et extrait de la description sur lequel repose l’étiquette. Conservez la publication d’origine avec l’étiquette pour permettre à l’analyste de vérifier les cas litigieux.
Le flux de travail reste simple : un planificateur lance la collecte ; Python vérifie la réponse et enregistre le JSON ; une tâche distincte normalise les nouveaux enregistrements ; le classificateur traite uniquement les nouvelles descriptions ; le rapport est généré à partir de la base de données et envoyé dans le canal choisi par l’équipe. TikTok Scraper API fournit les données de recherche, tandis que la classification et l’envoi du rapport relèvent de votre logique d’intégration, que vous pouvez mettre en œuvre avec Python, n8n ou Make.
Pour réduire le bruit, définissez un vocabulaire de catégories avant d’envoyer les données au modèle et vérifiez régulièrement un échantillon étiqueté manuellement. Pour les descriptions courtes ou ambiguës, un statut « contexte insuffisant » est préférable à l’attribution forcée d’une catégorie. Les étiquettes de l’IA aident à trier les éléments à examiner ; pour confirmer les problèmes rencontrés par les utilisateurs, lisez les publications et comparez plusieurs observations.
Erreurs, nouvelles tentatives et gestion sécurisée de la clé
Une requête réseau peut expirer, échouer temporairement ou renvoyer une réponse impossible à analyser en JSON. Séparez le traitement en étapes : requête, vérification du code HTTP, analyse du JSON, validation du statut général, normalisation et enregistrement. En cas de panne temporaire, effectuez un nombre limité de nouvelles tentatives avec des délais croissants ; consignez les erreurs persistantes pour les examiner plus tard, sans marquer l’exécution comme réussie.
Conservez la clé dans le gestionnaire de secrets de l’environnement d’exécution ou dans une variable d’environnement. Comme l’API accepte license_key dans la chaîne de requête, évitez de journaliser l’URL complète et les paramètres : ils contiendraient le secret. Pour le diagnostic, consignez la route, le code de réponse, la durée, l’expression de recherche et l’identifiant de la tâche, en supprimant la clé des journaux.
Définissez la fréquence et le volume de l’échantillon en fonction de vos besoins et des conditions d’utilisation de la plateforme. Limitez la collecte de données publiques à ce qui est réellement nécessaire à l’analyse ; décrivez dans les règles internes de l’équipe la conservation des descriptions, des liens et des identifiants d’auteur. Les réponses de l’API et les métriques peuvent être incomplètes ou évoluer d’une observation à l’autre : le rapport doit donc conserver l’heure de collecte et l’origine de chaque ligne.
Résultat : passer des liens partagés manuellement à un historique vérifiable
Une fois le système configuré, l’équipe dispose d’une liste régulièrement mise à jour des vidéos trouvées, des réponses d’origine pour les audits, d’un tableau des métriques publiques disponibles et d’un aperçu des thèmes récurrents. Cela permet de repérer plus rapidement les questions relatives à une nouvelle fonctionnalité, de trouver des exemples de scénarios d’utilisation et de sélectionner des publications à analyser manuellement. La comparaison des instantanés montre comment évoluent les valeurs enregistrées pour les vidéos déjà repérées, et le journal des requêtes explique comment l’échantillon a été constitué.
Commencez par une seule requête et une limite de pages réduite, vérifiez la structure réelle de la réponse, puis ajoutez d’autres formulations et une planification. Avant de mettre le prototype en production, définissez des règles de déduplication, de conservation et de gestion des erreurs. Les routes et paramètres à jour figurent dans la documentation officielle de l’API ; la page TikTok Scraper API présente ses fonctionnalités et permet de commencer les tests.
