> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/ja/generating-ads/product-ads/requesting-product-ads-1.md).

# 商品広告のリクエスト

## 広告の要求

すべての商品広告リクエストには、コンテキストの `placement`、および `catalogId`、ならびに顧客に表示したい `maxNumberOfAds` 。さらに、リクエストにはコンテキストの `customerId` と `sessionId`.

### 検索配置

検索配置は通常、最も簡単にリクエストできます。以下の例のように、リクエスト内で `searchTerm` を指定する必要があります:

```http
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "options": {
   						 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}
```

### カテゴリー配置

カテゴリー配置では、リクエスト内で `productFilters` を指定する必要があります。以下の例は、カテゴリーフィルターを送信する場所を示しています:

```http
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}
```

追加のカテゴリーが閲覧されるにつれて、それに応じてAPI呼び出しを更新する必要があります。

{% hint style="info" %}
ベストプラクティス

顧客がより深いカテゴリーを閲覧する際に、広告リクエストに最も低いレベルのカテゴリーを送信することがベストプラクティスです。 Epsilon Retail Media 顧客がより深いカテゴリーを閲覧するにつれて、

L1 + L2 + L3 のレベル 3 でチェーンリクエストを指定する代わりに、L3 カテゴリーのみを指定します。
{% endhint %}

### クロスセルカテゴリー配置

クロスセルカテゴリー配置のリクエストは、カテゴリー配置と非常に似ています。広告をリクエストしている正確なカテゴリーを指定する必要があります。これは通常、現在表示しているページです。リクエストの `productFilters` 内でカテゴリーを指定します。以下の例は、カテゴリーフィルターを送信する場所を示しています:

```http
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category-cross-sell",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}
```

追加のカテゴリーが閲覧されるにつれて、それに応じてAPI呼び出しを更新する必要があります。

{% hint style="info" %}
オーガニックとクロスセルのカテゴリーターゲティングの統合？

オーガニック広告リクエストとクロスセルカテゴリー広告リクエストを単一の配置に統合したい場合は、統合と配信のロジックを顧客に実装する必要があります。これはインテグレーターの責任ですが、 Epsilon Retail Media ご相談に応じます。

一般的には、オーガニックカテゴリー広告を表示し、オーガニック配置の後に位置およびカテゴリーのクロスセル広告を掲載することをお勧めします。
{% endhint %}

### 部分一致配置

ホーム画面やチェックアウトページなどの部分一致配置では、リクエスト内で `productFilters` を指定する必要はありません。リテーラーが指定したいフィルター（提供中、新規など）は、 `productFilters` 内で指定して、 Epsilon Retail Media 要件内の広告のみを配信するようにできます。

```http
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 []
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}
```

### リクエストの拡張

検索、カテゴリー、および部分一致配置では、ユーザーエクスペリエンスを向上させるために以下の拡張機能を検討することをお勧めします。

#### リクエストのページネーション

商品広告を生成する際、以下を受け取ります: `memoryToken` 以降のリクエストで送信して、以前に配信された広告を除外できます。その後、これを `memoryToken` 以降の広告リクエストで送信できます。 Epsilon Retail Media により、当社の広告レスポンスから同じコンテキストの以前に配信された広告が除外されます。

実装する前に [ページネーション](/retail-media-interface/integration/ja/feature-integrations/pagination.md) を確認してください。

```http
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=",
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3
}
```

#### 絞り込み検索

顧客が検索を絞り込む場合、コンテキストを拡張して提供できます `productFilters`以下は、顧客が「食器棚」カテゴリと食事制限「グルテンフリー」で絞り込んでいる例です。この同じ原則は、任意のカテゴリまたは部分一致の配置に適用できます。

```http
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}
```

#### 位置情報による絞り込み

カタログ内の位置情報フィルターを同期している場合は、コンテキストを拡張して顧客の店舗位置情報を次で提供できます `productFilters`:

```http
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}
```

## プロダクト広告レスポンス

すべてのプロダクト広告レスポンスは同じJSON形式に従います。プロダクト広告は以下の `ads` 配列で返されます。例：

```json
{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        },
        {
            "id": "display_xNeShqidaMuEqiJ0zNdt-Gzygjs3NzE0MTA3",
            "gtin": "7714107",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400912929Z",
            "position": 3
        },
        {
            "id": "display_3rGiryPskhQusmsf43nghbQwnqo3NzMzNjU3",
            "gtin": "7733657",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400917769Z",
            "position": 4
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}
```

この `id` フィールドは、インプレッションおよびクリックレポートで使用される広告IDです。 `position` フィールドは、 Epsilon Retail Media ペイロード内の位置を定義します。各文字列の詳細については、リファレンスを参照してください。

{% hint style="info" %}
固定掲載の配置が正しく表示されるように、 `position` フィールドを読み取り、尊重する必要があります。
{% endhint %}

### マーケットプレイスの sellerId

マーケットプレイスのセラーをオンボーディングしている場合、レスポンス内の広告ごとに追加の `sellerId` が表示されることがあります。これは、配信されるキャンペーンを所有するチームがUIでセラーIDを設定している場合にのみ表示されます。以下の例では、sellerIdがある広告1つと、ない広告1つを示しています。

```json
{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "sellerId": "2834-ascre-2wcr4",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}
```

{% hint style="info" %}
このセクションの文字列について不明な点がある場合は、 [商品広告リファレンス](/retail-media-interface/integration/ja/references/product-ad-reference-1.md) ページをご覧ください。
{% endhint %}

## デジタルサービス法

Epsilon Retail Media は、リテール企業が欧州連合（EU）の [デジタルサービス法](https://commission.europa.eu/strategy-and-policy/priorities-2019-2024/europe-fit-digital-age/digital-services-act_en) （DSA）の義務を満たすのを支援します。DSAは、オンラインコンテンツの規制、透明性のある広告、誤情報を対象として、EU全域で統一されたルールを確立しています。詳細については、以下を参照してください [デジタルサービス法](/retail-media-interface/integration/ja/feature-integrations/digital-services-act.md).

### 広告リクエストの例

```
{
    "placement": "search-only",
    "catalogId": "zesty-fruits-catalog",
    "searchTerm": "lime",
    "maxNumberOfAds": 5,
    "options": {
   			    "filterMode": "AndOr",
    			"includeAdvertiserInfo": true,
     },
}
```

### 広告レスポンスの例

```
{
  "ads": [
    {
      "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
      "gtin": "7733636",
      "discount": {
        "amount": 0,
        "minPrice": 0,
        "maxPerCustomer": 0
      },
      "expiry": "2021-05-12T04:17:50.400902957Z",
      "position": 1,
      "metadata": {
        "advertiserInfo": {
       "advertiser": "Bob's advertising agency",
          "onBehalfOf": "Brand company inc",
        }
      }
    },
    ....
  ],
  "banners": [],
  "products": [],
  "memoryToken": "85ykKVv-………"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.citrusad.com/retail-media-interface/integration/ja/generating-ads/product-ads/requesting-product-ads-1.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.