Analizza insieme video e caroselli di foto di TikTok con SocQ. Raccogli didascalie, creator, link ai media e conteggi di engagement attorno a una parola chiave, poi organizza dimostrazioni video, schede di ricette e guide illustrate nello stesso dataset tematico.
La TikTok Top Search API di SocQ cerca per parola chiave video e caroselli di foto pubblici. Questa guida tratta la richiesta, la gestione dei formati dei risultati e le esportazioni dei post e dei link ordinati alle immagini.
Risposta rapida: invia un
queryobbligatorio aPOST /v1/tiktok/top-search. Quando l’attività riesce, leggidata.results.items. Usatype=videoper i video etype=photo_carouselper i post con immagini; le immagini del carosello si trovano inmedia.
Scegli l’endpoint di ricerca per il tuo formato di contenuto
| Punto di partenza | Endpoint SocQ | Ambito dei risultati |
|---|---|---|
| Parola chiave, solo video | TikTok Search | Un flusso di ricerca di video |
| Parola chiave, video e post con immagini | TikTok Top Search | Risultati misti distinti da type |
| URL di un post noto | TikTok Videos | Recupera il contenuto specificato |
| ID di un suono noto | TikTok Song Videos | Trova i video associati a quel suono |
Top Search restituisce post esistenti per una parola chiave. Per lavorare con i post fotografici, seleziona type=photo_carousel dai risultati e leggi le immagini in media.
Cerca su TikTok per parola chiave
Imposta SOCQ_API_KEY e invia una ricerca limitata a 20 record:
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}'
Salva data.task_id come TASK_ID e interroga quell’attività:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Attendi tra un controllo e l’altro finché lo stato è queued, running o retrying. Con succeeded, leggi data.results.items; con failed, controlla data.error_message. Se il risultato ha has_more=true, segui next_cursor per leggere le pagine salvate rimanenti.
Il cursore di un risultato di attività legge i record salvati. Il valore results_limit inviato imposta il tetto di raccolta. Dopo un timeout del client, riprendi l’interrogazione dell’ID attività esistente.
Imposta ordinamento, filtri di pubblicazione e regione
| Parametro | Valori o intervallo accettati | Significato |
|---|---|---|
query | Parola chiave o frase obbligatoria non vuota | Argomento da cercare |
sort_by | relevance, date, likes | Ordinamento richiesto dei risultati; la pertinenza è il valore predefinito |
published_within | day, week, month, three_months, six_months | Filtro facoltativo sul periodo di pubblicazione |
region | Codice di due lettere, come US | Disponibilità dei contenuti per la ricerca |
results_limit | Numeri interi da 1 a 2000; predefinito 100 | Tetto complessivo sui formati di contenuto restituiti |
day seleziona ieri, week questa settimana e month questo mese. Queste tre opzioni usano periodi di calendario. three_months e six_months selezionano rispettivamente gli ultimi tre e sei mesi.
region cambia i contenuti accessibili per la ricerca. Salva region=US come condizione della richiesta; verifica la località del creator con prove geografiche separate.
Per esempio, se 20 risultati includono otto caroselli di foto, il filtro per formato produce otto post fotografici. results_limit conta insieme entrambi i formati e il numero di foto dipende dalla loro distribuzione in quella rilevazione.
Leggi i risultati di video e caroselli di foto
Gli esempi seguenti di un video e di un carosello di cinque immagini mostrano come leggere ciascun formato di risultato:
| Campo osservato | Record video | Record carosello di foto |
|---|---|---|
id | 7678536068550970638 | 7685189869970246926 |
type | video | photo_carousel |
author.username | patrickmcgee62 | coffeewithcandace |
duration_seconds | 5.247 | null |
| Voci multimediali | Un video | Cinque immagini |
I record standard memorizzano le didascalie in text, i media in media, le informazioni sul suono in audio e i conteggi di engagement in metrics. Elabora le query successive usando i record restituiti dalle rispettive attività.
Leggi le immagini del carosello nell’ordine dei media restituito. Un valore null di duration_seconds significa che non è stata fornita alcuna durata; una metrica null significa che non è stata fornita alcuna misurazione. Conserva gli zeri restituiti e tieni i conteggi delle riproduzioni e delle visualizzazioni nei rispettivi campi.
Esporta i risultati di ricerca e le immagini dei caroselli con Python
Salva questo helper basato sulla libreria standard come 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")
Salva quanto segue come export_search.py nella stessa directory:
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
Il JSON conserva tutti i record raccolti. Il CSV dei post elimina i duplicati per ID, mentre il CSV delle immagini salva gli ID dei post e le posizioni dei media per ricostruire l’ordine del carosello. I record senza ID vengono conservati separatamente; conferma i loro post di origine prima di unirli ad altri dataset.
Conserva sia gli URL dei post sia quelli dei media per aprire il post di origine e accedere ai suoi media. Mantieni vuoti i valori per gli indirizzi di immagine mancanti. Il CSV rende innocuo il testo pubblico simile a formule; importa gli ID dei post come testo per conservare ogni cifra.
Trasforma i post raccolti in una revisione tematica
Per una revisione sulle ricette di caffè, classifica i post raccolti come schede illustrate o dimostrazioni video. Leggi sia le didascalie sia i media quando assegni gli argomenti. Estrarre il testo completo mostrato all’interno delle immagini richiede un passaggio separato di riconoscimento del testo.
Conserva la query, i filtri e l’orario di rilevazione con ogni confronto. Etichetta un ordinamento locale per Mi piace come “classifica per Mi piace all’interno di questo campione” e indica la dimensione del campione e l’ambito di raccolta accanto ad essa.
Per la scoperta guidata dall’audio, consulta il tutorial sulle classifiche musicali di TikTok. Per i flussi su profili, video noti e commenti, usa la guida allo scraping di TikTok.
Crea un unico dataset di ricerca per video e immagini
SocQ Top Search usa un unico flusso di richiesta per video e caroselli di foto, con campi standard per identificare ciascun formato. Il codice di esportazione crea sia una tabella dei post sia una tabella ordinata delle immagini, offrendo alla tua libreria di argomenti o all’interfaccia di revisione i link alle fonti e le posizioni delle slide di cui ha bisogno.
Apri Top Search e prova la tua parola chiave.
Domande frequenti (FAQ)
La TikTok Search API può restituire caroselli di foto?
Top Search restituisce video e caroselli di foto, distinti da type, con i media in media. L’endpoint TikTok Search separato serve per la ricerca di video.
Posso cercare solo foto di TikTok?
Raccogli i risultati, poi seleziona type=photo_carousel. Il filtro per le foto avviene nella tua applicazione; il tetto di raccolta conta entrambi i formati.
Top Search restituisce le parole chiave più cercate o i volumi di ricerca?
Top Search prende la tua parola chiave e restituisce record di post. I volumi di ricerca delle parole chiave e gli elenchi delle query di tendenza sono tipi di dati separati e non sono inclusi in questa risposta.
La regione identifica dove vive il creator?
region regola la disponibilità dei contenuti per la ricerca. Verifica separatamente la residenza del creator o la località del post.
Posso ottenere ogni post che corrisponde a una parola chiave?
L’endpoint restituisce i post selezionati da quella ricerca, fino a results_limit. Leggere ogni pagina dei risultati recupera l’insieme completo dei risultati salvati dell’attività; la sua copertura tematica è definita da quei record.
Perché un post fotografico non ha durata né conteggio delle riproduzioni?
Leggi i caroselli di foto come voci di immagini. Conserva null per durata o riproduzioni mancanti e conserva 0 quando la fonte restituisce zero.
Posso pubblicare un carosello con questa API?
Top Search recupera contenuti pubblici esistenti. La pubblicazione dei caroselli usa un flusso di pubblicazione separato. Consulta la pagina della Top Search API per input, campi e fatturazione di questo endpoint.
TIKTOK API
Prova il flusso di lavoro con un URL pubblico di TikTok
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di TikTok