TikTok : vérifier le bon fonctionnement de la surveillance des recherches

Un HTTP 200 ne garantit pas que la surveillance quotidienne de TikTok a collecté des vidéos. Les résultats de recherche peuvent se trouver dans aweme_list ou dans search_item_list[].aweme_info ; un script qui ne lit que le premier tableau peut se terminer sans erreur et enregistrer un rapport vide. Une vérification fiable confirme séparément les statuts de transport et d’application, extrait les deux structures prises en charge et consigne le nombre de vidéos uniques récupérées lors de cette exécution.

Que faut-il diagnostiquer exactement ?

Imaginez la situation suivante : chaque matin, une équipe collecte des vidéos publiques à partir de plusieurs requêtes afin de repérer les nouvelles publications sur un produit. Le résultat important de ce processus est une liste reproductible d’éléments trouvés, accompagnés de leur description, de leur auteur, de leur date de publication et des indicateurs disponibles. Si le rapport devient soudainement vide, cela peut être dû au traitement du JSON, à un changement dans l’ensemble des résultats, à la réapparition de vidéos déjà connues ou à un véritable échec de la requête. Un seul chiffre — par exemple, la longueur de aweme_list — ne permet pas de distinguer ces cas.

Dans l’API TikTok Scraper de jsonscraper, la route de recherche /searchVideo accepte le paramètre obligatoire keyword et les paramètres facultatifs count, cursor, date_posted, sort_by et region. La documentation de la route décrit la pagination avec cursor ; cette valeur opaque doit être transmise à partir de la réponse précédente. Le paramètre count indique le nombre de résultats souhaité, et non une garantie d’exhaustivité des publications.

Évaluez quatre signaux distincts

Un diagnostic utile repose sur quatre vérifications indépendantes. Premièrement, la requête HTTP s’est terminée avec succès. Deuxièmement, le status externe de la réponse vaut ok et le tiktok.status_code interne correspond à une réponse réussie. Troisièmement, l’objet tiktok est présent et les éléments sont extraits des deux emplacements documentés dans la réponse. Quatrièmement, après déduplication, il reste des éléments dotés d’identifiants pouvant être enregistrés. Dans le journal, conservez le nombre d’éléments extraits avant et après la déduplication : l’écart permet de repérer les doublons apparus lors de la normalisation.

Un champ absent doit rester vide, et non être remplacé par une valeur inventée. Par exemple, le nombre de vues peut manquer dans un enregistrement donné. Conserver le JSON d’origine à côté de la ligne normalisée permet de vérifier ensuite si une information a été perdue lors de l’analyse ou si elle était absente de la réponse initiale.

Requête minimale et normalisation en Python

La spécification de jsonscraper définit l’adresse de base https://tiktok.evelode.com et la transmission de la clé dans le paramètre de requête license_key. L’exemple ci-dessous utilise les paramètres documentés ; la clé est lue dans une variable d’environnement et n’apparaît pas dans le journal. Installez la dépendance avec la commande python -m pip install requests, puis définissez JSONSCRAPER_TIKTOK_LICENSE_KEY dans l’environnement.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def extract_videos(payload):
    """Rassembler les vidéos issues des deux structures connues des réponses de recherche."""
    tiktok = payload.get("tiktok") or {}
    videos = []

    for item in tiktok.get("aweme_list") or []:
        if isinstance(item, dict):
            videos.append(item)

    for item in tiktok.get("search_item_list") or []:
        if isinstance(item, dict):
            aweme = item.get("aweme_info")
            if isinstance(aweme, dict):
                videos.append(aweme)

    return videos


def main():
    params = {
        "license_key": KEY,
        "keyword": "exemple de requête sur un produit",
        "count": 20,
        "region": "US",
    }
    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")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("L’objet tiktok est absent de la réponse")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("Le status_code interne n’est pas la valeur de succès 0")

    raw_videos = extract_videos(payload)
    unique = {}
    for video in raw_videos:
        video_id = video.get("aweme_id")
        if video_id:
            unique.setdefault(str(video_id), video)

    snapshot = {
        "collected_at": datetime.now(timezone.utc).isoformat(),
        "keyword": params["keyword"],
        "status": payload.get("status"),
        "status_code": tiktok.get("status_code"),
        "raw_items": len(raw_videos),
        "unique_items": len(unique),
        "has_more": tiktok.get("has_more"),
        "cursor": tiktok.get("cursor"),
        "videos": list(unique.values()),
    }

    Path("snapshots").mkdir(exist_ok=True)
    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    Path(f"snapshots/{stamp}.json").write_text(
        json.dumps(snapshot, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

    print({
        "status": snapshot["status"],
        "status_code": snapshot["status_code"],
        "raw_items": snapshot["raw_items"],
        "unique_items": snapshot["unique_items"],
        "has_more": snapshot["has_more"],
    })


if __name__ == "__main__":
    main()

Le script vérifie la couche de transport avec raise_for_status(), puis contrôle le statut externe, la présence de l’objet tiktok et le status_code interne. Il extrait ensuite les éléments des deux structures de recherche, les déduplique par aweme_id et enregistre un instantané horodaté. Même si aucun élément correspondant n’est trouvé, le fichier contient les informations sur l’exécution : on peut ainsi distinguer un résultat vide enregistré d’un rapport manquant.

Transformer les instantanés en signal pour l’équipe

Exécutez le script selon un calendrier avec cron, un système CI ou un ordonnanceur de tâches. Conservez des instantanés distincts pour chaque requête ou ajoutez le mot-clé au nom du fichier. Le tableau d’état peut se limiter à l’heure d’exécution, au statut, au nombre d’éléments extraits et uniques ainsi qu’au booléen has_more. Il est utile d’envoyer une alerte en cas d’exception de requête, d’absence d’éléments obligatoires dans la réponse ou de variation soudaine du nombre d’éléments extraits par rapport à l’historique propre à la requête.

Cette comparaison détecte une anomalie du pipeline, mais n’en explique pas à elle seule la cause. Un nombre de résultats inférieur peut refléter la composition des résultats du moment, et non une défaillance de l’API ou de l’analyseur. Il est donc utile de conserver le JSON d’origine, de comparer des paramètres identiques et de vérifier les identifiants trouvés. Définissez le seuil d’alerte à partir des observations portant sur votre requête, plutôt qu’en appliquant un chiffre universel.

Pour la pagination, utilisez le cursor de la réponse et arrêtez le parcours lorsque l’API indique qu’il n’y a pas de résultats suivants. Conservez les curseurs utilisés et les paramètres de requête afin de pouvoir reproduire l’exécution. Les paramètres date_posted et sort_by permettent de définir un filtre temporel et un ordre de tri ; si la tâche nécessite des comparaisons reproductibles, gardez-les constants d’une exécution à l’autre.

Comment interpréter le résultat

Une fois le dispositif en place, l’équipe dispose d’une réponse vérifiable à trois questions pratiques : la requête a-t-elle abouti, où se trouvent les résultats dans le JSON et combien de vidéos uniques figurent dans l’instantané enregistré ? Cela réduit le temps nécessaire pour diagnostiquer un tableau vide : on vérifie d’abord les statuts et la structure, puis les paramètres, les doublons et le contenu de la réponse d’origine.

Le schéma de réponse et les champs disponibles peuvent varier d’un enregistrement à l’autre. Lors d’un test en direct de jsonscraper, le 25 octobre 2026, la recherche a renvoyé des champs d’identifiant, de description, d’auteur et de statistiques ; les valeurs d’un enregistrement précis doivent être considérées comme facultatives. Un rapport opérationnel conserve les données effectivement reçues et ne remplace pas les valeurs manquantes par des zéros.

Vous pouvez commencer par la page TikTok Scraper API, puis vérifier les routes et paramètres exacts dans la documentation officielle de l’API. Cette vérification est utile avant de lancer la surveillance : le rapport devient un résultat observable dont la qualité peut être diagnostiquée.