tiktok/
popular-songs

Получайте чарт песен TikTok Top 50 или Viral 50 с названиями треков, исполнителями, ID звуков и доступным числом видео, чтобы составить музыкальный список для отбора.

TikTok Popular Songs API

Top 50
Viral 50
ID звуков
0,5 кредита за результат
Готово
README

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

TikTok Popular Songs

Звук TikTok — это аудиодорожка, прикрепленная к публикации, а в приложении TikTok есть чарты песен Top 50 и Viral 50. Каждая возвращенная запись указывает конкретный звук с названием, исполнителем и ID звука, поэтому можно составить музыкальный список и связать каждую позицию с данными о звуке или с видео, в которых он используется.

Возможности TikTok Popular Songs API

  • Выбор одного из двух чартов песенУкажите chart_type: top для Top 50 или viral для Viral 50. Это два именованных чарта в приложении TikTok; выберите нужный и запросите до 50 позиций.
  • Точный звук за названием песниЧитайте вместе название, исполнителя, ID звука, обложку и длительность. ID звука помогает различать аудиофрагменты с одинаковым названием и позволяет найти конкретный звук через TikTok Song или TikTok Song Videos.
  • Доступное число использований звукаЕсли источник передает счетчик, metrics.videos_count показывает, сколько видео используют этот звук. Это число видео, а не слушателей, воспроизведений или лайков; недоступный счетчик остается null.

Параметры TikTok Popular Songs API

ПараметрыОбязательныйОписание
chart_typeНеобязательныйНеобязательный выбор чарта: top выбирает Top 50 приложения TikTok, viral — Viral 50. По умолчанию top. Например, замените значение в примере на viral, чтобы запросить другой чарт.
results_limitНеобязательныйНеобязательное максимальное число песен — целое число от 1 до 50, по умолчанию 20. Например, 10 запрашивает до десяти позиций из выбранного чарта. Источник может вернуть меньше, а пагинация результатов не расширяет этот лимит.

Как использовать TikTok Popular Songs API

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

  1. Выберите chart_type: top для Top 50 или viral для Viral 50. Если параметр не указан, используется top; results_limit по умолчанию равен 20 и принимает целое число от 1 до 50.
  2. Замените $SOCQ_API_KEY своим API-ключом или задайте эту переменную окружения. Отправьте JSON-запрос на POST /v1/tiktok/popular-songs с заголовком Authorization и сохраните возвращенный task_id.
  3. Первый ответ содержит ID задачи, потому что сбор выполняется в фоне. Запрашивайте GET /v1/tasks/{task_id}; статусы queued, running и retrying означают, что задача еще выполняется. Читайте результаты после succeeded или проверьте error_message после failed.
  4. Читайте data.results.items. Каждый элемент описывает конкретный звук: audio.id — это ID звука, audio.artist — исполнитель, а metrics.videos_count — доступное число видео с этим звуком. Пустой массив items означает, что записи не вернулись.
  5. Если data.results.has_more равно true, передайте next_cursor без изменений как cursor в GET /v1/tasks/{task_id}?cursor=... и продолжайте, пока has_more не станет false. Так читается следующая страница той же сохраненной задачи; лимит сбора чарта при этом не превышает 50.
curl -X POST "https://api.socq.ai/v1/tiktok/popular-songs" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chart_type":"top","results_limit":20}'

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

  • Подготовка таблицы для отбора музыки: Выберите Top 50 или Viral 50 и выгрузите в таблицу названия, исполнителей, ID звуков, длительность и доступное число видео. Ваша команда сможет открыть страницы звуков и решить, какие фрагменты подходят для идеи контента.
  • Сбор примеров видео с выбранным звуком: Передайте возвращенные ID звуков как music_ids в TikTok Song Videos, чтобы собрать публичные примеры видео. Изучите эти видео сами, чтобы понять, как используется фрагмент: этот эндпоинт чарта такой анализ не выполняет.
  • Сравнение отдельно собранных снимков чарта: При каждом запуске задачи сохраняйте выбранный chart_type, ID звуков, доступное число видео и collected_at. Объединяйте сохраненные таблицы по ID звука, чтобы сравнивать возвращенные песни и число использований во времени; сам сервис исторических позиций не предоставляет.

Практические советы по TikTok Popular Songs API

  • При сравнении сохраненных запусков используйте один и тот же chart_type. Переключение с top на viral меняет выбранный чарт, поэтому другой список песен сам по себе не говорит о росте или падении популярности.
  • Используйте audio.id, чтобы связывать записи между задачами и запрашивать TikTok Song или TikTok Song Videos. Одно лишь название не позволяет различить разные аудиофрагменты с одинаковым именем.
  • Если audio.url равен null, сохраняйте ID звука и URL публичной страницы звука для дальнейшего изучения. Если URL аудио передан, считайте его ссылкой на медиа, доступной на момент сбора, а не постоянным адресом для скачивания.

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

  • TikTok Videos API — Получайте по URL видео автора, подпись, медиа, музыку, теги, упоминания и вовлеченность.
  • TikTok User Videos API — Собирайте публичные видео из ленты профиля по имени пользователя: подписи, авторы, медиа, метки времени, вовлеченность и контекст исходного аккаунта.
  • TikTok Trending Feed API — Собирайте текущую публичную ленту видео для региона: автор, подпись, обложка, метка времени и видимая вовлеченность.
  • TikTok Video Transcript API — Извлекайте доступный текст расшифровки, язык, формат и контекст источника по URL публичных видео.
  • TikTok Song API — Получайте публичные метаданные звука по ID клипа или URL музыки.
  • TikTok Song Videos API — Собирайте публичные видео с заданными ID звуков.

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

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

TikTok Popular Songs API — FAQ

TikTok Popular Songs API — это программный интерфейс для чтения чарта песен Top 50 или Viral 50 из приложения TikTok. Выберите chart_type и лимит результатов, чтобы получить названия звуков, исполнителей, ID звуков, обложки, длительность и доступное число видео с этими звуками.

Они выбирают два именованных чарта приложения TikTok: top — это Top 50, а viral — Viral 50. Если chart_type не указан, используется top. Ответ не раскрывает формулу ранжирования и не содержит оценки роста.

Нет. Этот интерфейс принимает chart_type и results_limit, а также необязательный callback_url для уведомления о завершении задачи. Фильтров по стране, периоду чарта, новым позициям или коммерческой музыке нет.

Нет. results_limit находится в диапазоне от 1 до 50. Курсор результатов позволяет прочитать следующую страницу записей, уже сохраненных этой задачей, но не собирает дополнительные позиции чарта.

metrics.videos_count — это число видео, которые, по данным источника, используют звук. Оно не измеряет слушателей, просмотры или лайки. Значение null означает, что источник не передал это измерение, а ноль — это фактически возвращенное значение.

Возьмите audio.id из записи песни и передайте его в music_ids эндпоинта TikTok Song Videos. Чтобы получить данные об одном звуке, используйте этот ID с TikTok Song. Это отдельные запросы.

Нет. audio.url может быть null, даже если название, исполнитель и ID звука доступны. Если URL возвращен, по нему можно проверить доступное аудио; сервис не гарантирует, что ссылка останется доступной.

Каждая возвращенная запись песни стоит 0,5 кредита, базовой платы нет. Для лимита 20 оценка составляет 10 кредитов; если задача вернет 12 песен, итоговое списание составит 6 кредитов. Для лимита 50 оценка составляет 25 кредитов.