Skip to main content
オーディエンスターゲティングAPIを使うと、プロジェクトのオーディエンスターゲティングとターゲティングオプションを取得できます。広告商品APIのtargetingsに入れるターゲティングIDとオプションIDを調べたり、オプションに設定したプロパティ・イベントの条件を確認したりするときに使います。
このAPIでできるのは取得のみです。オーディエンスターゲティングを作成・更新するには、コンソールを使ってください。オーディエンスターゲティングの作成を参照してください。コンテキストターゲティングはコンテキストターゲティングAPIで扱います。

事前準備

  • audience-targeting:readスコープを持つAPIキーが必要です。このスコープは、コンソールの [設定] > [連携] メニューでは選択できません。Adropにご依頼いただければ、スコープを含むキーを発行します。広告商品APIのスコープも、同じキーにあわせて含めることができます。
APIはサーバーからのみ呼び出してください。APIキーをアプリやウェブページに含めないでください。

基本情報

429を受け取ったら、Retry-Afterヘッダーの秒数だけ待ってから再送信してください。サーバーが混雑しているときは、リクエストを1件ずつ送っても429を受け取ることがあります。

用語

APIのパスやフィールドには、コンソールと異なる名前が使われているものがあります。本ドキュメントではコンソールの名称を使います。

エンドポイント

パスはBase URLを基準とします。すべてのエンドポイントにaudience-targeting:readスコープが必要です。

ターゲティングオブジェクト

ターゲティングオブジェクトにはオプションが含まれません。オプションはオプション一覧の取得で読み込みます。

ターゲティング一覧の取得

プロジェクトのすべてのオーディエンスターゲティングを、コンソールに表示される順に、ページに分けずに一度に返します。コンテキストターゲティングは含まれません。

リクエスト

リクエスト例

レスポンス例

200で、ターゲティングオブジェクトの配列を返します。

ターゲティングの取得

1つのターゲティングを返します。

リクエスト

リクエスト例

レスポンス

200でターゲティングオブジェクトを返します。

エラー

  • 404 TARGETING_NOT_FOUND: ターゲティングが存在しないか、ほかのプロジェクトのターゲティングか、コンテキストターゲティングです。

オプションオブジェクト

オプションの取得は、これにtargeting(所属するターゲティングのID)、convertible、conditionsを加えて返します。

オプション一覧の取得

ターゲティングの最上位オプションを、コンソールに表示される順に、ページ単位で返します。オプショングループの下位オプションは、parentで別途読み込みます。

リクエスト

クエリパラメーター

リクエスト例

レスポンス例

200で、items(オプションオブジェクトの一覧)とnext(次のページのカーソル)を返します。nextがなければ最後のページです。
  • オプション一覧には条件が含まれません。条件はオプションの取得で読み込みます。
  • usersが0の場合は、ユーザー統計がまだ蓄積されていないか、統計を一時的に読み込めなかった可能性があります。0だけでオプションを判断せず、疑わしい場合は少し時間をおいてから取得し直してください。
  • ページを読み込んでいる途中でオプションが追加・削除・移動されると、結果が実際と異なることがあります。nextに指定したオプションがその間に削除または移動されると404 TARGETING_CATEGORY_NOT_FOUNDを返すため、最初のページから読み込み直してください。

エラー

  • 400 TARGETING_CATEGORY_NOT_SUPPORTED: parentがオプショングループではなく、通常のオプションです。
  • 404 TARGETING_NOT_FOUND: ターゲティングが存在しないか、ほかのプロジェクトのターゲティングか、コンテキストターゲティングです。
  • 404 TARGETING_CATEGORY_NOT_FOUND: nextがこのターゲティングの最上位オプションではない(削除・移動された)か、parentがこのターゲティングのオプションではありません。

オプションの取得

1つのオプションを条件と一緒に返します。

リクエスト

リクエスト例

レスポンス例

200で、オプションオブジェクトに次のフィールドを加えて返します。usersは含まれません。
取得できるのは、このプロジェクトのオーディエンスターゲティングに属するオプションのみです。

エラー

  • 404 TARGETING_CATEGORY_NOT_FOUND: オプションが存在しないか、ほかのプロジェクトのオプションか、オーディエンスターゲティングに属するオプションではありません。

条件

conditionsは、オプションの条件をall(かつ)とany(または)でまとめたツリーです。広告配信で実際に使われる条件と同じ意味で表します。

ノード

  • 最も外側は常にallまたはanyです。条件が1つだけの場合は{ "all": [条件] }です。
  • 同じ種類のノードを重ねて使うことはありません。たとえば、allのすぐ内側にallが来ることはありません。
たとえば次の条件は、「(国がKRまたはJPで、levelが10以上で、直近30日以内にitem_categoryがbookの購入を1回以上したユーザー)または(性別がFのユーザー)」を表します。

プロパティ条件

イベント条件

コンソールでイベント条件を複数つなげると、広告配信では決められたルールで結合されるため、コンソールで or でつないだ条件が、ツリーではallとして表示されることがあります。ツリーのallとanyにそのまま従ってください。

オプショングループの条件

オプショングループには独自の条件がなく、下位オプションの条件のいずれかを満たすと含まれます。そのため、オプショングループのconditionsは、下位オプションの条件をanyでまとめたものです。
  • 下位オプションの条件がanyで始まる場合は、その中の条件が外側のanyに直接入るため、分岐の数が下位オプションの数と異なることがあります。
  • 下位オプションが1つだけの場合は、anyで囲まず、その下位オプションの条件をそのまま返します。
  • 条件のない下位オプションはスキップします。

条件を読み取れない場合

2つの値は互いに関係ありません。convertibleがtrueで、operableがfalseの場合もあります。

エラー処理

エラーレスポンスにはstatusCodeが含まれ、下の表でerrorCodeの欄が-ではないエラーにはerrorCodeも含まれます。処理はerrorCodeで分け、errorCodeがない場合はstatusCodeで分けてください。リクエスト形式のエラー(VALIDATION_FAILED)では、誤っている箇所をdetail.errors[]のpathで知らせます。

上限