SocQで、TikTokの楽曲候補リストを作りましょう。チャートのエントリ、サウンドID、アーティスト、動画の使用回数をまとめ、各サウンドを詳細情報やサンプル動画と結びつければ、出典に裏づけられたコンテンツブリーフを作成できます。
SocQ TikTok Popular Songs APIは、TikTokアプリのTop 50とViral 50のチャートを読み取ります。このガイドでは、チャートの選び方、リクエスト、JSONとCSVへのエクスポート、サウンドIDによる動画の検索を扱います。
結論(クイックアンサー):
chart_type=topまたはchart_type=viralをPOST /v1/tiktok/popular-songsに送信します。返されたタスクIDを保存し、成功するまで待って、data.results.itemsを読み取ります。デフォルトは上限20件のTop 50で、results_limitには1〜50の整数を指定できます。
Top 50とViral 50を選ぶ
| 入力 | 選択されるチャート | 使いどころ |
|---|---|---|
chart_type: "top" | TikTokアプリのTop 50 | この名前付きのチャートからリストを作る |
chart_type: "viral" | TikTokアプリのViral 50 | 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は、0件という値が返されたことを意味します。取得時点どうしを比較するには、サウンドIDを照合して、2つのカウントの差を計算します。
cover_urlにはカバーのアドレス、audio.urlにはオーディオのアドレスが入ります。audio.urlがnullの場合は、サウンドID、タイトル、アーティストを使ってリストを整理してください。メディアにアクセスするときは、オーディオURLからのレスポンスを確認してください。
PythonでサウンドリストをJSONとCSVにエクスポートする
次のタスク用ヘルパーを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を比べると、2回の観測の差が分かります。後のチャートに載っていないサウンドは「このキャプチャでは観測されなかった」とラベル付けしてください。削除されたかどうかを調べるには、個々のサウンドを別途確認します。
返されたサウンドを使っている動画を探す
エクスポートからサウンドを1つ選び、その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を開いて、候補リストを作成する。
よくある質問(FAQ)
これはTikTokのトレンドサウンドAPIですか?
はい。対象は、TikTokアプリのTop 50とViral 50のチャートです。chart_typeでチャートを選択し、返されたサウンドをIDで整理します。
国や期間を指定できますか?
収集はチャートの種類ごとに行われます。サポートされている入力は、chart_type、results_limit、任意のタスク完了通知用のcallback_urlです。国、日付、新規エントリ、商用利用可能な音楽のフィルターは提供されていません。
ページネーションで50曲より多く取得できますか?
各タスクが収集するのは最大50件のエントリです。結果のページネーションは、そのタスクがすでに保存した楽曲を読み取ります。
Viral 50には、伸び率のスコアや順位の変動が含まれますか?
標準のレコードが提供するのは、サウンドの情報と動画の使用回数で、伸び率のスコアや順位の変動は含まれません。観測を比較する場合は、繰り返し取得したデータを保存し、サウンドIDごとに差を計算してください。
サウンドIDは、同じ曲のすべての録音を識別しますか?
サウンドIDが識別するのは、1つのTikTokサウンドです。曲のタイトルが同じでも、別のクリップやバージョンは、それぞれのIDで保存してください。
すべての曲をダウンロードしたり、ビジネスで使用が承認された音楽に絞り込んだりできますか?
audio.urlに値がある場合は、そのアドレスでオーディオにアクセスしてみてください。nullの場合は、詳細を照会するためにサウンドIDを保持しておきます。商用利用の可否は別途確認が必要で、このエンドポイントには、承認を示すフィールドも対応するフィルターもありません。
楽曲のいずれかを使っている動画はどう取得しますか?
返されたaudio.idをmusic_ids配列に入れて、TikTok Song Videosに送信します。独自の収集上限と課金を持つ、別のタスクです。現在の入力と課金の詳細は、Popular Songs APIのページで確認してください。