> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# オーディエンスターゲティングAPI

> APIキーを使って、サーバーからオーディエンスターゲティング、ターゲティングオプション、オプションの条件を取得する方法をご案内します。

オーディエンスターゲティングAPIを使うと、プロジェクトのオーディエンスターゲティングとターゲティングオプションを取得できます。[広告商品API](https://docs.adrop.io/ja/integrations/ad-products.md)の`targetings`に入れるターゲティングIDとオプションIDを調べたり、オプションに設定したプロパティ・イベントの条件を確認したりするときに使います。

> [!NOTE]
>
> このAPIでできるのは取得のみです。オーディエンスターゲティングを作成・更新するには、コンソールを使ってください。[オーディエンスターゲティングの作成](https://docs.adrop.io/ja/targeting/audience.md)を参照してください。コンテキストターゲティングは[コンテキストターゲティングAPI](https://docs.adrop.io/ja/integrations/context-targeting/overview.md)で扱います。

***

## 事前準備

* `audience-targeting:read`スコープを持つAPIキーが必要です。このスコープは、コンソールの **\[設定]** > **\[連携]** メニューでは選択できません。Adropにご依頼いただければ、スコープを含むキーを発行します。[広告商品API](https://docs.adrop.io/ja/integrations/ad-products.md)のスコープも、同じキーにあわせて含めることができます。

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

***

## 基本情報

| 項目 | 値 |
| - | - |
| Base URL | `https://lake.adrop.io` |
| 認証 | `x-api-key`ヘッダーにAPIキーを指定します。キーが属するプロジェクトのターゲティングのみ取得できます。ほかのプロジェクトのIDは`404`を返します。 |
| リクエスト本文 | すべてのリクエストが取得（`GET`）のため、本文を含めないでください。本文があると、サイズに関係なく`413`を返します。 |
| IDの形式 | 英数字、`_`、`-`からなる64文字以内の文字列です。 |
| 時刻 | `createdAt`、`updatedAt`、`segmentedAt`はエポックミリ秒です。ISO 8601の文字列を使うコンテキストターゲティングAPIとは形式が異なります。 |
| 同時リクエスト | プロジェクトごとに4件まで同時に処理します。同じプロジェクトのキーを複数使っても合算します。超えると`429`を返します。 |

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

***

## 用語

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

| API | コンソールでの名称 | 説明 |
| - | - | - |
| `targeting` | ターゲティング | 「年齢層」などのオーディエンスターゲティングです。このAPIで扱えるのはオーディエンスターゲティングのみです。 |
| `category` | ターゲティングオプション（オプション） | 「20代」など、ターゲティングに含まれるオプションです。 |
| `type: "collection"` | オプショングループ | 下位オプションをまとめたオプションです。通常のオプションは`type: "atomic"`です。 |
| `children`、`parent` | 下位オプション | オプショングループに含まれるオプションです。オプショングループの`children`には下位オプションの一覧が、下位オプションの`parent`には所属するオプショングループが入っています。 |
| `users` | オーディエンスサイズ | プロジェクトのユーザーのうち、このオプションに該当するユーザーの数です。 |
| `conditions` | 条件 | オプションに設定したプロパティ・イベントの条件です。 |

***

## エンドポイント

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

| メソッド | パス | 説明 |
| - | - | - |
| `GET` | `/audience-targeting` | [ターゲティング一覧の取得](#ターゲティング一覧の取得) |
| `GET` | `/audience-targeting/{targetingId}` | [ターゲティングの取得](#ターゲティングの取得) |
| `GET` | `/audience-targeting/{targetingId}/categories` | [オプション一覧の取得](#オプション一覧の取得)（ページ単位） |
| `GET` | `/audience-targeting/category/{categoryId}` | [オプションの取得](#オプションの取得)（条件を含む） |

***

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

| フィールド | 型 | 説明 |
| - | - | - |
| `_id` | string | ターゲティングID。広告商品の`targetings[].targeting`に使います。 |
| `name` | string | ターゲティング名 |
| `categoryCount` | number | 下位オプションを含むオプションの数。削除されたオプションが含まれることがあるため、[オプション一覧の取得](#オプション一覧の取得)で読み込んだ数と異なる場合があります。 |
| `segmentedAt` | number | このターゲティングのオーディエンスを最後に計算した時刻。まだ計算していない場合は省略されます。 |
| `createdAt` | number | ターゲティングを作成した時刻 |
| `updatedAt` | number | ターゲティングを最後に更新した時刻 |

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

***

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

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

### リクエスト

```http theme={null}
GET /audience-targeting
```

### リクエスト例

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting" \
  -H "x-api-key: YOUR_API_KEY"
```

### レスポンス例

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

```json theme={null}
[
  {
    "_id": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
    "name": "Users",
    "categoryCount": 12,
    "segmentedAt": 1790820300000,
    "createdAt": 1790820300000,
    "updatedAt": 1790820300000
  }
]
```

***

## ターゲティングの取得

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

### リクエスト

```http theme={null}
GET /audience-targeting/{targetingId}
```

### リクエスト例

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting/01JAZ3K9Q8W5T2M4N6P7R8S9TV" \
  -H "x-api-key: YOUR_API_KEY"
```

### レスポンス

`200`で[ターゲティングオブジェクト](#ターゲティングオブジェクト)を返します。

### エラー

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

***

## オプションオブジェクト

| フィールド | 型 | 説明 |
| - | - | - |
| `_id` | string | オプションID。広告商品の`targetings[].policies`のキーに使います。 |
| `name` | string | オプション名 |
| `type` | string | `atomic`（通常のオプション）または`collection`（オプショングループ） |
| `parent` | string | 所属するオプショングループのID。下位オプションにのみあります。 |
| `children` | string\[] | 先頭50個の下位オプションのID。オプショングループにのみあります。 |
| `childCount` | number | 下位オプションの総数。オプショングループにのみあります。`children`より多い場合、残りは[オプション一覧の取得](#オプション一覧の取得)の`parent`で読み込みます。 |
| `users` | number | オーディエンスサイズ。オプション一覧の取得のレスポンスにのみあります。 |
| `operable` | boolean | 条件で使っているプロパティが現在のプロパティの設定（フィールド・タイプ・演算子）と合っているかどうか。[条件を読み取れない場合](#条件を読み取れない場合)を参照してください。 |
| `createdAt` | number | オプションを作成した時刻 |
| `updatedAt` | number | オプションを最後に更新した時刻 |

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

***

## オプション一覧の取得

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

### リクエスト

```http theme={null}
GET /audience-targeting/{targetingId}/categories
```

### クエリパラメーター

| パラメーター | 型 | 必須 | デフォルト値 | 説明 |
| - | - | :-: | - | - |
| `limit` | number | - | `100` | 1回で受け取るオプションの数（1〜1,000） |
| `next` | string | - | - | 次のページのカーソル。前のレスポンスの`next`をそのまま入れます。最初のページでは省略します。 |
| `parent` | string | - | - | オプショングループID。指定すると、そのオプショングループの下位オプションをグループ内の順に返します。 |

### リクエスト例

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting/01JAZ3K9Q8W5T2M4N6P7R8S9TV/categories?limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

### レスポンス例

`200`で、`items`（[オプションオブジェクト](#オプションオブジェクト)の一覧）と`next`（次のページのカーソル）を返します。`next`がなければ最後のページです。

```json theme={null}
{
  "items": [
    {
      "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K",
      "name": "Korea",
      "type": "atomic",
      "users": 1200,
      "operable": true,
      "createdAt": 1790820300000,
      "updatedAt": 1790820300000
    },
    {
      "_id": "01JAZ3KC3D4E5F6G7H8J9K0M1N",
      "name": "Asia",
      "type": "collection",
      "users": 5000,
      "operable": true,
      "children": ["01JAZ3KB2C3D4E5F6G7H8J9K0M", "01JAZ3KE5F6G7H8J9K0M1N2P3Q"],
      "childCount": 2,
      "createdAt": 1790820300000,
      "updatedAt": 1790820300000
    }
  ],
  "next": "01JAZ3KC3D4E5F6G7H8J9K0M1N"
}
```

* オプション一覧には条件が含まれません。条件は[オプションの取得](#オプションの取得)で読み込みます。
* `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つのオプションを条件と一緒に返します。

### リクエスト

```http theme={null}
GET /audience-targeting/category/{categoryId}
```

### リクエスト例

```bash theme={null}
curl "https://lake.adrop.io/audience-targeting/category/01JAZ3KA1B2C3D4E5F6G7H8J9K" \
  -H "x-api-key: YOUR_API_KEY"
```

### レスポンス例

`200`で、[オプションオブジェクト](#オプションオブジェクト)に次のフィールドを加えて返します。`users`は含まれません。

| フィールド | 型 | 説明 |
| - | - | - |
| `targeting` | string | オプションが属するターゲティングのID |
| `convertible` | boolean | 条件を`conditions`で表せるかどうか |
| `conditions` | object | オプションの条件。`convertible`が`true`の場合にのみあります。[条件](#条件)を参照してください。 |

```json theme={null}
{
  "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K",
  "name": "Korean adults",
  "type": "atomic",
  "operable": true,
  "targeting": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
  "convertible": true,
  "conditions": {
    "all": [
      { "field": "country", "op": "is", "values": ["KR"] },
      { "field": "age", "op": "greater_than_or_equals", "values": [20] }
    ]
  },
  "createdAt": 1790820300000,
  "updatedAt": 1790820300000
}
```

取得できるのは、このプロジェクトのオーディエンスターゲティングに属するオプションのみです。

### エラー

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

***

## 条件

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

### ノード

| ノード | 意味 |
| - | - |
| `{ "all": [...] }` | 中の条件をすべて満たす |
| `{ "any": [...] }` | 中の条件のうち1つ以上を満たす |
| プロパティ条件、イベント条件 | 以下で説明 |

* 最も外側は常に`all`または`any`です。条件が1つだけの場合は`{ "all": [条件] }`です。
* 同じ種類のノードを重ねて使うことはありません。たとえば、`all`のすぐ内側に`all`が来ることはありません。

たとえば次の条件は、「（国がKRまたはJPで、`level`が10以上で、直近30日以内に`item_category`が`book`の購入を1回以上したユーザー）または（性別がFのユーザー）」を表します。

```json theme={null}
{
  "any": [
    {
      "all": [
        { "field": "country", "op": "is", "values": ["KR", "JP"] },
        { "field": "custom.level", "op": "greater_than_or_equals", "values": [10] },
        {
          "event": "purchase",
          "action": "did",
          "measure": "total_events",
          "op": "greater_than_or_equals",
          "value": 1,
          "where": [{ "param": "item_category", "op": "is", "values": ["book"] }],
          "recency": "30D"
        }
      ]
    },
    { "field": "gender", "op": "is", "values": ["F"] }
  ]
}
```

### プロパティ条件

```json theme={null}
{ "field": "country", "op": "is", "values": ["KR"] }
```

| フィールド | 説明 |
| - | - |
| `field` | プロパティ。デフォルトプロパティは`country`、`language`、`gender`、`age`、`consent`で、カスタムプロパティは`custom.<プロパティ名>`です。[プロパティ](https://docs.adrop.io/ja/targeting/property.md)を参照してください。 |
| `op` | 演算子。下の表を参照してください。 |
| `values` | 比較する値。個数は演算子によって異なります。`is`と`is_not`は複数、`between`と`not_between`は`[最小値, 最大値]`の2つ、`is_true`と`is_false`は`[]`、それ以外は1つです。 |
| `match` | 値が配列のカスタムプロパティにのみあります。`any`の場合は配列の要素のいずれか1つが、`all`の場合はすべての要素が条件を満たす必要があります。 |

| プロパティのタイプ | 演算子 |
| - | - |
| 文字列 | `is`（いずれかの値と等しい）、`is_not`（どの値とも異なる。値がないユーザーも含む）、`contains`、`does_not_contains`、`starts_with`、`ends_with` |
| 数値 | `is`、`is_not`、`equals`、`not_equals`、`greater_than`、`greater_than_or_equals`、`less_than`、`less_than_or_equals`、`between`、`not_between` |
| ブール値 | `is_true`、`is_false` |
| 日付 | `last`（直近の期間以内）、`before_the_last`、`next`、`after_the_next`（値は`30D`、`2W`、`1M`などの期間）、`before`、`after`（値は日付の文字列） |

### イベント条件

```json theme={null}
{ "event": "purchase", "action": "did", "measure": "total_events", "op": "greater_than_or_equals", "value": 1, "recency": "30D" }
```

| フィールド | 説明 |
| - | - |
| `event` | イベント名：`app_open`、`sign_up`、`push_clicks`、`page_view`、`click`、`view_item`、`add_to_wishlist`、`add_to_cart`、`begin_checkout`、`purchase`、`view_content`、`begin_lead_form`、`generate_lead`。[イベント](https://docs.adrop.io/ja/targeting/event.md)を参照してください。 |
| `action` | `did`の場合は、期間内にイベントを実行し、集計値が`op`と`value`を満たしたユーザーです。`did_not_do`の場合は、期間内にイベントを実行していないユーザーで、`measure`、`op`、`value`はありません。 |
| `measure` | 集計方法。`"total_events"`（イベント数）、または`{ "type": "sum", "param": "price" }`のような、イベントパラメータの値の`sum`（合計）、`average`（平均）、`minimum`（最小値）、`maximum`（最大値）、`distinct_count`（ユニーク数）です。 |
| `op` | `equals`、`not_equals`、`greater_than`、`greater_than_or_equals`、`less_than`、`less_than_or_equals` |
| `value` | 比較する数値 |
| `where` | イベントパラメータの条件の一覧`[{ "param", "op", "values" }]`。すべてを満たす必要があります。 |
| `recency` | 期間。数字と単位`H`（時間）、`D`（日）、`W`（週）、`M`（月）で表します（例：`30D`）。この期間内のイベントだけを対象にします。 |

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

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

オプショングループには独自の条件がなく、下位オプションの条件のいずれかを満たすと含まれます。そのため、オプショングループの`conditions`は、下位オプションの条件を`any`でまとめたものです。

* 下位オプションの条件が`any`で始まる場合は、その中の条件が外側の`any`に直接入るため、分岐の数が下位オプションの数と異なることがあります。
* 下位オプションが1つだけの場合は、`any`で囲まず、その下位オプションの条件をそのまま返します。
* 条件のない下位オプションはスキップします。

### 条件を読み取れない場合

| フィールド | 意味 | `false`の場合 |
| - | - | - |
| `convertible` | 保存された条件を、広告配信と同じ意味のツリーで表せるかどうか | `conditions`がありません。条件を解釈せず、コンソールで確認してください。 |
| `operable` | 条件で使っているプロパティが現在のプロパティの設定と合っているかどうか | 条件で使っているプロパティが削除されたか、タイプが変わったため、現在の設定では運用できません。オプショングループは、下位オプションのうち1つでも合っていなければ`false`です。 |

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

***

## エラー処理

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

| ステータス | `errorCode` | 原因 |
| - | - | - |
| `400` | `VALIDATION_FAILED` | IDや`next`、`parent`の形式が誤っているか、`limit`が範囲外であるか、不明なクエリパラメーターを送りました。 |
| `400` | `TARGETING_CATEGORY_NOT_SUPPORTED` | `parent`がオプショングループではなく、通常のオプションです。 |
| `401` | - | APIキーがない、誤っている、または廃棄されています。 |
| `403` | - | `audience-targeting:read`スコープがありません。 |
| `404` | `TARGETING_NOT_FOUND` | ターゲティングが存在しないか、ほかのプロジェクトのターゲティングか、コンテキストターゲティングです。 |
| `404` | `TARGETING_CATEGORY_NOT_FOUND` | オプションが存在しないか、ほかのプロジェクトのオプションか、オーディエンスターゲティングのオプションではありません。オプション一覧の取得では、`next`や`parent`がこのターゲティングのオプションでない場合にも返します。 |
| `413` | - | 取得リクエストに本文を含めました。 |
| `429` | `TOO_MANY_CONCURRENT_REQUESTS` | 同時リクエストの上限を超えたか、サーバーが混雑しています。`Retry-After`ヘッダーの秒数だけ待ってから再送信してください。 |
| `502` | - | サーバー内部の通信に問題があります。 |

***

## 上限

| 項目 | 上限 |
| - | - |
| オプション一覧のページサイズ | 1〜1,000件（デフォルトは100） |
| オプショングループの`children` | 先頭50個。残りは`parent`で取得 |
| 同時リクエスト | プロジェクトあたり4件 |
| レスポンスの受信 | 30秒以内にレスポンスを受け取りきれないと、サーバーが接続を切断します。下位オプションが多いオプショングループは、レスポンスが大きくなることがあります。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.