コンテキストターゲティングAPI

コンテキストターゲティングAPIを使うと、コンテキストターゲティングをサーバーから管理できます。CMSのセクション、掲示板、タグをターゲティングオプションとコンテキストIDに対応付けておけば、コンソールで手作業で編集しなくても、コンテンツの変化に合わせて自動で更新できます。 APIは、コンソールのコンテキストターゲティングと同じデータを扱います。APIで作成したターゲティングはコンソールに表示され、コンソールで作成したターゲティングもAPIで取得できます。

事前準備

context-targeting:readとcontext-targeting:writeの両方のスコープを持つAPIキーが必要です。プロジェクトのオーナーがコンソールの [設定] > [連携] でキーを作成し、両方のスコープを選択します。キーの作成方法は連携 & APIキーを参照してください。
既存のキーのスコープは変更できません。今のキーに両方のスコープがない場合は新しいキーを作成し、不要になった古いキーは廃棄してください。

書き込みが中心の場合でも、両方のスコープを付与してください。各エンドポイントが確認するスコープは1つだけで、context-targeting:writeにはcontext-targeting:readが含まれません。書き込みスコープしかないキーはすべてのGETリクエストで403を受け取るため、IDの確認、現在のコンテキストIDの取得、変更が読み込まれたかの確認ができません。

APIはサーバーからのみ呼び出してください。APIキーをアプリやウェブページに含めないでください。

基本情報

項目	値
Base URL	`https://lake.adrop.io`
認証	`x-api-key`ヘッダーにAPIキーを指定します。プロジェクトはキーで決まるため、パスにプロジェクトIDは含まれません。
Content-Type	`application/json`
リクエストボディの最大サイズ	8 MB。これより大きいリクエストには`413`が返されます。
ID形式	サーバーが発行する26文字のULID（例：`01JAB3XK5Q8V7M2N4P6R9T0W1Y`）。有効なULIDでないIDには`400`が返されます。
書き込みの処理	APIは、プロジェクトごとに書き込みを1件ずつ処理します。別の書き込みの処理中に送った書き込みは`409 CONTEXT_TARGETING_WRITE_IN_PROGRESS`で失敗することがあるため、書き込みは並列ではなく1件ずつ順番に送ってください。読み取りには影響しません。同時書き込みを参照してください。

リクエストに関する上限の一覧は、上限を参照してください。

用語

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

API	コンソールでの名称	説明
`targeting`	ターゲティング	「News Sections」などのコンテキストターゲティング。APIで扱えるのはコンテキストターゲティングのみです。
`category`	ターゲティングオプション（オプション）	「Sports」など、ターゲティングに含まれるオプション。
`contexts`	コンテキストID	`sport`など、オプションに登録されたID。アプリやウェブサイトは、これを広告リクエストの`contextId`として送信します。
`type: "collection"`	オプショングループ	下位オプションをまとめるオプション。自身のコンテキストIDと下位オプションのコンテキストIDの両方に一致します。通常のオプションは`type: "atomic"`です。
`children`、`parent`	下位オプション	オプショングループに含まれるオプション。オプショングループの`children`には下位オプションが並び、下位オプションの`parent`はそのオプショングループです。
`exposeChildren`	下位オプションを広告主に表示	広告主がオプショングループの下位オプションを個別に選択できるかどうか。広告配信には影響しません。

エンドポイント

パスはBase URLからの相対パスです。各エンドポイントには、表に記載したスコープが必要です。

メソッド	パス	スコープ	説明
`GET`	`/context-targeting`	`context-targeting:read`	ターゲティング一覧の取得
`GET`	`/context-targeting/{targetingId}`	`context-targeting:read`	ターゲティングの取得（オプションを含む）
`POST`	`/context-targeting`	`context-targeting:write`	ターゲティングの作成（オプションも同時に作成可能）
`PATCH`	`/context-targeting/{targetingId}`	`context-targeting:write`	ターゲティング名の変更
`DELETE`	`/context-targeting/{targetingId}`	`context-targeting:write`	ターゲティングの削除（すべてのオプションも削除）
`POST`	`/context-targeting/bulk/create`	`context-targeting:write`	ターゲティングの一括作成（1リクエストあたり最大100件）
`POST`	`/context-targeting/bulk/update`	`context-targeting:write`	ターゲティング名の一括変更（1リクエストあたり最大100件）
`POST`	`/context-targeting/bulk/delete`	`context-targeting:write`	ターゲティングの一括削除（1リクエストあたり最大100件）
`GET`	`/context-targeting/{targetingId}/categories`	`context-targeting:read`	ターゲティングのオプション一覧の取得（ページ単位）
`GET`	`/context-targeting/category/{categoryId}`	`context-targeting:read`	オプションの取得（コンテキストIDを含む）
`POST`	`/context-targeting/{targetingId}/category`	`context-targeting:write`	ターゲティングへのオプションの追加
`PATCH`	`/context-targeting/category/{categoryId}`	`context-targeting:write`	オプションの更新（名前の変更、コンテキストIDの変更、移動、`exposeChildren`の設定）
`DELETE`	`/context-targeting/category/{categoryId}`	`context-targeting:write`	オプションの削除
`POST`	`/context-targeting/category/bulk/create`	`context-targeting:write`	オプションの一括追加（1リクエストあたり最大5,000件）
`POST`	`/context-targeting/category/bulk/update`	`context-targeting:write`	オプションの一括更新（1リクエストあたり最大5,000件）
`POST`	`/context-targeting/category/bulk/delete`	`context-targeting:write`	オプションの一括削除（1リクエストあたり最大5,000件）

一括操作のエンドポイントは、項目ごとに結果を返します。一括操作のレスポンスを参照してください。

クイックスタート

この例では、「News Sections」ターゲティングを作成し、1つのオプションのコンテキストIDを変更して、その変更が読み込まれたかを確認します。

ターゲティングとオプションの作成

ターゲティングとそのオプションを1回のリクエストで作成します。

curl -X POST https://lake.adrop.io/context-targeting \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "News Sections",
    "categories": [
      { "name": "Sports", "contexts": ["sport", "baseball", "soccer"] },
      { "name": "Tech", "contexts": ["tech", "ai", "mobile"] }
    ]
  }'

レスポンスは201で、作成されたターゲティングが返されます。ターゲティングと各オプションの_idを保存してください。後でターゲティングを変更するときに必要です。

{
  "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
  "name": "News Sections",
  "categories": [
    {
      "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
      "name": "Sports",
      "type": "atomic",
      "contextCount": 3,
      "createdAt": "2026-10-13T01:23:45.000Z",
      "updatedAt": "2026-10-13T01:23:45.000Z"
    },
    {
      "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9",
      "name": "Tech",
      "type": "atomic",
      "contextCount": 3,
      "createdAt": "2026-10-13T01:23:45.000Z",
      "updatedAt": "2026-10-13T01:23:45.000Z"
    }
  ],
  "categoryCount": 2,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:23:45.000Z"
}

作成は冪等ではありません。作成リクエストがタイムアウトした場合は、再送する前に再試行と重複リクエストを参照してください。

コンテキストIDの追加と削除

セクションが変わったら、オプションのコンテキストIDを更新します。addとremoveは、指定したIDだけを変更します。

curl -X PATCH https://lake.adrop.io/context-targeting/category/01JAB3XK5RA1B2C3D4E5F6G7H8 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contexts": {
      "add": ["basketball", "golf"],
      "remove": ["soccer"]
    }
  }'

レスポンスは200で、更新後のオプションが返されます。

{
  "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
  "name": "Sports",
  "type": "atomic",
  "contextCount": 4,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:30:00.000Z"
}

オプションのコンテキストIDをまとめて置き換える方法は、コンテキストIDの更新方法を参照してください。

変更が読み込まれたかを確認

ターゲティングを取得し、そのsyncedAtを更新が成功した時刻と比べます。

curl "https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y?includeCategories=false" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
  "name": "News Sections",
  "categoryCount": 2,
  "syncedAt": 1791855005000,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:30:06.000Z"
}

前のステップの更新は2026-10-13T01:30:00.000Z（1791855000000）に成功しています。syncedAtはそれより後なので変更は読み込まれており、その後数分以内に広告配信に反映されます。syncedAtがない場合やそれより前の場合は、少し待ってからターゲティングをもう一度取得してください。変更が反映されるタイミングを参照してください。

広告リクエストでコンテキストIDを送信

ユーザーが閲覧しているページのコンテキストIDを、広告リクエストのcontextIdとして送信します。変更が反映された後は、contextIdにbasketballを指定した広告リクエストが「Sports」オプションに一致します。広告リクエストでのコンテキストIDの仕組みは、コンテキストターゲティングの作成を参照してください。

変更が反映されるタイミング

書き込みが成功すると、変更はすぐに保存されます。その後、Adropがプロジェクトのコンテキストターゲティングを広告配信に読み込み、通常は数分以内に変更が広告配信に反映されます。変更が読み込まれたかどうかは、ターゲティングのsyncedAtフィールド（エポックミリ秒）で確認します。

syncedAtは、そのターゲティングの直近の読み込みが始まった時刻です。syncedAt以前に成功した変更は読み込み済みで、その後数分以内に広告配信に反映されます。
新しく作成したターゲティングにはsyncedAtが含まれません。コンテキストIDの変更（add、remove、set）、オプションの追加、オプションの移動や切り離しを行った後も含まれません。通常は次の読み込みが完了すると、再び含まれるようになります。
変更したときにすでに実行中だった読み込みによって、syncedAtがその読み込みの開始時刻、つまり変更より前の時刻になることがあります。その読み込みには変更が含まれていない可能性がありますが、その後の読み込みには含まれます。
名前の変更や削除では、syncedAtは消えません。

そのため、syncedAtがあるかどうかで判断しないでください。リクエストが成功した時刻を記録しておき、変更を含むターゲティングを取得します（例：ターゲティングの取得でincludeCategories=falseを指定）。syncedAtがその時刻と同じかそれより後であれば、変更は読み込まれています。syncedAtはAdropのサーバー時刻に基づくため、自社サーバーの時刻とずれがある可能性がある場合は、余裕を持って判断してください。

変更が反映されるまで、広告リクエストは変更前のコンテキストIDと照合されます。新しいコンテキストIDは、アプリやウェブサイトが広告リクエストで送信し始める前に追加してください。

ターゲティング

ターゲティングの一覧取得、作成、名前の変更、削除

ターゲティングオプション

オプションを追加し、コンテキストIDを最新の状態に保つ方法

オプショングループ

オプションを下位オプションとしてオプショングループにまとめる方法

エラーと上限

エラーコード、上限、再試行の方法

連携 & APIキー

APIキーの作成と管理

コンテキストターゲティングの作成

コンテキストターゲティングとコンテキストIDの仕組み

ターゲティングの販売

ターゲティングを広告商品に接続して広告主に販売する方法

​事前準備

​基本情報

​用語

​エンドポイント

​クイックスタート

​変更が反映されるタイミング

​関連ドキュメント

ターゲティング

ターゲティングオプション

オプショングループ

エラーと上限

連携 & APIキー

コンテキストターゲティングの作成

ターゲティングの販売

事前準備

基本情報

用語

エンドポイント

クイックスタート

変更が反映されるタイミング

関連ドキュメント