tiktok/
top-search

Ищите видео и фотокарусели TikTok по ключевому слову и получайте подписи, данные об авторах, ссылки на медиа и счетчики взаимодействий вместе в одном JSON-списке.

TikTok Top Search API

Видео и фотокарусели
Поиск по ключевым словам
Сортировка и фильтры по дате публикации
0,7 кредита за результат
Готово
Готово

Введите параметры и отправьте запрос. Здесь появятся статус задачи и нормализованные результаты.

README

Автор: SocQ · Обновлено

TikTok Top Search

Поиск Top в TikTok объединяет видео и фотокарусели, то есть публикации из нескольких изображений, найденные по ключевому слову или фразе. Подписи, данные об авторах, медиа и счетчики взаимодействий помогают сравнить, как одна и та же тема представлена в этих разных форматах контента.

Возможности TikTok Top Search API

  • Видео и публикации с изображениями в одном поискеОдин и тот же запрос по ключевому слову может вернуть видео и фотокарусели; поле type указывает формат, поэтому их можно хранить в одном датасете или разделять для анализа.
  • Выбор сортировки и периода публикацииСортируйте найденный контент по релевантности, дате публикации или лайкам и добавляйте фильтр по времени публикации, чтобы сосредоточить выборку на нужном вам контенте.
  • Контент вместе с автором и счетчикамиКаждый результат объединяет подпись, данные об авторе, ссылки на медиа и доступные счетчики взаимодействий, поэтому тему и формат публикации можно связать с опубликовавшим ее аккаунтом.

Параметры TikTok Top Search API

ПараметрыОбязательныйОписание
queryОбязательныйОбязательное ключевое слово или фраза, описывающие то, что вы хотите найти, например coffee или home workout; вводите поисковый текст, а не URL публикации TikTok.
sort_byНеобязательныйНеобязательный порядок: relevance ставит первыми наиболее релевантные совпадения, date сортирует по дате публикации, а likes — по числу лайков; по умолчанию relevance.
published_withinНеобязательныйНеобязательный период публикации: day выбирает вчерашний день, week — эту неделю, month — этот месяц, three_months — последние три месяца, six_months — последние шесть месяцев; оставьте пустым, чтобы не применять дополнительный фильтр по времени публикации.
regionНеобязательныйНеобязательный двухбуквенный код региона, например US или GB, который меняет доступный для поиска контент; он не доказывает, что возвращенные публикации или авторы находятся в этой стране.
results_limitНеобязательныйНеобязательное максимальное число записей контента — от 1 до 2 000, по умолчанию 100; и видео, и фотокарусели учитываются в этом лимите, а результатов может вернуться меньше.

Как использовать TikTok Top Search API

Запрос запускает фоновую задачу сбора, поэтому первый ответ содержит ID задачи, а не готовые данные; используйте этот ID, чтобы проверять ход выполнения и получать результаты.

  1. Введите ключевое слово темы, выберите наиболее полезную сортировку — relevance, date или likes — и задайте лимит результатов; период публикации или регион добавляйте, только если они нужны.
  2. Перед запуском примера замените $SOCQ_API_KEY своим API-ключом или задайте эту переменную окружения. Отправьте JSON на POST /v1/tiktok/top-search с заголовком Authorization, как показано ниже, и сохраните task_id из ответа.
  3. Проверяйте ход выполнения через GET /v1/tasks/{task_id} с сохраненным ID. queued означает ожидание, running — сбор идет, retrying — выполняется повторная попытка. Дождитесь succeeded, прежде чем читать результаты; если задача в статусе failed, причину смотрите в error_message.
  4. После успешного завершения читайте data.results.items: каждый элемент этого списка описывает одно видео или одну фотокарусель. Пустой список означает, что задача завершилась, не вернув записей.
  5. Если data.results.has_more равно true, значение next_cursor — это маркер следующей страницы сохраненных результатов. Скопируйте его без изменений в параметр cursor запроса GET /v1/tasks/{task_id}?cursor=... и продолжайте, пока has_more не станет false.
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}'

Сценарии использования TikTok Top Search API

  • Подборка контента по теме: Ищите по теме, например coffee, и сохраняйте подписи, хендлы авторов, ссылки и типы контента в таблицу для анализа с примерами и видео, и публикаций с изображениями.
  • Сравнение счетчиков взаимодействий у найденных публикаций: Сопоставляйте доступные лайки, комментарии и пересылки с форматом и временем публикации, чтобы подготовить таблицу для сравнения, и сохраняйте запрос и фильтры, чтобы знать, как были отобраны примеры.

Практические советы по TikTok Top Search API

  • При показе результата сначала проверяйте type и media: photo_carousel означает публикацию с изображениями, для нее нужна галерея изображений, а не видеоплеер.
  • При сборе по нескольким ключевым словам удаляйте повторяющиеся совпадения по ID публикации и сохраняйте ключевое слово для каждого сбора, чтобы одна и та же публикация случайно не была учтена несколько раз.
  • Если ваш процесс принимает только видео, используйте TikTok Search; если нужны и видео, и публикации с изображениями, оставьте Top Search и обрабатывайте оба формата при показе.
  • Если у фоторезультата нет длительности или числа воспроизведений, оставляйте это значение пустым, а не трактуйте его как видео длиной ноль секунд или непросмотренную публикацию.

Помимо TikTok Top Search API, используйте эти API, когда нужен другой тип публичных данных TikTok.

  • TikTok Profiles API — Получайте по имени пользователя публичные данные профиля, описание, признаки аккаунта и счетчики аудитории.
  • TikTok Hashtags API — Собирайте публичные видео, авторов, медиа, звук и вовлеченность по заданным хештегам.
  • TikTok Comments API — Собирайте публичные комментарии верхнего уровня, авторов, вовлеченность, упоминания и признаки взаимодействия с автором видео.
  • TikTok Videos API — Получайте по URL видео автора, подпись, медиа, музыку, теги, упоминания и вовлеченность.
  • TikTok Search API — Ищите публичные видео по ключевому слову с поддерживаемой сортировкой и фильтрами по дате публикации.
  • TikTok Live Room Info API — Получайте данные об одном известном прямом эфире по паре ID эфира и владельца: статус, контекст владельца, обложка и число зрителей.

Другие платформы

Объединяйте данные TikTok с публичными данными других поддерживаемых соцсетей.

TikTok Top Search API — FAQ

TikTok Top Search API — это программный интерфейс для поиска публичных видео и фотокаруселей TikTok по ключевому слову или фразе. Он возвращает подписи, данные об авторах, ссылки на медиа и счетчики взаимодействий с необязательной сортировкой и фильтрами по времени публикации.

Это публикация TikTok из нескольких изображений, которые зритель может пролистывать. В результатах этот формат обозначается type=photo_carousel, а media содержит элементы изображений.

TikTok Search возвращает только видео, а Top Search может включать и видео, и фотокарусели. Выбирайте в зависимости от того, должны ли ваш сбор или интерфейс обрабатывать также публикации с изображениями.

Входного фильтра только для фото нет. После получения выберите записи, у которых type равен photo_carousel; лимит результатов применяется до вашей фильтрации по формату, поэтому фотокаруселей может остаться меньше.

Нет. region меняет доступность контента для поиска, а не географическое происхождение каждого результата; не используйте его вместо поля местоположения автора или публикации.

Нет. results_limit ограничивает возвращаемую выборку, но не гарантирует, что в нее попадут все подходящие публикации TikTok. Поиск может вернуть меньше записей, чем запрошено.

Каждая возвращенная запись контента стоит 0,7 кредита, будь то видео или фотокарусель. Базовой платы нет; для лимита 100 оценка составляет 70 кредитов, а 20 возвращенных записей стоят 14 кредитов.