← データ API

TikTok · 広告検索

ベータ

ソーシャルプラットフォームの公開データを呼び出しごとの課金で取得できます。API キーと残高はモデル呼び出しと共通です。

未払いアカウントは1日50回まで。有料アカウントに1日の呼び出し上限はありません。毎日00:00 UTCにリセットされます。 · HTTP 200 で data が空でない場合にのみ 1 回分を課金します。結果が空の場合、パラメータが拒否された場合、上流が失敗した場合は課金されません。

リクエストパラメータ

パラメータはプラットフォーム自身の名前でクエリ文字列に入れます。例はカタログから取ったものです。識別子は取得したいコンテンツのものに置き換えてください。

名前タイプ必須サンプル説明
objectiveintegerいいえ—Ad objective (optional): 1 traffic, 2 app installs, 3 conversions, 4 video views, 5 reach, 6 leads, 7 product sales
likeintegerいいえ—Performance percentile (optional): 1 top 1-20%, 2 top 21-40%, 3 top 41-60%, 4 top 61-80%, 5 top 81-100%
periodintegerいいえ180Time period (days)
デフォルト 180
industrystringいいえ—Industry ID
keywordstringいいえ"美食"Search keyword
pageintegerいいえ1Page number
デフォルト 1
limitintegerいいえ20Items per page
デフォルト 20
order_bystringいいえ"for_you"Sort by (for_you, likes)
デフォルト "for_you"
country_codestringいいえ"US"Country code
デフォルト "US"
ad_formatintegerいいえ—Ad format (optional; 1:Spark Ads 2:Non-Spark Ads)
ad_languagestringいいえ—Ad language (optional)
durationintegerいいえ—Video duration filter value (optional)
pattern_labelstringいいえ—Creative pattern label (optional)
search_idstringいいえ—Search ID (optional)

リクエスト例

curl --get "https://api.chinaapi.ai/v1/social/tiktok/ad-search" \
  -H "Authorization: Bearer $CHINAAPI_KEY"

レスポンスの形

成功したレスポンスは、プラットフォームのデータを小さなエンベロープで包んで返します。data の中身（フィールド名、ページネーションカーソル、ID）はすべてプラットフォーム自身のものです。カーソルは受け取ったとおりにそのまま渡し返してください。

{
  "object": "social.result",
  "platform": "tiktok",
  "capability": "ad-search",
  "data": { … }
}

ページング

ページング用パラメータ：page, search_id。1 ページ取得するごとに別の課金対象の呼び出しになります。カーソル値は前回のレスポンスからそのまま渡してください。

エラーと課金されないケース

ステータスコードエラーコード意味
400—パラメータが不明、重複、長すぎる、型が違う、または欠けている場合です。「いずれか 1 つ以上」のグループから 1 つも指定されていない場合も含みます。どれに当たるかはエラーの code（unknown_parameter や missing_parameter など）でわかります。
403—この API キーには、このリクエストを実行する権限がありません。
404social_data_no_resultそのプラットフォームと機能の組み合わせが存在しないか、プラットフォームがこのパラメータで何も見つけられませんでした（social_data_no_result）。
429data_api_daily_limit_exceededsocial_data_capacity_reachedベータの当日分の容量を使い切ったか（00:00 UTC にリセット）、プラットフォームが混雑しています。後者なら数秒後の再試行で通ります。間隔を空けずに再試行を繰り返さないでください。 未払いアカウントは1日50回まで。有料アカウントに1日の呼び出し上限はありません。毎日00:00 UTCにリセットされます。
502social_data_no_resultデータソースが応答しなかったか、データなしで応答しました。
503social_data_unavailableこのエンドポイントは現在一時停止中で、ライブカタログでは paused と表示されます。

これらのレスポンスはいずれも課金されません。

すべてのレスポンスに X-Oneapi-Request-Id ヘッダーが付きます。サポートへの問い合わせ時に添えていただければ、その呼び出しを特定できます。

ベータ版の条件

未払いアカウントは1日50回まで。有料アカウントに1日の呼び出し上限はありません。毎日00:00 UTCにリセットされます。 ベータ版には SLA がなく、対応プラットフォーム、エンドポイント、料金は変更される場合があります。

各プラットフォームの規約と、あなたに適用されるデータ保護規則に従ってください。この API を個人のプロファイリングに使わないでください。ログイン、連絡先情報の抽出、エンゲージメントの操作、非公開または有料コンテンツへのアクセスは、このベータの対象外です。

データ API のレート特典

データ API のレート特典

有料アカウントは毎秒 10 リクエストから開始し、累計純利用額に応じて毎秒 100 リクエストまで自動的に増加します。

未払いアカウントは1日50回まで。有料アカウントに1日の呼び出し上限はありません。毎日00:00 UTCにリセットされます。

累計純利用額毎秒のリクエスト数
有料アカウントの初期値10/s
50 米ドル超20/s
500 米ドル超50/s
1500 米ドル超100/s

集計対象はデータ API の精算済み料金から呼び出しの返金を差し引いた額です。チャージ額とモデル API の利用額は含みません。

同じアカウントのすべての API キーでこのレートを共有します。同時実行数ではなく、毎秒のリクエスト数です。

供給元の各エンドポイントには別の容量制限があり、実際に利用できるスループットにも影響します。

より高いレートが必要な場合は、[email protected] までメールでお問い合わせください。