TikTokTikTok Search APITikTok Top Search APITikTok Photo Carousel APIRecherche par mot-clé

API TikTok Search : trouver des vidéos et des carrousels photo

Explorez les vidéos et les carrousels photo TikTok avec SocQ. Collectez légendes, créateurs, médias et nombres d’engagement, avec des filtres et du code d’export JSON et CSV.

SocQMis à jour le 16 octobre 20268 min de lecture

Explorez ensemble les vidéos et les carrousels photo TikTok avec SocQ. Collectez les légendes, les créateurs, les liens de médias et les nombres d’engagement autour d’un même mot-clé, puis classez les démonstrations vidéo, les fiches de recettes et les guides en images dans un seul jeu de données thématique.

L’API SocQ TikTok Top Search recherche par mot-clé les vidéos et les carrousels photo publics. Ce guide présente la requête, le traitement des formats de résultats et l’export des publications et des liens d’images ordonnés.

Réponse rapide : envoyez un query obligatoire à POST /v1/tiktok/top-search. Une fois la tâche réussie, lisez data.results.items. Utilisez type=video pour les vidéos et type=photo_carousel pour les publications d’images ; les images du carrousel se trouvent dans media.

Choisir l’endpoint de recherche selon le format de contenu

Point de départEndpoint SocQPérimètre des résultats
Mot-clé, vidéos uniquementTikTok SearchUn workflow de recherche de vidéos
Mot-clé, vidéos et publications d’imagesTikTok Top SearchRésultats mixtes distingués par type
URL de publication connueTikTok VideosRécupérer le contenu indiqué
ID de son connuTikTok Song VideosTrouver les vidéos associées à ce son

Top Search renvoie des publications existantes pour un mot-clé. Pour travailler sur les publications photo, sélectionnez type=photo_carousel dans les résultats et lisez les images dans media.

Rechercher sur TikTok par mot-clé

Définissez SOCQ_API_KEY et envoyez une recherche plafonnée à 20 enregistrements :

curl -X POST "https://api.socq.ai/v1/tiktok/top-search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"coffee","sort_by":"relevance","results_limit":20}'

Enregistrez data.task_id sous le nom TASK_ID et interrogez cette tâche :

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Patientez entre deux vérifications tant que l’état est queued, running ou retrying. Avec succeeded, lisez data.results.items ; avec failed, examinez data.error_message. Si le résultat contient has_more=true, suivez next_cursor pour lire les pages enregistrées restantes.

Le curseur d’un résultat de tâche lit des enregistrements déjà sauvegardés. Le results_limit soumis fixe le plafond de collecte. Après un délai d’expiration côté client, reprenez l’interrogation avec l’ID de tâche existant.

Définir le tri, les filtres de publication et la région

ParamètreValeurs ou plage acceptéesSignification
queryMot-clé ou expression obligatoire et non videSujet à rechercher
sort_byrelevance, date, likesTri demandé pour les résultats ; la pertinence est la valeur par défaut
published_withinday, week, month, three_months, six_monthsFiltre facultatif sur la date de publication
regionCode à deux lettres, par exemple USDisponibilité du contenu pour la recherche
results_limitEntiers de 1 à 2 000 ; 100 par défautPlafond commun à tous les formats de contenu renvoyés

day sélectionne hier, week cette semaine et month ce mois-ci. Ces trois options utilisent des périodes calendaires. three_months et six_months sélectionnent respectivement les trois et les six derniers mois.

region modifie les contenus accessibles pour la recherche. Enregistrez region=US comme condition de la requête ; vérifiez la localisation du créateur à l’aide d’éléments géographiques distincts.

Par exemple, si 20 résultats comprennent huit carrousels photo, le filtrage par format produit huit publications photo. results_limit compte les deux formats ensemble, et le nombre de photos dépend de leur répartition dans cette capture.

Lire les résultats vidéo et carrousel photo

L’exemple suivant, avec une vidéo et un carrousel de cinq images, montre comment lire chaque format de résultat :

Champ observéEnregistrement vidéoEnregistrement carrousel photo
id76785360685509706387685189869970246926
typevideophoto_carousel
author.usernamepatrickmcgee62coffeewithcandace
duration_seconds5.247null
Éléments de médiaUne vidéoCinq images

Les enregistrements standard stockent les légendes dans text, les médias dans media, les informations sur le son dans audio et les nombres d’engagement dans metrics. Traitez les requêtes suivantes à partir des enregistrements renvoyés par leurs propres tâches.

Lisez les images du carrousel dans l’ordre où les médias sont renvoyés. Un duration_seconds null signifie qu’aucune durée n’a été fournie ; une métrique null signifie qu’aucune mesure n’a été fournie. Conservez les zéros renvoyés et gardez les nombres de lectures et de vues dans leurs champs respectifs.

Exporter les résultats de recherche et les images de carrousel avec Python

Enregistrez cet utilitaire de bibliothèque standard sous le nom socq_collect.py :

import json
import os
import time
from urllib.parse import urlencode
from urllib.request import Request, urlopen

BASE = "https://api.socq.ai/v1"
PENDING = {"queued", "running", "retrying"}

def api(method, path, payload=None):
    body = json.dumps(payload).encode("utf-8") if payload is not None else None
    request = Request(
        BASE + path, data=body, method=method,
        headers={
            "Authorization": "Bearer " + os.environ["SOCQ_API_KEY"],
            "Content-Type": "application/json",
        },
    )
    with urlopen(request, timeout=60) as response:
        result = json.load(response)
    if result.get("code") != 200:
        raise RuntimeError(result)
    return result["data"]

def collect(endpoint, payload):
    task_id = api("POST", "/" + endpoint, payload)["task_id"]
    print("Task:", task_id, flush=True)
    path = "/tasks/" + task_id
    deadline = time.monotonic() + 600
    data = api("GET", path + "?limit=100")
    while data["status"] in PENDING:
        if time.monotonic() >= deadline:
            raise TimeoutError("Resume GET " + path + "; do not resubmit automatically")
        time.sleep(2)
        data = api("GET", path + "?limit=100")
    if data["status"] != "succeeded":
        raise RuntimeError(data.get("error_message") or data["status"])

    items, seen_cursors = [], set()
    while True:
        if time.monotonic() >= deadline:
            raise TimeoutError("Resume pagination for " + task_id)
        page = data["results"]
        items.extend(page["items"])
        if not page["has_more"]:
            return task_id, items
        cursor = page.get("next_cursor")
        if not cursor or cursor in seen_cursors:
            raise RuntimeError("Missing or repeated result cursor")
        seen_cursors.add(cursor)
        data = api("GET", path + "?" + urlencode({"limit": 100, "cursor": cursor}))
        if data["status"] != "succeeded":
            raise RuntimeError("Task is not ready for result pagination")

Enregistrez ce qui suit sous le nom export_search.py dans le même répertoire :

import csv
import json
from socq_collect import collect

payload = {"query": "coffee", "sort_by": "relevance", "results_limit": 20}
task_id, records = collect("tiktok/top-search", payload)
with open("tiktok-search.json", "w", encoding="utf-8") as f:
    json.dump({"task_id": task_id, "input": payload, "items": records},
              f, ensure_ascii=False, indent=2)

def csv_cell(value):
    if value is None:
        return ""
    if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
        return "'" + value
    return value

def write_csv(path, fields, rows):
    with open(path, "w", encoding="utf-8-sig", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=fields)
        writer.writeheader()
        writer.writerows({k: csv_cell(v) for k, v in row.items()} for row in rows)

posts, images, seen_ids = [], [], set()
for item in records:
    post_id = item.get("id")
    if post_id is not None:
        if str(post_id) in seen_ids:
            continue
        seen_ids.add(str(post_id))
    metrics = item.get("metrics") or {}
    posts.append({"post_id": post_id, "type": item.get("type"),
                  "text": item.get("text"), "url": item.get("url"),
                  "username": (item.get("author") or {}).get("username"),
                  "published_at": item.get("published_at"),
                  "likes_count": metrics.get("likes_count"),
                  "views_count": metrics.get("views_count"),
                  "collected_at": item.get("collected_at")})
    if item.get("type") == "photo_carousel":
        for position, media in enumerate(item.get("media") or [], start=1):
            if media.get("type") == "image":
                images.append({"post_id": post_id, "media_position": position,
                               "image_url": media.get("url"),
                               "width": media.get("width"), "height": media.get("height")})

write_csv("tiktok-search.csv", ["post_id", "type", "text", "url", "username",
          "published_at", "likes_count", "views_count", "collected_at"], posts)
write_csv("tiktok-carousel-images.csv", ["post_id", "media_position", "image_url",
          "width", "height"], images)
python3 export_search.py

Le JSON conserve tous les enregistrements collectés. Le CSV des publications dédoublonne les publications par ID, tandis que le CSV des images enregistre les ID de publication et les positions des médias pour reconstituer l’ordre des carrousels. Les enregistrements sans ID sont conservés à part ; confirmez leurs publications sources avant de les rapprocher d’autres jeux de données.

Gardez à la fois les URL des publications et celles des médias pour ouvrir la publication source et accéder à ses médias. Conservez les valeurs vides pour les adresses d’image manquantes. Le CSV échappe les textes publics qui ressemblent à des formules ; importez les ID de publication comme texte pour conserver tous les chiffres.

Transformer les publications collectées en analyse thématique

Pour une analyse sur les recettes de café, classez les publications collectées en fiches d’images ou en démonstrations vidéo. Lisez à la fois les légendes et les médias pour attribuer les thèmes. Extraire l’intégralité du texte affiché dans les images demande une étape distincte de reconnaissance de texte.

Gardez la requête, les filtres et l’heure de capture avec chaque comparaison. Étiquetez un tri local par mentions “J’aime” comme « classement par mentions “J’aime” au sein de cet échantillon », et indiquez la taille de l’échantillon et le périmètre de collecte à côté.

Pour une découverte axée sur l’audio, consultez le tutoriel sur les classements musicaux TikTok. Pour les workflows de profils, de vidéos connues et de commentaires, utilisez le guide de scraping TikTok.

Constituer un jeu de données de recherche unique pour les vidéos et les images

SocQ Top Search utilise un seul workflow de requête pour les vidéos et les carrousels photo, avec des champs standard pour identifier chaque format. Le code d’export crée à la fois un tableau de publications et un tableau d’images ordonné, ce qui donne à votre bibliothèque de thèmes ou à votre interface d’analyse les liens sources et les positions des diapositives dont elle a besoin.

Ouvrir Top Search et essayer votre mot-clé.

FAQ

L’API TikTok Search peut-elle renvoyer des carrousels photo ?

Top Search renvoie des vidéos et des carrousels photo, distingués par type, avec les médias dans media. L’endpoint TikTok Search distinct est réservé à la recherche de vidéos.

Puis-je rechercher uniquement des photos TikTok ?

Collectez les résultats, puis sélectionnez type=photo_carousel. Le filtrage des photos se fait dans votre application ; le plafond de collecte compte les deux formats.

Top Search renvoie-t-il les mots-clés les plus recherchés ou des volumes de recherche ?

Top Search prend votre mot-clé et renvoie des enregistrements de publications. Les volumes de recherche par mot-clé et les listes de requêtes en tendance sont des types de données distincts et ne figurent pas dans cette réponse.

La région indique-t-elle où vit le créateur ?

region ajuste la disponibilité du contenu pour la recherche. Vérifiez séparément la résidence du créateur ou le lieu de la publication.

Puis-je obtenir toutes les publications correspondant à un mot-clé ?

L’endpoint renvoie les publications sélectionnées par cette recherche, jusqu’à results_limit. Lire toutes les pages de résultats permet de récupérer l’ensemble des résultats enregistrés de la tâche ; sa couverture thématique est définie par ces enregistrements.

Pourquoi une publication photo n’a-t-elle ni durée ni nombre de lectures ?

Lisez les carrousels photo comme des éléments d’image. Conservez null pour une durée ou une mesure de lecture manquante, et conservez 0 lorsque la source renvoie zéro.

Puis-je publier un carrousel avec cette API ?

Top Search récupère du contenu public existant. La publication de carrousels passe par un autre workflow de publication. Consultez la page de l’API Top Search pour les entrées, les champs et la facturation de cet endpoint.

TIKTOK API

Tester le workflow avec une URL publique TikTok

Envoyez des entrées publiques et recevez des enregistrements normalisés, avec un contexte de source traçable.

Découvrir les API TikTok