Исследуйте видео и фотокарусели TikTok вместе с помощью SocQ. Собирайте подписи, авторов, ссылки на медиа и показатели вовлеченности по одному ключевому слову, а затем сводите видеодемонстрации, карточки рецептов и инструкции в картинках в один тематический датасет.
SocQ TikTok Top Search API ищет публичные видео и фотокарусели по ключевому слову. В этом руководстве разобраны запрос, обработка форматов результатов и экспорт публикаций и упорядоченных ссылок на изображения.
Коротко: отправьте обязательный
queryвPOST /v1/tiktok/top-search. После успешного завершения задачи читайтеdata.results.items.type=videoобозначает видео,type=photo_carousel— публикации с изображениями; изображения карусели находятся вmedia.
Выберите эндпоинт поиска под формат контента
| Отправная точка | Эндпоинт SocQ | Охват результатов |
|---|---|---|
| Ключевое слово, только видео | TikTok Search | Сценарий поиска видео |
| Ключевое слово, видео и публикации с изображениями | TikTok Top Search | Смешанные результаты, различающиеся по type |
| Известный URL публикации | TikTok Videos | Получение указанного контента |
| Известный ID звука | TikTok Song Videos | Поиск видео, связанных с этим звуком |
Top Search возвращает существующие публикации по ключевому слову. Чтобы работать с фотопубликациями, отберите из результатов type=photo_carousel и читайте изображения в media.
Поиск в TikTok по ключевому слову
Задайте SOCQ_API_KEY и отправьте поиск с ограничением в 20 записей:
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}'
Сохраните data.task_id как TASK_ID и запросите эту задачу:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Пока статус равен queued, running или retrying, делайте паузы между проверками. При succeeded читайте data.results.items; при failed изучите data.error_message. Если в результате has_more=true, переходите по next_cursor, чтобы прочитать оставшиеся сохраненные страницы.
Курсор результатов задачи читает сохраненные записи. Отправленный results_limit задает верхнюю границу сбора. После тайм-аута клиента продолжайте запрашивать существующий ID задачи.
Сортировка, фильтры по дате публикации и регион
| Параметр | Допустимые значения или диапазон | Значение |
|---|---|---|
query | Обязательное непустое ключевое слово или фраза | Тема поиска |
sort_by | relevance, date, likes | Запрашиваемый порядок результатов; по умолчанию — релевантность |
published_within | day, week, month, three_months, six_months | Необязательный фильтр по времени публикации |
region | Двухбуквенный код, например US | Доступность контента для поиска |
results_limit | Целые числа от 1 до 2 000; по умолчанию 100 | Общее ограничение для всех возвращаемых форматов контента |
day выбирает вчерашний день, week — текущую неделю, month — текущий месяц. Эти три варианта используют календарные периоды. three_months и six_months выбирают последние три и шесть месяцев соответственно.
region меняет то, какой контент доступен для поиска. Сохраняйте region=US как условие запроса; местоположение автора проверяйте по отдельным географическим данным.
Например, если среди 20 результатов восемь фотокаруселей, фильтрация по формату даст восемь фотопубликаций. results_limit учитывает оба формата вместе, а число фотопубликаций зависит от их распределения в конкретном снимке.
Чтение результатов: видео и фотокарусели
Примеры видео и карусели из пяти изображений ниже показывают, как читать каждый формат результатов:
| Наблюдаемое поле | Запись видео | Запись фотокарусели |
|---|---|---|
id | 7678536068550970638 | 7685189869970246926 |
type | video | photo_carousel |
author.username | patrickmcgee62 | coffeewithcandace |
duration_seconds | 5.247 | null |
| Элементы медиа | Одно видео | Пять изображений |
Стандартные записи хранят подписи в text, медиа — в media, сведения о звуке — в audio, показатели вовлеченности — в metrics. Последующие запросы обрабатывайте по записям, которые вернули их собственные задачи.
Читайте изображения карусели в том порядке, в котором вернулись медиа. duration_seconds, равное null, означает, что длительность не передана; метрика, равная null, — что измерение не передано. Сохраняйте возвращенные нули и держите число воспроизведений и число просмотров в соответствующих полях.
Экспорт результатов поиска и изображений каруселей на Python
Сохраните этот вспомогательный модуль на стандартной библиотеке как 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")
Сохраните следующий скрипт как export_search.py в том же каталоге:
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
JSON сохраняет все собранные записи. CSV публикаций убирает дубликаты по ID, а CSV изображений сохраняет ID публикаций и позиции медиа, чтобы можно было восстановить порядок карусели. Записи без ID сохраняются отдельно; прежде чем объединять их с другими датасетами, проверьте, из каких публикаций они взяты.
Храните и URL публикаций, и URL медиа, чтобы открывать исходную публикацию и получать ее медиа. Для отсутствующих адресов изображений сохраняйте пустые значения. CSV экранирует публичный текст, похожий на формулы; импортируйте ID публикаций как текст, чтобы сохранить все цифры.
Превратите собранные публикации в тематический обзор
Для обзора рецептов кофе разделите собранные публикации на карточки с изображениями и видеодемонстрации. При распределении по темам читайте и подписи, и медиа. Чтобы извлечь весь текст, показанный на изображениях, нужен отдельный шаг распознавания текста.
Храните запрос, фильтры и время снимка вместе с каждым сравнением. Локальную сортировку по лайкам помечайте как «рейтинг по лайкам внутри этой выборки» и указывайте рядом размер выборки и охват сбора.
Для поиска контента через звуки смотрите руководство по музыкальным чартам TikTok. Для сценариев с профилями, известными видео и комментариями используйте руководство по парсингу TikTok.
Один исследовательский датасет для видео и изображений
SocQ Top Search использует один сценарий запросов для видео и фотокаруселей, а стандартные поля позволяют определить формат каждой записи. Код экспорта создает и таблицу публикаций, и упорядоченную таблицу изображений, давая вашей тематической библиотеке или интерфейсу проверки нужные ссылки на источник и позиции слайдов.
Открыть Top Search и попробовать свое ключевое слово.
Часто задаваемые вопросы
Может ли TikTok Search API возвращать фотокарусели?
Top Search возвращает видео и фотокарусели, различающиеся по type, с медиа в media. Отдельный эндпоинт TikTok Search предназначен для поиска видео.
Можно ли искать в TikTok только фото?
Соберите результаты, затем отберите type=photo_carousel. Фильтрация фото происходит в вашем приложении; ограничение сбора учитывает оба формата.
Возвращает ли Top Search популярные поисковые запросы или их частотность?
Top Search принимает ваше ключевое слово и возвращает записи публикаций. Частотность ключевых слов и списки трендовых запросов — отдельные типы данных, они не входят в этот ответ.
Определяет ли регион, где живет автор?
region регулирует доступность контента для поиска. Место жительства автора или место публикации проверяйте отдельно.
Можно ли получить все публикации, соответствующие ключевому слову?
Эндпоинт возвращает публикации, отобранные этим поиском, в пределах results_limit. Чтение всех страниц результатов дает полный сохраненный набор результатов задачи; его тематический охват определяется этими записями.
Почему у фотопубликации нет длительности или числа воспроизведений?
Читайте фотокарусели как набор изображений. Для отсутствующей длительности или числа воспроизведений сохраняйте null, а если источник вернул ноль — сохраняйте 0.
Можно ли опубликовать карусель через этот API?
Top Search получает существующий публичный контент. Для публикации каруселей используется отдельный сценарий публикации. Входные данные, поля и тарификацию этого эндпоинта смотрите на странице Top Search API.
TIKTOK API
Проверить сценарий на публичном URL TikTok
Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.
API для TikTok