Repérer les vidéos TikTok dont l’engagement progresse sans comparer les vues brutes

Pour savoir si une vidéo TikTok suscite davantage de réactions, comparez ses métriques publiques à son propre relevé précédent. Une recherche ponctuelle indique le nombre de vues et de réactions déjà accumulées ; une nouvelle collecte des mêmes vidéos trouvées permet de voir l’évolution entre deux exécutions. Voici un pipeline Python minimal et fonctionnel : requête de recherche, enregistrement des métriques dans un fichier CSV et calcul de leur variation.

Que mesure exactement ce suivi ?

Ce script convient aux spécialistes du marketing, aux analystes ou aux développeurs qui ont besoin d’une liste de vidéos trouvées sur un sujet et d’un historique vérifiable des observations. Par exemple, une équipe suit régulièrement les vidéos sur le lancement d’un produit ou une requête précise du public et veut repérer celles qui ont gagné des vues, des mentions J’aime, des commentaires ou des partages depuis la vérification précédente.

L’unité de comparaison est la vidéo, identifiée par aweme_id. Pour chaque entrée, on enregistre l’heure de collecte, l’identifiant, la description, l’URL, le nom de l’auteur et les compteurs disponibles. On rapproche ensuite deux relevés à l’aide de l’identifiant. Ainsi, la hausse des vues d’une vidéo n’est pas confondue avec le total accumulé par une autre.

Le résultat ne décrit que les vidéos renvoyées par une requête de recherche donnée lors d’une exécution donnée. Les résultats de recherche peuvent varier et certains champs statistiques peuvent être absents. Il est donc utile de conserver les relevés eux-mêmes et leur heure de collecte, et d’interpréter le rapport comme un suivi des vidéos déjà trouvées, non comme un catalogue complet des publications sur le sujet.

Comment la collecte par API fonctionne-t-elle ?

La documentation de TikTok Scraper API décrit la route GET /searchVideo. Le paramètre keyword est obligatoire pour la recherche ; les paramètres facultatifs comprennent count, region, sort_by et date_posted. La clé API se transmet avec license_key. La documentation indique https://tiktok.evelode.com comme URL de base.

La réponse contient un statut externe et un objet tiktok. Dans les résultats de recherche, les vidéos peuvent se trouver dans tiktok.aweme_list ou dans tiktok.search_item_list[].aweme_info. Le gestionnaire ci-dessous prend en charge les deux structures. Les métriques proviennent de statistics et comprennent play_count, digg_count, comment_count et share_count ; si une valeur est absente, elle reste vide au lieu d’être remplacée par zéro.

La documentation des routes répertorie cursor pour parcourir les résultats de recherche et précise les valeurs admises pour date_posted et sort_by. Pour un suivi simple et reproductible, commencez par récupérer une page de résultats et enregistrer la réponse ; n’ajoutez la pagination qu’en cas de besoin. Si nécessaire, transmettez le curseur reçu sans le modifier.

Exemple fonctionnel en Python

Installez la bibliothèque de requêtes avec la commande python -m pip install requests et définissez la clé dans la variable d’environnement JSONSCRAPER_TIKTOK_LICENSE_KEY. Le script prend une expression de recherche en argument et ajoute les relevés des vidéos trouvées à un seul fichier CSV. Le code est compatible avec Python 3.8 et versions ultérieures.

import csv
import os
import sys
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
CSV_PATH = Path("tiktok_video_snapshots.csv")
FIELDS = [
    "collected_at", "aweme_id", "author", "description", "share_url",
    "play_count", "digg_count", "comment_count", "share_count",
]


def extract_items(payload):
    """Prend en charge les structures de réponse de recherche observées."""
    data = payload.get("tiktok") or {}
    items = data.get("aweme_list") or []
    if items:
        return items

    found = []
    for result in data.get("search_item_list") or []:
        info = result.get("aweme_info")
        if info:
            found.append(info)
    return found


def main():
    key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
    if not key:
        raise SystemExit("Définissez d’abord JSONSCRAPER_TIKTOK_LICENSE_KEY")
    if len(sys.argv) < 2:
        raise SystemExit('Utilisation : python collect.py "expression de recherche"')

    params = {
        "license_key": key,
        "keyword": sys.argv[1],
        "count": 20,
        "region": "US",
        "sort_by": "relevance",
        "date_posted": "this-week",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("L’API a renvoyé un statut externe différent de ok")
    data = payload.get("tiktok") or {}
    items = extract_items(payload)
    collected_at = datetime.now(timezone.utc).isoformat()

    rows = []
    for item in items:
        stats = item.get("statistics") or {}
        author = item.get("author") or {}
        rows.append({
            "collected_at": collected_at,
            "aweme_id": item.get("aweme_id"),
            "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"),
        })

    write_header = not CSV_PATH.exists()
    with CSV_PATH.open("a", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=FIELDS)
        if write_header:
            writer.writeheader()
        writer.writerows(rows)

    print("Enregistré", len(rows), "vidéos renvoyées")
    print("has_more :", data.get("has_more"), "cursor :", data.get("cursor"))


if __name__ == "__main__":
    main()

Exécutez, par exemple, python collect.py "requête sur un produit". La bibliothèque ajoute la clé aux paramètres de l’URL ; le script ne l’affiche pas dans le terminal. Évitez d’enregistrer l’URL complète de la requête dans des journaux accessibles au public, car elle contient la clé. Pour un système en production, utilisez un gestionnaire de secrets et limitez l’accès au fichier des relevés.

Comment calculer la hausse entre deux exécutions ?

Le script enregistre volontairement toutes les observations au lieu d’écraser les valeurs précédentes. L’analyseur suivant rapproche les deux relevés les plus récents de chaque vidéo et affiche la différence entre les compteurs. Si une métrique est absente de l’un des deux enregistrements, le résultat est indiqué comme indisponible.

import csv
from collections import defaultdict
from pathlib import Path

rows_by_video = defaultdict(list)
with Path("tiktok_video_snapshots.csv").open(encoding="utf-8", newline="") as file:
    for row in csv.DictReader(file):
        if row["aweme_id"]:
            rows_by_video[row["aweme_id"]].append(row)

metrics = ("play_count", "digg_count", "comment_count", "share_count")
for video_id, snapshots in rows_by_video.items():
    snapshots.sort(key=lambda row: row["collected_at"])
    if len(snapshots) < 2:
        continue
    previous, latest = snapshots[-2], snapshots[-1]
    changes = {}
    for metric in metrics:
        old, new = previous[metric], latest[metric]
        changes[metric] = int(new) - int(old) if old and new else None
    print(video_id, changes, latest["share_url"])

La variation correspond à la différence entre deux valeurs enregistrées ; ce n’est pas un taux de croissance calculé selon une périodicité garantie. Si les exécutions sont espacées d’intervalles différents, ajoutez le calcul de la durée écoulée entre les valeurs de collected_at et comparez les hausses sur la période réelle. Les compteurs peuvent évoluer entre deux observations ; les horodatages enregistrés indiquent quand les valeurs utilisées ont été obtenues.

Comment automatiser et interpréter le rapport ?

Pour produire un rapport quotidien, planifiez la collecte sur un serveur ou dans un pipeline CI, définissez une liste fixe d’expressions de recherche et enregistrez le CSV ou chargez les lignes dans une base de données. Lors des exécutions répétées, dédupliquez les enregistrements d’un même relevé à l’aide de aweme_id si les résultats contiennent des doublons. Pour conserver l’historique, stockez le JSON d’origine avec les colonnes normalisées : cela facilitera le retraitement si le schéma du rapport change.

Un tableau peut afficher l’identifiant et l’URL de la vidéo, l’auteur, la description, l’heure de collecte et les variations de chaque métrique. Un tri par hausse des vues renseigne sur la diffusion, tandis que la progression des commentaires ou des partages permet de repérer un autre type de réaction. Ne combinez pas ces indicateurs en un classement unique sans règle explicite : chaque compteur a sa propre signification.

Un planificateur peut envoyer le rapport par courriel, dans un tableur ou sur un canal interne, mais cette étape relève de votre infrastructure : l’exemple ci-dessus se limite à collecter et analyser les données. Pour une collecte plus complète, parcourez les pages de résultats, enregistrez le curseur et arrêtez la boucle lorsque l’API indique qu’il n’y a plus de pages. Le curseur de recherche est une valeur opaque renvoyée par la réponse ; ne le calculez pas vous-même. Même le parcours des pages ne décrit que les résultats renvoyés et ne garantit pas une liste exhaustive de toutes les publications pertinentes.

Le résultat pratique attendu est un journal d’observations reproductible et un tableau des variations pour les vidéos trouvées. Cela aide à repérer les publications dont les compteurs publics ont évolué entre deux vérifications, puis à transmettre des liens précis à un spécialiste pour une analyse de fond. Consultez la page TikTok Scraper API pour en savoir plus sur le produit et l’accès à l’API.

Que vérifier avant de planifier les exécutions ?

• Assurez-vous que le statut externe de la réponse est ok avant de traiter tiktok.
• Vérifiez les deux structures possibles des éléments de recherche ; une liste absente doit produire une collecte vide, et non une erreur.
• Conservez les valeurs d’origine et les horodatages. Une métrique vide doit le rester.
• Utilisez les mêmes requêtes et paramètres pour faciliter la comparaison des relevés ; consignez à côté du rapport toute modification de ces réglages.
• Surveillez la fréquence des exécutions, les erreurs HTTP et la taille de l’historique ; respectez également les règles applicables de la plateforme et les exigences relatives au traitement des données.

En bref, pour obtenir un résultat exploitable, il suffit de répéter la même recherche, d’identifier les vidéos par aweme_id et de comparer leurs métriques enregistrées au fil du temps. Cette approche répond à une question pratique précise — quelles vidéos déjà trouvées ont vu leurs compteurs publics évoluer entre deux vérifications — tout en conservant les données d’origine pour l’audit et les traitements ultérieurs.