Comment ne pas perdre les résultats de recherche TikTok en analysant le JSON

Lors d’une recherche de vidéos TikTok via une API, les vidéos peuvent ne pas se trouver dans le tableau que le traitement s’attend à lire en premier. Dans la réponse jsonscraper examinée pour la requête `/searchVideo`, le champ `aweme_list` était vide et les éléments contenant les données vidéo se trouvaient dans `search_item_list[].aweme_info`. Si le code ne lit que `aweme_list`, il n’enregistrera aucune vidéo, alors que la réponse contient des résultats. Pour les développeurs, il s’agit d’un enjeu concret de fiabilité : extraire les deux formes de données et les normaliser dans une liste unique avant de les enregistrer dans une base de données ou de les transmettre à un rapport.

Vous pouvez consulter un exemple réel et la description de l’endpoint dans la spécification de l’API jsonscraper et la documentation de l’endpoint TikTok. L’instantané du schéma dans la spécification est daté du 25 octobre 2026 ; il illustre la structure d’une réponse donnée, sans garantir que chaque champ sera présent dans toutes les requêtes ultérieures.

Pourquoi l’analyseur peut renvoyer une liste vide

L’endpoint `GET https://tiktok.evelode.com/searchVideo` recherche des vidéos à partir du paramètre obligatoire `keyword`. La documentation répertorie également `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` et `region`. Dans le schéma de la réponse observée, l’objet de premier niveau contient `status` et un objet imbriqué `tiktok` ; celui-ci comprend `cursor`, `has_more`, `status_code`, `aweme_list` et `search_item_list`.

Dans l’observation réalisée pour une requête avec un mot-clé et `count=3`, le tableau `aweme_list` était vide. En revanche, `search_item_list` contenait des éléments dont les informations vidéo se trouvaient dans `aweme_info`. Ces objets pouvaient notamment contenir l’ID de la vidéo, sa légende, l’URL de publication, l’auteur et des statistiques comme le nombre de vues, de mentions J’aime ou de commentaires. Ces champs décrivent le schéma observé ; le traitement doit malgré tout tolérer les valeurs absentes.

En pratique, une requête HTTP réussie et la présence d’un tableau non vide dans le champ attendu sont deux vérifications distinctes. Vérifiez d’abord le statut externe et la présence de `tiktok`, puis rassemblez les vidéos issues de chaque emplacement documenté. Pour l’analyse, conservez les ID et la réponse d’origine : vous pourrez ainsi retracer l’extraction et la normalisation de chaque entrée.

Normalisez la réponse avant de l’enregistrer

Une frontière pratique entre l’API et votre propre système consiste à utiliser une fonction qui reçoit l’objet imbriqué `tiktok` et renvoie des éléments uniformisés. Elle doit traiter les deux tableaux, ignorer les éléments vides ou qui ne sont pas des dictionnaires et éliminer les doublons d’une même vidéo à partir de `aweme_id`. Laissez les compteurs vides lorsque le fournisseur ne les renvoie pas : zéro indique une valeur mesurée, tandis que `None` signale l’absence du champ.

Voici un exemple minimal pour Python 3.8 ou une version ultérieure. Il effectue une requête, vérifie le statut du transport et celui de la réponse au niveau supérieur, normalise les deux formes de résultats et affiche les champs choisis. La clé est lue depuis une variable d’environnement et n’est pas affichée dans les journaux.

import os
import requests

BASE_URL = "https://tiktok.evelode.com"


def extract_videos(tiktok):
    candidates = []
    aweme_list = tiktok.get("aweme_list") or []
    if isinstance(aweme_list, list):
        candidates.extend(aweme_list)

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

    unique = {}
    for video in candidates:
        if not isinstance(video, dict):
            continue
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


license_key = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
response = requests.get(
    BASE_URL + "/searchVideo",
    params={
        "license_key": license_key,
        "keyword": "python tutorial",
        "count": 10,
        "region": "US",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
    raise RuntimeError("Response has no tiktok object")

for video in extract_videos(tiktok):
    stats = video.get("statistics") or {}
    author = video.get("author") or {}
    print({
        "aweme_id": video.get("aweme_id"),
        "desc": video.get("desc"),
        "share_url": video.get("share_url"),
        "author": author.get("unique_id"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
    })

Installez la dépendance avec la commande python -m pip install requests, définissez `JSONSCRAPER_TIKTOK_LICENSE_KEY` dans l’environnement d’exécution et enregistrez le fichier, par exemple sous le nom `search_videos.py`. Les paramètres de la requête correspondent aux noms documentés : `keyword`, `count` et `region` ; `license_key` est transmis comme paramètre de requête. Le code suppose que la réponse contient `status: "ok"`, comme dans l’exemple consigné. Si l’API renvoie un autre statut, le traitement s’arrête avant de transmettre une structure douteuse à l’étape suivante.

Transformer l’exemple en collecte reproductible

Pour un export ponctuel, il suffit d’enregistrer les éléments normalisés en JSON Lines ou dans une table. Dans un processus permanent, ajoutez la conservation de la réponse d’origine, avec l’heure de réception et la requête de recherche. Une table distincte pour les vidéos normalisées peut utiliser `aweme_id` comme clé : un résultat répété met à jour l’entrée, et la présence du même ID dans les deux tableaux ne crée pas de doublon.

Pour demander la page suivante, la documentation indique le paramètre `cursor` : transmettez la valeur reçue dans la réponse précédente. Traitez-le comme un jeton opaque : stockez-le et renvoyez-le sans le modifier. La boucle de pagination doit s’arrêter lorsque `has_more` indique qu’il n’y a pas de suite ou lorsque l’API ne fournit pas de curseur exploitable ; limitez le nombre de pages par exécution afin qu’une erreur de logique ne crée pas de boucle infinie. Les sources consultées confirment le nom du paramètre et la présence des champs `cursor` et `has_more` dans le schéma observé, mais ne garantissent pas l’exhaustivité des résultats.

Pour surveiller plusieurs expressions de recherche, conservez l’expression avec l’ID de la vidéo et l’heure de collecte. Vous pourrez alors créer des vues par requête, comparer les résultats entre les exécutions et envoyer les nouveaux ID dans une file d’attente pour une classification ultérieure. Un tel système décrit les résultats de recherche obtenus ; son jeu de données dépend de la requête, de la région, du moment et des éléments effectivement renvoyés par l’API.

Vérifiez la qualité des données, pas seulement la réussite de la requête

Après la normalisation, il est utile de suivre des indicateurs techniques simples pour votre pipeline : le nombre d’entrées issues de chaque tableau, le nombre d’ID uniques, la proportion d’éléments sans ID et celle des éléments sans statistiques. Ces indicateurs décrivent le traitement d’une réponse particulière ; ils ne mesurent pas la popularité des vidéos. Par exemple, une hausse du nombre d’éléments sans `play_count` indique que l’outil d’analyse doit conserver une valeur inconnue et signaler que le champ est incomplet, au lieu de la remplacer par zéro.

Ne faites pas dépendre les calculs suivants de la présence systématique du même ensemble de statistiques pour chaque vidéo. Pour conserver les données brutes, gardez l’intégralité du JSON ; pour la table d’analyse, sélectionnez uniquement les champs nécessaires et autorisez les valeurs `NULL`. En cas de changement de la forme de la réponse, l’archive d’origine permettra de relancer le normalisateur sans effectuer une nouvelle requête.

Transmettez la clé API via les secrets de CI ou les variables d’environnement de l’orchestrateur. Ne l’incluez pas dans les URL conservées dans les journaux, n’affichez pas l’objet des paramètres de la requête et ne stockez pas la clé à côté des réponses d’origine. Si l’exécution est planifiée, ajoutez un délai maximal pour les requêtes, la gestion des erreurs HTTP et des tentatives répétées avec un temps d’attente ; ne stockez le curseur qu’avec la requête de recherche correspondante pour ne pas mélanger les pages de différents résultats.

Résultat : une table unifiée au lieu de vidéos manquantes

Après normalisation, le code en aval reçoit une seule liste de vidéos, qu’un élément provienne de `aweme_list` ou de `search_item_list[].aweme_info`. L’ID permet d’éliminer les doublons, tandis que les champs facultatifs restent explicitement vides. Cela réduit le risque de rapports vides parce qu’un seul tableau a été lu et rend l’étape suivante — export, filtrage ou classification — plus prévisible.

Pour commencer vos vérifications, consultez la page TikTok Scraper API, qui indique le point d’accès de base et propose un lien vers une démonstration. Pour l’intégration, utilisez la documentation officielle et testez d’abord le traitement avec un petit nombre d’éléments ; augmentez `count` si nécessaire et poursuivez les résultats à l’aide du curseur documenté. Vous obtiendrez ainsi une couche de données structurée pour vos besoins, sans supposer qu’elle couvre l’ensemble de TikTok.