Un rapport hebdomadaire sur les recherches TikTok est utile lorsqu’il montre quelles vidéos sont apparues dans la collecte depuis la dernière exécution. Il suffit de conserver les identifiants des vidéos déjà rencontrées et d’ajouter les nouveaux résultats à un CSV. Voici un script Python reproductible utilisant le TikTok Scraper API : il recherche des vidéos par mot-clé, analyse les deux formats de réponse documentés et tient une base locale d’identifiants.
Objectif : repérer les nouvelles publications sans repasser en revue tous les résultats
Une équipe d’assistance, un analyste de marché ou une personne chargée de l’analyse de contenu peut avoir besoin d’une collecte régulière de vidéos publiques correspondant à une requête sur un produit. Si les résultats sont exportés intégralement à chaque fois, les vidéos répétées compliquent la vérification et les nouvelles entrées se perdent parmi celles déjà traitées. Un journal d’identifiants permet de comparer le résultat de chaque exécution : le CSV ne contient que les vidéos nouvelles pour ce processus, avec les principaux champs renvoyés dans la réponse.
Ce journal répond à une question limitée, mais pratique : quels éléments figuraient dans la réponse de l’exécution en cours et étaient absents de l’ensemble d’identifiants enregistré ? C’est utile pour constituer une file de vérification manuelle et transmettre les données à un tableur ou à une analyse ultérieure. La collecte reflète les résultats de l’API pour la requête indiquée ; à elle seule, elle ne décrit pas toutes les publications TikTok.
Prérequis
- Python 3.8 ou version ultérieure.
- Un accès au TikTok Scraper API et une clé de licence.
- Une requête que vous pouvez répéter sans en modifier le sens, par exemple le nom d’un produit ou une expression précise.
Enregistrez la clé dans la variable d’environnement JSONSCRAPER_TIKTOK_LICENSE_KEY, et non dans le fichier du script. Dans l’exemple ci-dessous, la clé est transmise dans le paramètre de requête license_key, conformément au schéma de l’API. Ne l’affichez pas dans les journaux d’exécution.
export JSONSCRAPER_TIKTOK_LICENSE_KEY="votre_clé"
python -m pip install requests
Dans Windows PowerShell, vous pouvez définir la variable pour la session en cours ainsi : $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="votre_clé". N’ajoutez pas de véritables secrets à Git ni à un CSV partagé.
Intégration : lancer la recherche et normaliser le JSON
Pour rechercher des vidéos, la documentation décrit la route GET /searchVideo, qui exige le paramètre keyword. La requête peut aussi définir count, une région, un tri, un filtre temporel et un curseur pour parcourir les résultats. Cet exemple minimal utilise uniquement un mot-clé, le nombre d’éléments demandés et la région des États-Unis. Le répertoire des routes de l’API TikTok énumère les noms exacts des paramètres.
La structure de la réponse de recherche mérite une attention particulière : le tableau aweme_list peut être vide et les vidéos peuvent se trouver dans search_item_list, avec leurs données imbriquées dans aweme_info. Le code vérifie donc les deux chemins, puis rassemble les éléments et élimine les doublons à partir de aweme_id. Cela évite qu’un JSON correctement analysé ne produise par erreur un rapport vide.
import csv
import json
import os
from pathlib import Path
from datetime import datetime, timezone
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "nom du produit"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")
license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
raise RuntimeError("Définissez JSONSCRAPER_TIKTOK_LICENSE_KEY")
response = requests.get(
BASE_URL,
params={
"license_key": license_key,
"keyword": KEYWORD,
"count": COUNT,
"region": REGION,
},
timeout=60,
)
response.raise_for_status()
data = response.json()
# L’exemple de réponse contient un status externe et un objet tiktok imbriqué.
if "status" in data and data["status"] != "ok":
raise RuntimeError("L’API a renvoyé un statut différent de ok")
tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info")
if isinstance(info, dict):
items.append(info)
# Éléments uniques de la réponse en cours, dans leur ordre d’origine.
current = {}
for item in items:
video_id = item.get("aweme_id")
if video_id:
current[str(video_id)] = item
if STATE_FILE.exists():
seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
seen = set()
new_items = [(video_id, item) for video_id, item in current.items()
if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()
fields = ["collected_at_utc", "query", "aweme_id", "created_at",
"author", "description", "share_url", "play_count",
"digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=fields)
if write_header:
writer.writeheader()
for video_id, item in new_items:
author = item.get("author") or {}
stats = item.get("statistics") or {}
writer.writerow({
"collected_at_utc": run_time,
"query": KEYWORD,
"aweme_id": video_id,
"created_at": item.get("create_time"),
"author": author.get("unique_id") or author.get("nickname"),
"description": item.get("desc"),
"share_url": item.get("share_url"),
"play_count": stats.get("play_count"),
"digg_count": stats.get("digg_count"),
"comment_count": stats.get("comment_count"),
"share_count": stats.get("share_count"),
})
seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"Dans la réponse : {len(current)} vidéos uniques ; nouvelles : {len(new_items)}")
Le script laisse vides les cellules correspondant aux valeurs absentes du JSON : certains champs et indicateurs peuvent ne pas figurer dans une entrée. Le code ne remplace pas une valeur manquante par zéro et ne confond pas zéro avec une donnée absente. L’heure de collecte est enregistrée séparément de l’heure de publication renvoyée par l’API dans le champ create_time.
Fonctionnement de la détection des changements
- La requête renvoie une page de résultats de recherche pour le mot-clé défini.
- Le normalisateur rassemble les enregistrements de
aweme_listet desearch_item_list[].aweme_info. - Le script élimine les doublons dans la réponse à partir de l’identifiant de la vidéo.
- Les identifiants sont comparés au journal JSON local.
- Les nouveaux identifiants sont ajoutés au CSV, puis l’ensemble des identifiants rencontrés est enregistré pour la prochaine exécution.


La visualisation de ce processus peut être utile lorsque le script est transmis à des collègues : le CSV est un journal cumulatif, tandis que le JSON conserve l’état de déduplication. Vous pouvez les stocker séparément du code et les sauvegarder ensemble. Pour une exécution en équipe ou dans le cloud, remplacez le fichier JSON local par un stockage persistant adapté et prévoyez une mise à jour atomique de l’état afin que des exécutions simultanées ne s’écrasent pas mutuellement.
Relancer le script et gérer la pagination
Programmez les exécutions avec le planificateur du système d’exploitation, une tâche CI ou un processus d’automatisation. Ne modifiez pas le mot-clé sans noter sa version : des requêtes différentes produisent des collectes différentes, et les regrouper dans un seul journal complique l’interprétation. Par souci de simplicité, le script présenté utilise une seule requête ; vous pouvez traiter une liste de requêtes dans une boucle et conserver le champ query pour chaque ligne.
L’API prend en charge cursor pour parcourir les résultats de recherche. Si vous ajoutez la pagination, transmettez le curseur de la réponse précédente, conservez-le comme valeur opaque et arrêtez le parcours lorsque les pages suivantes ne sont plus nécessaires. La limite count définit le nombre d’éléments demandés, mais le nombre réel d’enregistrements doit être déterminé à partir de la réponse. Même plusieurs pages restent des pages de résultats de recherche obtenues ; elles ne garantissent pas une couverture complète de la plateforme.
Le scénario présenté ne comporte volontairement aucune classification automatique du texte ni conclusion sur une « tendance ». Le CSV permet de repérer rapidement les nouvelles entrées trouvées ; un analyste peut ensuite les annoter par thème, intention ou type de question et vérifier les exemples manuellement. Si vous connectez un modèle de langage, ne lui transmettez que les champs textuels nécessaires et demandez-lui de renvoyer les catégories avec l’identifiant d’origine, afin de pouvoir vérifier le résultat et le relier à l’enregistrement.
Vérifications et erreurs courantes
- Erreur HTTP.
raise_for_status()interrompt l’exécution en cas de code HTTP hors de la plage de réussite. Vérifiez la disponibilité de l’API, les paramètres et le compte avant de mettre à jour le fichier d’état. - Le statut de l’API est différent de
ok. Le script s’arrête avant d’enregistrer les résultats si la réponse contient un champ de premier niveaustatusavec une autre valeur. Le journal précédent est ainsi préservé et une réponse erronée ne risque pas d’être prise pour une recherche sans résultat. - La liste
aweme_listest vide. Vérifiez égalementsearch_item_list; le code tient compte des deux structures. - Des vidéos réapparaissent d’une exécution à l’autre. C’est normal lorsque les pages de résultats de recherche se chevauchent : les vidéos ne sont pas ajoutées une seconde fois au rapport si leur identifiant est déjà enregistré.
- Un indicateur est absent. La cellule reste vide. Dans vos calculs, distinguez les valeurs absentes des véritables zéros.
- L’état a été perdu. Le script considérera toutes les vidéos renvoyées comme nouvelles. Sauvegardez
seen_video_ids.jsonavec le CSV ou utilisez une base de données persistante.
Lors de l’automatisation, consignez les informations de diagnostic sans la clé : heure d’exécution, code HTTP, statut de l’API, nombre d’enregistrements analysés et nombre de nouveaux identifiants. Vous pourrez ainsi distinguer l’absence de nouvelles vidéos d’un échec de la requête. Vous pouvez archiver séparément la réponse complète d’origine si une vérification ultérieure du schéma est nécessaire ; limitez-en l’accès et la durée de conservation selon les besoins de l’équipe.
Résultat
Après l’exécution, vous disposez d’un CSV contenant les vidéos dont l’identifiant est nouveau pour le journal, avec leur description, leur lien et les champs publics disponibles, ainsi que d’un état JSON permettant la comparaison lors de la prochaine exécution. Ce résultat constitue une file d’entrée compacte pour une équipe d’assistance, d’analyse ou de contenu. Vous pouvez consulter la description de l’API et les options d’accès sur la page du TikTok Scraper API ; vérifiez les paramètres exacts de recherche dans le répertoire officiel des routes.