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

# Product Lookup: AIショッピングエンジンが商品をどう表示するかを確認する

> ChatGPT、Google AIによる概要、AIモード、Copilot、NAVER AIタブに商品について尋ね、エンジンごとに回答が商品を表示したか、どの販売店の出品を使ったか、どのページを引用したかを確認します。

Product Lookup は、AIショッピングエンジンが買い物客に商品をどう見せているかを確認するために使います。商品名と市場を送ると、querying.ai が各エンジンにその商品について尋ねます。エンジンごとに、回答が商品を表示したか、どの販売店の出品（販売店、カタログ、価格、在庫、評価とレビュー数）を表示したか、回答がどのページを引用したかを返します。競合商品を5つまで加えるとエンジンごとに並べて比較でき、`best moisturizing eye cream` のようなショッピングプロンプトを3つまで加えると、各エンジンがこれらの商品のうちどれを買い物客に見せるかがわかります。

1回のルックアップで次のことがわかります。

* ChatGPT、Google AIによる概要、AIモード、Copilot に商品について尋ねたとき、その商品が表示されるか
* 各エンジンがどの販売店とカタログの記録から、どの価格、評価、レビュー数で表示しているか
* ChatGPT の回答モデルが商品について何を読み取ったか
* エンジンごとに競合商品と比べてどうか
* ショッピングの質問に対して、各エンジンがこれらの商品のうちどれを表示するか

## ルックアップを送信する

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/product-lookup \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "belif Moisturizing Eye Bomb",
    "country": "US",
    "competitors": ["Clinique All About Eyes", "CeraVe Eye Repair Cream"],
    "prompts": ["best eye cream for puffiness", "best moisturizing eye cream"],
    "idempotencyKey": "eye-bomb-us"
  }'
```

ルックアップは質問に分かれます。質問とは、1つの商品または1つのショッピングプロンプトを1つのエンジンに尋ねることです。質問はそれぞれ通常のタスクとしてキューに入り、レスポンスにその一覧が入ります。次の例は、23件の質問のうち3件だけを残したものです。

```json theme={"theme":"css-variables"}
{
  "success": true,
  "lookup": {
    "id": "eye-bomb-us",
    "product": "belif Moisturizing Eye Bomb",
    "competitors": ["Clinique All About Eyes", "CeraVe Eye Repair Cream"],
    "prompts": ["best eye cream for puffiness", "best moisturizing eye cream"],
    "country": "US",
    "engines": ["CHATGPT", "GOOGLE", "AIMODE", "BING_COPILOT"]
  },
  "summary": { "total": 23, "succeeded": 23, "failed": 0 },
  "credits": { "creditsToCharge": 40, "creditsCharged": 0 },
  "asks": [
    {
      "engine": "CHATGPT",
      "taskType": "CHATGPT",
      "role": "product",
      "prompt": "Buy belif Moisturizing Eye Bomb",
      "success": true,
      "task": {
        "id": "56be57f3-d316-4727-8bd3-ab065fed2ec1",
        "taskType": "CHATGPT",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "2026-10-20T09:22:43.422Z",
        "idempotencyKey": "eye-bomb-us:CHATGPT:buy"
      }
    },
    {
      "engine": "CHATGPT",
      "taskType": "CHATGPT",
      "role": "competitor",
      "prompt": "Buy Clinique All About Eyes",
      "success": true,
      "task": {
        "id": "35f300a4-7603-4ad0-97ba-82eb6a07eed9",
        "taskType": "CHATGPT",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "2026-10-20T09:22:43.637Z",
        "idempotencyKey": "eye-bomb-us:CHATGPT:buy:c1"
      }
    },
    {
      "engine": "AIMODE",
      "taskType": "AIMODE",
      "role": "prompt",
      "query": "best eye cream for puffiness",
      "success": true,
      "task": {
        "id": "bff41168-d081-4bce-a873-9609baafbaa5",
        "taskType": "AIMODE",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "2026-10-20T09:22:44.149Z",
        "idempotencyKey": "eye-bomb-us:AIMODE:p1"
      }
    }
  ]
}
```

* `lookup.id` は送った `idempotencyKey`、送らなかった場合はサーバーが決めた UUID です。この値でルックアップを読み取ります。
* `asks[]` の各項目には、`role`（`product`、`competitor`、`prompt`）、尋ねた内容（`prompt` または `query`）、その質問の `task` が入ります。拒否された質問には `task` の代わりに `success: false` と `error` が入ります。[エラー](#エラー)を参照してください。
* `credits.creditsToCharge` はレスポンスに入っている質問の料金の合計で、各質問が終わるまで残高から確保されます。`creditsCharged` はそれらの質問にすでに請求された額です。

`lookup.status` が `COMPLETED` になるまで `GET /v1/product-lookup/{id}` でルックアップを読み取ります。この例では約2分かかりました。ルックアップは最も遅いエンジンが回答した時点で終わります。`webhook.url` を指定すると、各質問のタスクが終わるたびに送信され、`task.idempotencyKey` にはルックアップ id で始まるその質問のキーが入ります。ルックアップ全体の完了を知らせる Webhook はないため、受け取るたびにルックアップを読み取って `lookup.status` を確認してください。スキーマは API リファレンスの[Product Lookup](/ja/api-reference/product-lookup.md)と[Product Lookupの取得](/ja/api-reference/get-product-lookup.md)にあります。

## リクエストフィールド

| フィールド | 必須 | 説明 |
| - | - | - |
| `product` | はい | 買い物客が書くとおりの商品名。1〜200文字。例: `belif Moisturizing Eye Bomb`。商品ページの URL や GTIN は `400 VALIDATION_ERROR` を返します。 |
| `country` | はい | `US`（米国）または `KR`（韓国）。大文字と小文字は区別しません。それ以外の値は `422 REGION_UNSUPPORTED` を返します。 |
| `competitors` | いいえ | ほかの商品名を最大5つ。規則は `product` と同じで、各競合商品には商品と同じ質問をします。商品と同じ名前や、2回入れた名前は `400` を返します。大文字と小文字、句読点、空白だけが違う名前は同じ名前とみなします。 |
| `prompts` | いいえ | 1〜300文字のショッピングプロンプトを最大3つ。例: `best moisturizing eye cream`。書かれたとおりに各エンジンへ1回ずつ尋ねます。 |
| `engines` | いいえ | 尋ねるエンジン: `CHATGPT`、`GOOGLE`、`AIMODE`、`BING_COPILOT`、`GEMINI`、および `KR` のみの `NAVER_AI_TAB`。省略すると、下記の市場ごとの既定のエンジンに尋ねます。 |
| `idempotencyKey` | いいえ | ルックアップの名前。前後に空白のない1〜200文字です。[もう一度送る](#もう一度送る)を参照してください。 |
| `priority` | いいえ | `1`〜`10` の整数、既定値は `1` で、すべての質問に付きます。範囲外の値は丸められます。実行順序は保証しません。 |
| `webhook.url` | いいえ | 各質問のタスクが終わると受け取ります。[Webhook](/ja/concepts/webhooks.md)を参照してください。 |

## エンジンと質問

商品と各競合商品は同じ質問を受けます。

| エンジン | `US` | `KR` |
| - | - | - |
| `CHATGPT` | `Buy {product}`、`Find the best price for {product}` | `{product} 구매`、`{product} 최저가` |
| `GOOGLE`（Google AIによる概要） | 商品名 | 商品名（指定時のみ） |
| `AIMODE`（Google AIモード） | 商品名 | 商品名 |
| `BING_COPILOT`（Copilot） | 商品名 | 商品名（指定時のみ） |
| `NAVER_AI_TAB`（NAVER AIタブ） | 非対応 | 商品名 |
| `GEMINI` | 商品名（指定時のみ） | 商品名（指定時のみ） |

「指定時のみ」は、`engines` に入れたときだけ尋ねるという意味です。`engines` を省略すると、`US` のルックアップは ChatGPT、AIによる概要、AIモード、Copilot に尋ね、商品ごとの質問は5件です。`KR` のルックアップは NAVER AIタブ、ChatGPT、AIモードに尋ね、商品ごとの質問は4件です。ショッピングプロンプトは各エンジンに1回ずつ尋ねるので、`US` の既定では4件、`KR` の既定では3件です。上の例の質問は 3 × 5 + 2 × 4 = 23件でした。

ChatGPT に2回尋ねるのは、1回の質問で商品の記録が出るのは商品の半分ほどで、同じ質問を繰り返すと別の半分で出ることが多いためです。ほかの既定のエンジンは、2026-10-20 に50商品で試したときに商品を表示したエンジンです。

| エンジン | `US` | `KR` |
| - | - | - |
| ChatGPT（2つの質問、ウィジェットカードを含む） | 24回中24回 | 20回中20回 |
| Copilot | 25商品中25 | 25商品中0 |
| Google AIによる概要 | 25商品中23 | 25商品中1 |
| Google AIモード | 25商品中23 | 25商品中13 |
| NAVER AIタブ | – | 25商品中25 |

ChatGPT の行は、`US` の12商品と `KR` の10商品をそれぞれ2回ずつルックアップした結果です。Gemini は両市場の115件の質問で、商品の記録を1件も表示しませんでした。

## ルックアップを読み取る

```bash theme={"theme":"css-variables"}
curl https://api.querying.ai/v1/product-lookup/eye-bomb-us \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

結果は5つの部分からなります。

* `lookup`: 尋ねた内容、`status`、これまでに請求された `credits`。
* `summary` と `engines[]`: 商品についての回答を、エンジン全体とエンジンごとにまとめたもの。
* `competitors[]`: 競合商品ごとの、同じ形の `summary` と `engines[]`。
* `comparison[]`: 商品と競合商品をエンジンごとに並べたもの。
* `prompts[]`: 各ショッピングプロンプトへの各エンジンの回答。

`lookup.status` は、質問が始まるまで `QUEUED`、終わっていない質問があるあいだは `PROCESSING` です。すべての質問が終わって1件以上が完了すると `COMPLETED`、すべて失敗すると `FAILED` になります。質問が終わるたびに項目が埋まるので、完了前でも読み取れます。

次の例は、上のルックアップの `lookup`、`summary`、`engines[]` です。4つのエンジンのうち2つと、各リストの一部だけを残しています。

```json theme={"theme":"css-variables"}
{
  "success": true,
  "lookup": {
    "id": "eye-bomb-us",
    "product": "belif Moisturizing Eye Bomb",
    "competitors": ["Clinique All About Eyes", "CeraVe Eye Repair Cream"],
    "prompts": ["best eye cream for puffiness", "best moisturizing eye cream"],
    "country": "US",
    "status": "COMPLETED",
    "createdAt": "2026-10-20T09:22:43.422Z",
    "completedAt": "2026-10-20T09:24:36.695Z",
    "credits": 40
  },
  "summary": {
    "foundIn": ["CHATGPT", "GOOGLE", "AIMODE", "BING_COPILOT"],
    "notFoundIn": [],
    "pending": [],
    "failed": [],
    "merchants": [
      {
        "merchant": "Ulta Beauty",
        "engines": ["CHATGPT", "BING_COPILOT"],
        "price": { "currency": "USD", "min": 48, "max": 48 }
      },
      {
        "merchant": "Amazon",
        "engines": ["CHATGPT"],
        "price": { "currency": "USD", "min": 43, "max": 43 }
      },
      {
        "merchant": "Comparor",
        "engines": ["BING_COPILOT"],
        "price": { "currency": "USD", "min": 35.82, "max": 45.9 }
      }
    ],
    "priceRange": { "currency": "USD", "min": 35.82, "max": 48 },
    "citedDomains": [
      { "domain": "ulta.com", "engines": ["CHATGPT", "GOOGLE", "AIMODE", "BING_COPILOT"] },
      { "domain": "lgbeauty.com", "engines": ["CHATGPT", "GOOGLE", "AIMODE"] }
    ],
    "credits": 10
  },
  "engines": [
    {
      "engine": "CHATGPT",
      "status": "COMPLETED",
      "found": true,
      "via": [
        {
          "taskType": "CHATGPT",
          "prompt": "Buy belif Moisturizing Eye Bomb",
          "taskId": "56be57f3-d316-4727-8bd3-ab065fed2ec1",
          "status": "COMPLETED",
          "completedAt": "2026-10-20T09:23:04.711Z",
          "credits": 2
        },
        {
          "taskType": "CHATGPT",
          "prompt": "Find the best price for belif Moisturizing Eye Bomb",
          "taskId": "c60ffa61-d399-4b15-8343-452dcc150fd3",
          "status": "COMPLETED",
          "completedAt": "2026-10-20T09:23:20.863Z",
          "credits": 2
        }
      ],
      "listings": [
        {
          "position": 1,
          "title": "belif Moisturizing Eye Bomb Eye Cream",
          "source": "merchant_feed",
          "merchant": "Ulta Beauty",
          "url": "https://www.ulta.com/p/moisturizing-eye-bomb-eye-cream-pimprod2043262?cmpid…",
          "price": { "value": 48, "currency": "USD", "raw": "$48.00" },
          "available": true,
          "brand": "belif",
          "modelSees": {
            "title": "belif Moisturizing Eye Bomb Eye Cream",
            "description": "belif's Moisturizing Eye Bomb Eye Cream is a lightweight cream that floods the eye area wi…",
            "rating": 4.5,
            "reviewCount": 105,
            "brand": "belif"
          },
          "ids": { "chatgptProductId": "2619879", "feedId": "oai-shopping-id:v1:feed:…" },
          "ask": 1,
          "match": { "score": 1 }
        },
        {
          "position": 1,
          "title": "Amazon",
          "source": "chatgpt_widget",
          "merchant": "Amazon",
          "url": "https://www.amazon.com/s?k=belif+Moisturizing+Eye+Bomb",
          "price": { "value": 43, "currency": "USD", "raw": "$43.00" },
          "description": "Reported sale price · $5 below retail · A recent October 2026 deal report lists this price.",
          "pictured": "belif Moisturizing Eye Bomb 25ml blue jar white lid",
          "ask": 2,
          "match": { "score": 1 }
        }
      ],
      "otherListings": [],
      "citedPages": [
        {
          "url": "https://lgbeauty.com/products/moisturizing-eye-bomb?selectedVariant=47584416432448",
          "domain": "lgbeauty.com",
          "title": "Moisturizing Eye Bomb",
          "ask": 1
        }
      ]
    },
    {
      "engine": "AIMODE",
      "status": "COMPLETED",
      "found": true,
      "via": [
        {
          "taskType": "AIMODE",
          "query": "belif Moisturizing Eye Bomb",
          "taskId": "74807193-762f-4689-a974-0dfb395ed0f9",
          "status": "COMPLETED",
          "completedAt": "2026-10-20T09:24:30.021Z",
          "credits": 2
        }
      ],
      "listings": [
        {
          "position": 1,
          "title": "belif Moisturizing Eye Bomb",
          "source": "google_shopping",
          "merchant": "Loja Glamourosa",
          "url": "https://www.google.com/search?ibp=oshop&prds=…",
          "price": { "value": 39.59, "currency": "USD", "raw": "$39.59" },
          "oldPrice": { "value": 53, "currency": "USD", "raw": "$53" },
          "rating": 4.7,
          "reviewCount": 1300,
          "ids": {
            "googleProductGroupId": "6991299462534820972",
            "googleCatalogId": "7562423970477224507",
            "googleProductDocId": "5915412989765911473"
          },
          "ask": 1,
          "match": { "score": 1 }
        },
        {
          "position": 2,
          "title": "belif Moisturizing Eye Bomb Stick",
          "source": "google_shopping",
          "merchant": "Oseila Beauty",
          "url": "https://www.google.com/search?ibp=oshop&prds=…",
          "price": { "value": 37.24, "currency": "USD", "raw": "$37.24" },
          "rating": 5,
          "reviewCount": 7,
          "ask": 1,
          "match": { "score": 1, "variant": ["stick"] }
        }
      ],
      "otherListings": [
        {
          "position": 3,
          "title": "belif Aqua Bomb Depuffing Eye Gel",
          "source": "google_shopping",
          "merchant": "Ulta Beauty",
          "price": { "value": 32, "currency": "USD", "raw": "$32.00" },
          "rating": 4.1,
          "reviewCount": 1400,
          "ask": 1,
          "match": { "score": 0.75, "missing": ["moisturizing"] }
        }
      ],
      "citedPages": [
        {
          "url": "https://www.sephora.com/product/belif-moisturizing-eye-bomb-with-peptide-ceramide-P510122",
          "domain": "sephora.com",
          "title": "Sephora",
          "ask": 1
        }
      ]
    }
  ]
}
```

4つのエンジンすべてが商品を表示しました。ChatGPT は Ulta Beauty の販売店フィードの記録を表示し、回答モデルはこの記録から評価4.5とレビュー105件を読み取りました。ChatGPT は Amazon を含む3つの販売店のウィジェットカードも書きました。AIモードは1つの販売店の出品と、`variant` が付いたスティック版を表示し、同じブランドのアイジェルは `otherListings` に入れました。

### `summary`

| フィールド | 説明 |
| - | - |
| `foundIn`、`notFoundIn` | 回答が商品を表示したエンジンと、質問が終わったものの商品を表示しなかったエンジン。 |
| `pending`、`failed` | 質問がまだ処理中のエンジンと、質問がすべて失敗したエンジン。 |
| `merchants[]` | 商品の出品の販売店ごとに、その販売店を表示した `engines` と、そこでの単品の `price` の範囲。エンジン数の多い順です。 |
| `priceRange` | エンジン全体での単品の価格範囲。市場の通貨（`US` は USD、`KR` は KRW）で数えます。別のパックや形態の出品（`match.variant`）は除きます。 |
| `citedDomains[]` | 回答が引用したサイトごとに、引用した `engines`。エンジン数の多い順です。 |
| `credits` | これまでに商品の質問に請求されたクレジット。ルックアップ全体は `lookup.credits` です。 |

### `engines[]`

尋ねたエンジンごとに1項目です。

| フィールド | 説明 |
| - | - |
| `status` | そのエンジンの質問全体の状態: `QUEUED`、`PROCESSING`、すべて終わって1件以上完了したら `COMPLETED`、すべて失敗したら `FAILED`。 |
| `found` | 回答が商品の出品を表示したら `true` です。カタログの記録と ChatGPT のウィジェットカードの両方を数えます。すべての質問が終わって見つからなければ `false`、処理中でまだ見つかっていないとき、またはすべての質問が失敗したときは `null` です。 |
| `via[]` | そのエンジンの質問を順に並べたもの。尋ねた内容、`taskId`、`status`、`credits` があり、失敗した質問には `error` が付きます。 |
| `listings[]` | その商品、またはその別のパックや形態と判定した出品。2つの質問がどちらも表示した出品は1回だけ入ります。 |
| `otherListings[]` | 回答が一緒に表示したほかの商品。名前が変わった、または翻訳された同じ商品がここに入ることがあります。 |
| `citedPages[]` | 回答が引用したページ。`url`、`domain`（`www.` や `m.` を除いたホスト）、`title`、`ask` があります。ChatGPT では、回答が引用した出典だけが入ります。 |

### 出品のフィールド

出品とは、エンジンが持つ1つの販売店の商品の記録です。エンジンが返すフィールドだけが入ります。

| フィールド | 説明 |
| - | - |
| `position` | 回答内での順序。1から数えます。 |
| `ask` | その出品を表示した質問。`via[]` の順に1から数えます。 |
| `title` | 記録上の商品名。ChatGPT のウィジェットカードではカードの見出しで、販売店名のこともあります。 |
| `merchant` | 販売店。 |
| `source` | 出品の出どころ。次の表を参照してください。 |
| `url` | エンジンが販売店のリンクを示す場合は販売店のページ、そうでなければエンジン自身の商品ページ。 |
| `price`、`oldPrice` | 表示どおりの `value`、`currency`、`raw`。`currency` は、その市場で通貨記号が1つに決まる場合は ISO 4217 コードです。`oldPrice` はエンジンが示した割引前の価格です。 |
| `available` | 在庫の有無。ChatGPT のみです。 |
| `rating`、`reviewCount` | 記録にある評価とレビュー数。 |
| `modelSees` | ChatGPT のみ。ChatGPT が回答モデルに渡した記録の情報で、`title`、`description`、`rating`、`reviewCount`、`brand`、`productPage` があります。販売店フィードの記録の評価とレビュー数はここにしかありません。 |
| `image`、`description`、`brand` | エンジンが表示したとおり。 |
| `reviews` | エンジンが表示したレビューの `summary`、`pros`、`cons`。 |
| `ids` | 1つの商品の記録どうしを結びつけるカタログ識別子。ChatGPT の `chatgptProductId` と `feedId`、Google のエンジンの `googleCatalogId`、`googleProductGroupId`、`googleProductDocId`、Copilot の `bingProductId` と `bingGroupId`、NAVER AIタブの `naverProductId` などがあります。GTIN を返すエンジンはありません。 |
| `pictured` | ChatGPT のウィジェットカードのみ。カードの横の画像が示すもので、回答が画像を探すために使った検索語です。 |
| `match` | その商品と判定した根拠。`score` は商品名の単語のうち出品に含まれる割合（0〜1）です。`missing` は含まれない単語、`variant` は別のパックや形態（セット、ミニ、1+1、スティック）、`accessory` は交換用フィルターのような、商品ではなく部品であることを示します。 |

`source` は、出品がどのカタログから来たかを示します。

| `source` | エンジン | 内容 |
| - | - | - |
| `shopify` | ChatGPT | ChatGPT の商品カタログにある Shopify ストアの記録 |
| `merchant_feed` | ChatGPT | 販売店が ChatGPT に送った商品フィードの記録 |
| `google_shopping` | ChatGPT、AIによる概要、AIモード、Gemini | Google ショッピングの記録 |
| `chatgpt_catalog` | ChatGPT | 出どころが示されていない ChatGPT のカタログの記録 |
| `chatgpt_widget` | ChatGPT | ChatGPT が記録なしでウィジェットカードに書いた販売店と価格 |
| `microsoft_shopping` | Copilot | Microsoft Shopping のオファー |
| `naver_shopping` | NAVER AIタブ | NAVER ショッピングの出品 |

### ChatGPT のウィジェットカード

ChatGPT は、ショッピングの質問にカードで答えることがよくあります。カードにはそれぞれ販売店のページで読み取った販売店と価格がありますが、その裏にカタログの記録はありません。ルックアップはこのカードを、回答の記録のあとに `chatgpt_widget` の出品として読み取り、`found` にも数えます。

* `merchant` はカードに書かれた販売店名、または購入リンクのドメインです。`description` はカードの説明行です。
* カードには `rating`、`reviewCount`、`available`、`ids`、`modelSees` がありません。価格が `$40–$62` のような範囲の場合、`price` は入りません。
* 購入リンクも販売店の行もないカードは読み取りません。
* その商品の記録や前のカードと、販売店と価格が同じカードは除きます。販売店名やリンク先のサイトが同じか、一方がもう一方で始まる場合は同じ販売店とみなします。Ulta、Ulta Beauty、ulta.com がその例です。

カタログの記録だけを見るには、`source` が `chatgpt_widget` の出品を除いて読んでください。

## 競合商品と比べる

1つの商品について尋ねた回答には、ほかのブランドの商品はほとんど出てきません。50商品の試験では一度も出ませんでした。そのため競合商品は自分で指定し、各競合商品に商品と同じ質問をします。`competitors[]` の各項目には競合商品の `product`、`summary`、`engines[]` があり、商品と同じように読みます。

`comparison[]` は、商品と競合商品を1行ずつ並べ、各行にエンジンごとの項目を置きます。次の例は、上のルックアップから Copilot だけを残し、商品については ChatGPT も残したものです。

```json theme={"theme":"css-variables"}
{
  "comparison": [
    {
      "product": "belif Moisturizing Eye Bomb",
      "role": "product",
      "engines": [
        {
          "engine": "CHATGPT",
          "status": "COMPLETED",
          "found": true,
          "listings": 4,
          "merchants": 4,
          "mostReviewed": { "reviewCount": 105, "rating": 4.5, "merchant": "Ulta Beauty" },
          "priceRange": { "currency": "USD", "min": 43, "max": 48 },
          "prompts": { "answered": 2, "appeared": 0 }
        },
        {
          "engine": "BING_COPILOT",
          "status": "COMPLETED",
          "found": true,
          "listings": 6,
          "merchants": 5,
          "mostReviewed": { "reviewCount": 2942, "rating": 4.58, "merchant": "Comparor" },
          "priceRange": { "currency": "USD", "min": 35.82, "max": 48 },
          "prompts": { "answered": 2, "appeared": 1 }
        }
      ]
    },
    {
      "product": "Clinique All About Eyes",
      "role": "competitor",
      "engines": [
        {
          "engine": "BING_COPILOT",
          "status": "COMPLETED",
          "found": true,
          "listings": 4,
          "merchants": 3,
          "mostReviewed": { "reviewCount": 85773, "rating": 4.6, "merchant": "Walmart" },
          "priceRange": { "currency": "USD", "min": 38.05, "max": 72 },
          "prompts": { "answered": 2, "appeared": 0 }
        }
      ]
    },
    {
      "product": "CeraVe Eye Repair Cream",
      "role": "competitor",
      "engines": [
        {
          "engine": "BING_COPILOT",
          "status": "COMPLETED",
          "found": true,
          "listings": 6,
          "merchants": 6,
          "mostReviewed": { "reviewCount": 117193, "rating": 4.35, "merchant": "Pasteur Pharmacy" },
          "priceRange": { "currency": "USD", "min": 15.95, "max": 38.95 },
          "prompts": { "answered": 2, "appeared": 0 }
        }
      ]
    }
  ]
}
```

| フィールド | 説明 |
| - | - |
| `role` | `product` または `competitor`。 |
| `found` | `engines[]` と同じです。 |
| `listings` | その商品と判定した出品の数。ChatGPT のウィジェットカードを含みます。 |
| `merchants` | それらの出品の販売店の数。 |
| `mostReviewed` | レビューが最も多い出品の `reviewCount`、`rating`、`merchant`。ChatGPT では、回答モデルが受け取った `modelSees` のレビュー数を使います。Copilot は1つの商品のレビュー数を販売店のオファーごとに付けるため、`merchant` はその数が付いた最初のオファーです。 |
| `priceRange` | そのエンジンでの単品の価格範囲。 |
| `prompts` | ショッピングプロンプトがある場合のみ。`answered` はそのエンジンが答えたショッピングプロンプトの数、`appeared` はそのうち商品を表示したか名前を挙げた回答の数です。 |

3つの商品はいずれも4つのエンジンすべてで見つかりました。Copilot では、商品の最もレビューの多い出品が2,942件で、2つの競合商品は85,773件と117,193件でした。8件のショッピングプロンプトの回答のうち、CeraVe Eye Repair Cream は5件に、商品と Clinique All About Eyes は2件ずつに登場しました。

## ショッピングプロンプト

`prompts[]` の各項目には、`prompt` と、エンジンごとに1項目ずつの `engines[]` があります。

| フィールド | 説明 |
| - | - |
| `shown` | 回答が記録やウィジェットカードで表示した、ルックアップの商品（商品と競合商品）。表示された順です。 |
| `named` | 回答の本文が名前を挙げた、ルックアップの商品。挙げられた順です。 |
| `listings[]` | 回答のすべての商品の記録とウィジェットカード。ルックアップの商品であれば `product` と `match` が付きます。 |
| `via[]`、`citedPages[]` | `engines[]` と同じです。 |

ショッピングプロンプトへの回答には多くのブランドの商品が出てくるため、記録にブランド、つまり商品名の最初の単語が含まれている場合にだけ、ルックアップの商品として数えます。本文中の名前は、[GEOモニター](/ja/monitors.md)がブランドの言及を数えるのと同じ方法で、商品名全体を探して数えます。

次の例は、上のルックアップで AIによる概要と Copilot が `best moisturizing eye cream` に答えた内容です。出品はルックアップの商品だけを残しています。

```json theme={"theme":"css-variables"}
{
  "prompts": [
    {
      "prompt": "best moisturizing eye cream",
      "engines": [
        {
          "engine": "GOOGLE",
          "status": "COMPLETED",
          "via": [
            {
              "taskType": "GOOGLE",
              "query": "best moisturizing eye cream",
              "taskId": "ae6a153a-6382-40d6-84df-c99de0b60d17",
              "status": "COMPLETED",
              "completedAt": "2026-10-20T09:24:29.231Z",
              "credits": 1.25
            }
          ],
          "shown": ["CeraVe Eye Repair Cream", "Clinique All About Eyes"],
          "named": [
            "belif Moisturizing Eye Bomb",
            "CeraVe Eye Repair Cream",
            "Clinique All About Eyes"
          ],
          "listings": [
            {
              "position": 1,
              "title": "CeraVe Eye Repair Cream",
              "source": "google_shopping",
              "product": "CeraVe Eye Repair Cream",
              "match": { "score": 1 }
            },
            {
              "position": 3,
              "title": "Clinique All About Eyes Rich",
              "source": "google_shopping",
              "product": "Clinique All About Eyes",
              "match": { "score": 1 }
            }
          ],
          "citedPages": [
            {
              "url": "https://www.nytimes.com/wirecutter/reviews/best-eye-cream/",
              "domain": "nytimes.com",
              "title": "The New York Times"
            }
          ]
        },
        {
          "engine": "BING_COPILOT",
          "status": "COMPLETED",
          "via": [
            {
              "taskType": "BING_COPILOT",
              "prompt": "best moisturizing eye cream",
              "taskId": "0f582e93-7756-439d-8e5c-bacc510fdff0",
              "status": "COMPLETED",
              "completedAt": "2026-10-20T09:23:45.384Z",
              "credits": 1.25
            }
          ],
          "shown": ["belif Moisturizing Eye Bomb"],
          "named": ["belif Moisturizing Eye Bomb"],
          "listings": [
            {
              "position": 1,
              "title": "belif Moisturizing Eye Bomb with Peptide and Ceramide",
              "source": "microsoft_shopping",
              "merchant": "Comparor",
              "price": { "value": 45.9, "currency": "USD", "raw": "$45.9" },
              "rating": 4.58,
              "reviewCount": 2942,
              "product": "belif Moisturizing Eye Bomb",
              "match": { "score": 1 }
            },
            {
              "position": 2,
              "title": "belif Moisturizing Eye Bomb with Peptide and Ceramide",
              "source": "microsoft_shopping",
              "merchant": "SweetCare",
              "price": { "value": 41.36, "currency": "USD", "raw": "$41.36" },
              "rating": 4.58,
              "reviewCount": 2942,
              "product": "belif Moisturizing Eye Bomb",
              "match": { "score": 1 }
            },
            {
              "position": 3,
              "title": "belif Moisturizing Eye Bomb with Peptide and Ceramide",
              "source": "microsoft_shopping",
              "merchant": "Macy's",
              "price": { "value": 48, "currency": "USD", "raw": "$48" },
              "rating": 4.58,
              "reviewCount": 2942,
              "product": "belif Moisturizing Eye Bomb",
              "match": { "score": 1 }
            }
          ],
          "citedPages": [
            {
              "url": "https://www.comparor.com/us/belif-moisturizing-eye-bomb-hydrating-eye-cream-25ml.html?utm_source=copilot.com",
              "domain": "comparor.com",
              "title": "belif Moisturizing Eye Bomb with Peptide and Ceramide"
            }
          ]
        }
      ]
    }
  ]
}
```

AIによる概要は本文で商品の名前を挙げましたが、記録は2つの競合商品のものだけを表示しました。Copilot は3つの販売店の、商品の出品を表示しました。判定は名前で行うため、`Clinique All About Eyes Rich` のように名前に単語が加わった版も、その商品として数えます。

## もう一度送る

質問にはそれぞれ、ルックアップ id から作られたキーがあります。

* 商品の質問: `<id>:<engine>:<ask>`。例: `eye-bomb-us:CHATGPT:buy`。ChatGPT の質問は `buy` と `price`、ほかのエンジンの質問は `name` です。
* n番目の競合商品の質問には、末尾に `:c<n>` が付きます。例: `eye-bomb-us:CHATGPT:buy:c1`。
* n番目のショッピングプロンプトの質問: `<id>:<engine>:p<n>`。例: `eye-bomb-us:AIMODE:p1`。

同じ `idempotencyKey` でルックアップをもう一度送ると、すでにある質問はそのまま返し、足りない質問だけを追加します。請求されるのも、追加した質問の分だけです。クレジットや同時実行数の上限で拒否された質問を埋めるときや、リストの末尾に競合商品やショッピングプロンプトを加えるときに使います。再送で省いた競合商品やショッピングプロンプトは、ルックアップに残ります。

商品や国を変えたり、すでに埋まっている位置に別の競合商品やショッピングプロンプトを入れたりすると、`409 RESOURCE_ALREADY_EXISTS` を返し、何も書き込みません。失敗した質問は、再送しても失敗したまま返ります。エンジンに改めて尋ねて新しい回答を得るには、新しい `idempotencyKey` で送ってください。

## 料金

ルックアップは、商品（商品と各競合商品）ごとに10クレジット、ショッピングプロンプトごとに5クレジットで、どのエンジンに尋ねても同じです。

* 上のルックアップは 3 × 10 + 2 × 5 = 40クレジットです。最大のルックアップ（商品1つ、競合商品5つ、ショッピングプロンプト3つ）は75クレジットです。
* 商品やショッピングプロンプトのクレジットは、その質問に分けて割り当てます。`US` の既定のエンジンでは、商品の質問1件が2クレジット、ショッピングプロンプトの質問1件が1.25クレジットです。`KR` の既定のエンジンでは、商品の質問1件が2.5クレジット、ショッピングプロンプトの3件の質問は1.67、1.67、1.66クレジットです。エンジンを減らしても料金は変わりません。ChatGPT だけに尋ねると、商品の2件の質問はそれぞれ5クレジットです。
* 質問はほかのタスクと同じく、送信時に確保され、完了時に請求されます。失敗した質問は請求されません。
* プランの料金に換算すると、商品1つは Basic で \$0.025、Max で \$0.010 です。

確保とプランについては[クレジットと制限](/ja/concepts/credits-and-limits.md)を参照してください。

## 結果を正しく読む

* **1回のルックアップは、ある時点の記録です。** 各エンジンは1〜2件の質問に答えます。1回だけ出た差で判断する前に、新しい `idempotencyKey` でもう一度ルックアップしてください。
* **記録の値は変わらず、どの記録が出るかが変わります。** 同じルックアップを4回実行したところ、同じ販売店の記録の価格、評価、レビュー数は、316個の値のうち307個が同じでした。実行ごとに変わるのは、回答がどの記録を表示するかです。そのため `found`（特に ChatGPT）、販売店、`mostReviewed`、`priceRange`、ショッピングプロンプトの `shown` と `named` は変わることがあります。
* **数分の間隔でも、数時間の間隔と同じくらい変わります。** ChatGPT、AIモード、Copilot の回答は、3分の間隔でも11時間の間隔と同じくらい違いました。AIによる概要は数秒以内に尋ね直すと同じ回答が返ることがあるため、すぐに尋ね直した結果は新しい標本になりません。
* **1件の回答より合計のほうが安定します。** 4回の実行で、ショッピングプロンプトの回答は1件ずつ見ると変わりましたが、最も多くの回答に登場した商品は毎回上位でした。ショッピングプロンプトを継続して追跡するには[GEOモニター](/ja/monitors.md)を使ってください。
* **`found: false` は今回の回答についての結果です。** 今回の実行の質問が商品を表示しなかったという意味です。エンジンのカタログに商品がないという意味ではありません。
* **判定は名前で行います。** GTIN を返すエンジンはありません。名前が変わった、または翻訳された商品は `otherListings` に入ることがあり、名前で区別できない版はその商品として数えることがあります。出品がおかしく見えるときは `match` を確認してください。

## 制限事項

* 入力は商品名です。商品ページの URL と GTIN には対応していません。
* 市場は `US` と `KR` です。
* 1回のルックアップには、競合商品を5つ、ショッピングプロンプトを3つまで入れられます。`US` の既定のエンジンでは、最大のルックアップは質問42件です。
* 競合商品は自分で指定したものだけです。ルックアップが競合商品を探すことはありません。エンジンが買い物客にどの商品を見せるかは、ショッピングプロンプトで確認します。
* ChatGPT からは記録とウィジェットカードを読み取ります。回答の本文や表に書かれた販売店と価格は読み取りません。
* 1件の回答から、出品は60件、引用ページは20件まで入ります。
* ルックアップは、質問のタスクを読み取れるあいだ、つまり完了から24時間まで読み取れます。[非同期タスク](/ja/concepts/async-tasks.md#保持期間)を参照してください。

## エラー

### 送信時の拒否

| ステータス | コード | 原因 |
| - | - | - |
| `400` | `VALIDATION_ERROR` | 本文が有効な JSON でないか、フィールドが上記の規則に反しています。`product` や `country` がない、名前の代わりに URL や GTIN を入れた、`competitors` や `prompts` が多すぎるか重複している、不明なエンジンやその市場で使えないエンジンを入れた、`idempotencyKey` が無効、などです。`details` がフィールドを示します。 |
| `422` | `REGION_UNSUPPORTED` | `country` が `US` でも `KR` でもありません。 |
| `409` | `RESOURCE_ALREADY_EXISTS` | `idempotencyKey` が、別の商品や国のルックアップ、または同じ位置に別の競合商品やショッピングプロンプトがあるルックアップを指しています。何も書き込まれていません。 |

```json theme={"theme":"css-variables"}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "product",
        "message": "product takes a product's name; a GTIN or barcode is not supported"
      }
    ],
    "timestamp": "2026-10-20T09:00:00.000Z"
  }
}
```

### 拒否された質問

質問は単一のタスクと同じように受け付けられるため、残高（`402 INSUFFICIENT_CREDITS`）、プランの同時実行数（`429 PLAN_CONCURRENCY_LIMIT`）、キーの1日あたりのクレジット上限（`429 KEY_DAILY_CREDIT_LIMIT`）、ほかのエンジンだけを使えるキーのために拒否されることがあります。拒否された質問は `success: false` と `error` を持って `asks[]` に残り、ほかの質問はそのまま進みます。

質問は1件ずつ受け付けられます。各商品についての全エンジンの最初の質問と、各ショッピングプロンプトが、2件目の質問より先に入ります。そのため、プランに一部の質問しか入る余裕がない場合は、受け付けられた質問ができるだけ多くのエンジンと商品をカバーします。商品の最初の質問が1件も入らなかった場合はほかの質問はせず、最初の拒否がそのステータスのままレスポンスになります。`402 INSUFFICIENT_CREDITS` がその例です。同時実行数が2の Free プランでは、`US` のルックアップは商品の ChatGPT の最初の質問と AIによる概要の質問だけが入ります。それらが終わってからもう一度送ると、残りが入ります。最大の `US` のルックアップ（質問42件）は、ほかのタスクがなければ Basic の同時実行数50に収まります。

認証エラーはほかのリクエストと同じです。[エラー](/ja/concepts/errors.md)を参照してください。

### 失敗した質問と読み取り

* 失敗した質問は `via[]` で `status: "FAILED"` と `error` を持ち、請求されません。質問がすべて失敗したエンジンは `status: "FAILED"`、`found: null` で、`summary.failed` に入ります。
* `GET /v1/product-lookup/{id}` は、アカウントにその id のルックアップがなければ `404 RESOURCE_NOT_FOUND` を返します。タスクの読み取り期間を過ぎたルックアップも同じです。

## 次のステップ

> **[GEOモニタリング](/ja/monitors.md)**
>
> ショッピングプロンプトを複数のAIエンジンで定期的に追跡します。

> **[Prompt Research](/ja/research/prompt-research.md)**
>
> ある分野で人々が尋ねるショッピングの質問を見つけます。


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