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, чтобы проверять ход выполнения и получать результаты.
- Введите ключевое слово темы, выберите наиболее полезную сортировку — relevance, date или likes — и задайте лимит результатов; период публикации или регион добавляйте, только если они нужны.
- Перед запуском примера замените $SOCQ_API_KEY своим API-ключом или задайте эту переменную окружения. Отправьте JSON на POST /v1/tiktok/top-search с заголовком Authorization, как показано ниже, и сохраните task_id из ответа.
- Проверяйте ход выполнения через GET /v1/tasks/{task_id} с сохраненным ID. queued означает ожидание, running — сбор идет, retrying — выполняется повторная попытка. Дождитесь succeeded, прежде чем читать результаты; если задача в статусе failed, причину смотрите в error_message.
- После успешного завершения читайте data.results.items: каждый элемент этого списка описывает одно видео или одну фотокарусель. Пустой список означает, что задача завершилась, не вернув записей.
- Если 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 и обрабатывайте оба формата при показе.
- Если у фоторезультата нет длительности или числа воспроизведений, оставляйте это значение пустым, а не трактуйте его как видео длиной ноль секунд или непросмотренную публикацию.
Связанные API
Помимо 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 Comment Replies API
- TikTok Followers List API
- TikTok Following List API
- TikTok User Videos API
- TikTok Trending Feed API
- TikTok Video Transcript API
- TikTok Search Users API
- TikTok Song API
- TikTok Song Videos API
- TikTok Popular Songs API
- TikTok User Live API
- TikTok Audience Demographics API
- TikTok Similar Accounts API
- TikTok Reposts API
- TikTok Playlists API
- TikTok Hashtag Views API
- TikTok Sound Search API
- TikTok Live Search API
- TikTok Photo Search API
- TikTok Trending Searches API
- TikTok Creator Search Insights API
- TikTok Live Ranking API
- TikTok Live Shopping API
- TikTok Fake Views Checker API
- TikTok Comment Keywords API