Соберите шорт-лист песен TikTok с помощью SocQ. Сведите вместе позиции чартов, ID звуков, исполнителей и число видео с этими звуками, а затем свяжите каждый звук с его деталями и примерами видео, чтобы получить контент-бриф с опорой на источники.
SocQ TikTok Popular Songs API читает чарты Top 50 и Viral 50 из приложения TikTok. В этом руководстве разобраны выбор чарта, запросы, экспорт в JSON и CSV и поиск видео по ID звука.
Коротко: отправьте
chart_type=topилиchart_type=viralвPOST /v1/tiktok/popular-songs. Сохраните возвращенный ID задачи, дождитесь успешного завершения и читайтеdata.results.items. По умолчанию выбран Top 50 с лимитом 20;results_limitпринимает целые числа от 1 до 50.
Выберите Top 50 или Viral 50
| Входные данные | Выбранный чарт | Когда использовать |
|---|---|---|
chart_type: "top" | Top 50 в приложении TikTok | Собрать список по этому именованному чарту |
chart_type: "viral" | Viral 50 в приложении TikTok | Собрать список Viral 50 или сравнить его ID звуков с Top 50 |
Не указывать chart_type | Top 50 | Использовать чарт по умолчанию |
Если собираете оба чарта, сохраняйте chart_type вместе с каждой записью. Когда звук есть в обоих списках, храните оба наблюдения и сопоставляйте звук между ними по audio.id.
chart_type выбирает чарт, а results_limit задает верхнюю границу сбора. Viral 50 — название чарта в приложении TikTok. Фильтры по стране и дате, а также показатели роста рассмотрены в FAQ ниже.
Запрос чарта песен
Задайте SOCQ_API_KEY в переменной окружения и отправьте запрос:
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}'
Замените top на viral, чтобы выбрать Viral 50. Задайте results_limit равным 50, чтобы собрать до 50 позиций из чарта; поле задачи result_count показывает фактическое число сохраненных записей.
Ответ на отправку содержит data.task_id. Присвойте это значение TASK_ID, затем запросите существующую задачу:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Ждите, пока статус равен queued, running или retrying. После succeeded читайте data.results.items; после failed изучите data.error_message. Если запрос клиента завершился по тайм-ауту, сохраните ID задачи, чтобы продолжить опрос.
results_limit задает верхнюю границу сбора. При получении результатов задачи limit задает размер страницы, а cursor указывает следующую сохраненную страницу. Верхняя граница сбора песен — 50 позиций.
Определите звук, стоящий за каждой песней
Этот пример записи песни показывает ID звука, название, исполнителя, число видео со звуком и время сбора:
{
"id": "6711980022204205826",
"type": "music",
"name": "we fell in love in october",
"audio": {
"id": "6711980022204205826",
"title": "we fell in love in october",
"artist": "girl in red"
},
"duration_seconds": 42,
"metrics": {"videos_count": 2031150},
"collected_at": "2026-10-15T08:12:54.524359Z"
}
Для последующих вызовов используйте audio.id. Храните его как строку и импортируйте как текст в табличных редакторах, чтобы сохранить все цифры. Сопоставление по ID звука различает разные звуки с одинаковым названием.
metrics.videos_count — переданное источником общее число видео с этим звуком. Null означает, что источник не передал показатель; 0 — возвращенное нулевое значение. Чтобы сравнить два снимка, сопоставьте ID звуков и вычислите разницу между значениями.
cover_url содержит адрес обложки, а audio.url — адрес аудио. Если audio.url равно null, упорядочивайте список по ID звука, названию и исполнителю. При обращении к медиа проверяйте ответ по URL аудио.
Экспорт списка звуков в JSON и CSV на Python
Сохраните вспомогательный модуль для задач ниже как socq_collect.py. Он использует стандартную библиотеку Python, выводит ID задачи и читает все сохраненные страницы результатов:
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_songs.py в том же каталоге:
import csv
import json
import sys
from socq_collect import collect
chart = sys.argv[1] if len(sys.argv) > 1 else "top"
if chart not in {"top", "viral"}:
raise SystemExit("Usage: python3 export_songs.py [top|viral]")
payload = {"chart_type": chart, "results_limit": 20}
task_id, items = collect("tiktok/popular-songs", payload)
with open(f"songs-{chart}.json", "w", encoding="utf-8") as f:
json.dump({"task_id": task_id, "input": payload, "items": items},
f, ensure_ascii=False, indent=2)
fields = ["chart_type", "sound_id", "title", "artist", "videos_count",
"duration_seconds", "url", "collected_at"]
def csv_cell(value):
if value is None:
return ""
if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
return "'" + value
return value
with open(f"songs-{chart}.csv", "w", encoding="utf-8-sig", newline="") as f:
writer = csv.DictWriter(f, fieldnames=fields)
writer.writeheader()
for item in items:
audio = item.get("audio") or {}
row = {"chart_type": chart, "sound_id": audio.get("id"),
"title": item.get("name"), "artist": audio.get("artist"),
"videos_count": (item.get("metrics") or {}).get("videos_count"),
"duration_seconds": item.get("duration_seconds"),
"url": item.get("url"), "collected_at": item.get("collected_at")}
writer.writerow({k: csv_cell(v) for k, v in row.items()})
python3 export_songs.py top
python3 export_songs.py viral
Каждая команда создает отдельную задачу сбора. JSON хранит исходные записи и запрос; CSV — таблица для просмотра. Публичный текст, похожий на формулы, экранируется в CSV, а в JSON сохраняются исходные значения. Импортируйте ID звуков в табличные редакторы как текст.
Сохраняйте выгрузки по дате снимка. Сравнение metrics.videos_count одного и того же звука дает разницу между двумя наблюдениями. Звук, которого нет в более позднем чарте, помечайте как «не наблюдался в этом снимке»; чтобы выяснить, не удален ли он, проверьте этот звук отдельно.
Найдите видео, в которых используется возвращенный звук
Выберите звук из выгрузки и передайте его audio.id в TikTok Song Videos:
curl -X POST "https://api.socq.ai/v1/tiktok/song-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"music_ids":["6711980022204205826"],"results_limit":20}'
Так создается отдельная задача сбора видео со своим results_limit. Для деталей звука используйте TikTok Song, а для исследования темы по видео и публикациям с изображениями — руководство по поиску в TikTok.
Для контент-брифа храните вместе ID звука, тип чарта, время снимка, URL источника и примеры видео, чтобы проверяющий мог сверить каждый пункт.
Используйте чарты в исследовании музыки
SocQ связывает получение чартов, детали звуков и поиск связанных видео в рамках одного сценария задач. Используйте код экспорта, чтобы упорядочить исследование по чарту и времени снимка, а затем добавьте к каждому звуку примеры видео. Ваш следующий шорт-лист начнется с записей, которые можно проверить и использовать повторно.
Открыть Popular Songs API и собрать шорт-лист.
Часто задаваемые вопросы
Это API трендовых звуков TikTok?
Да. Его охват — чарты Top 50 и Viral 50 в приложении TikTok. Выберите чарт через chart_type и упорядочивайте возвращенные звуки по ID.
Можно ли выбрать страну или диапазон дат?
Сбор организован по типу чарта. Поддерживаемые входные данные — chart_type, results_limit и необязательный callback_url для уведомления о завершении задачи. Фильтров по стране, дате, новым позициям и коммерческой музыке нет.
Можно ли получить больше 50 песен с помощью пагинации?
Каждая задача собирает до 50 позиций. Пагинация результатов читает песни, уже сохраненные этой задачей.
Есть ли в Viral 50 показатель роста или изменение позиции?
Стандартная запись содержит сведения о звуке и число видео с ним; показатели роста и изменения позиций не входят. Чтобы сравнивать наблюдения, сохраняйте повторные снимки и вычисляйте разницу по ID звука.
Обозначает ли ID звука все записи одной и той же песни?
ID звука обозначает один звук TikTok. Сохраняйте отдельные фрагменты или версии под их собственными ID, даже если у них одинаковое название песни.
Можно ли скачать каждую песню или отфильтровать музыку, одобренную для бизнеса?
Если у audio.url есть значение, попробуйте получить аудио по этому адресу. Если оно равно null, сохраните ID звука для запроса деталей. Возможность коммерческого использования нужно проверять отдельно; этот эндпоинт не дает ни поля одобрения, ни соответствующего фильтра.
Как получить видео, в которых используется одна из песен?
Отправьте возвращенный audio.id в массиве music_ids в TikTok Song Videos. Это отдельная задача со своим лимитом сбора и тарификацией. Актуальные входные данные и тарификацию смотрите на странице Popular Songs API.
TIKTOK API
Проверить сценарий на публичном URL TikTok
Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.
API для TikTok