> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 商品
このレポートは、ChatGPT のショッピング結果における商品の可視性を示します。各商品の
マーチャントのオファーを取得することもできます。レポートは各商品を
`{ name, brand }` として返し、その指標を名前付きフィールドとして含めます。
* **指標:** `visibility_score`、`average_position` (数値が **低い** ほど **良い**)、`visibility_rank`、掲載位置の頻度を示す指標 `position1_percentage`、`position2_percentage`、`position3_percentage`、`position_above3_percentage`、`product_rating`、`product_num_reviews`。
* **掲載位置の頻度指標:** それぞれ、商品の表示のうちその位置に表示された割合です (`position1` = 最上位、`position_above3` = 3 位より下)。値は 0–100 ではなく **0–1 の割合** です。4 つの値の合計は約 1 になります。
* **`group_by`:** `date`、`topic`、または `prompt`。
* **フィルタフィールド:** `topic`、`region`、`persona`、`prompt`、`tag`、`brand`、`merchant`。
### マーチャントのオファー
各商品にマーチャントのオファーを付加するには、`include_merchants: true` を設定します。
レポートには `merchants` (`{ name, price }` のリスト)、`product_url`、
`product_image_urls` が追加されます。このモードでは `group_by` と
`target_product` は使用できません。また、掲載位置の頻度指標も利用できません。
### 競合モード
1 つの商品とその上位の競合を返すには、`target_product` に
商品名を設定します。競合の数を設定するには `competitor_limit` を使用します (
デフォルトは 5)。競合モードはアイテムビューでのみ利用できます。
`include_merchants` と併用しないでください。
ショッピングデータは ChatGPT のみから取得されます。ショッピングレポートには `model` の
group\_by や `model` フィルタはありません。
v2 レポートは共通のリクエスト形式を使用します。フィルタツリー、グループ化、
ページネーションについては、[フィルタリングと概念](/ja-jp/rest-api/reports/reports-v2-overview) を参照してください。
`POST /v2/reports/shopping/products/stream` は **同じリクエストボディ** を使用します。
[Server-Sent Events](https://developer.mozilla.org/docs/Web/API/Server-sent_events) を返し、
まず 1 つの `summary` イベント (`info` ブロック) が送信され、続いて行ごとに 1 つの `result` イベントが送信されます。
ストリームは `limit` と `cursor` を受け付けません。デフォルトではすべての行が返されます。
上限を設定するには `max_results` (最大 50000) を使用します。
```bash cURL theme={null}
curl -X POST https://api.tryprofound.com/v2/reports/shopping/products \
-H "X-API-Key: " \
-H "Content-Type: application/json" \
-d '{
"category_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"include_merchants": true,
"metrics": ["visibility_score", "product_rating", "product_num_reviews"],
"limit": 10
}'
```
```json 200 theme={null}
{
"info": {
"total_results": 128,
"count": 10,
"next_cursor": "eyJvZmZzZXQiOjEwfQ==",
"models": ["ChatGPT"],
"include_merchants": true,
"metrics": ["visibility_score", "product_rating", "product_num_reviews"],
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"filter": null
},
"data": [
{
"product": { "name": "Example Running Shoe", "brand": "Example Brand" },
"merchants": [
{ "name": "Example Retailer", "price": "$120.00" },
{ "name": "Example Brand", "price": "$110.00" }
],
"product_url": "https://www.example.com/p/example-running-shoe",
"product_image_urls": ["https://images.example.com/products/example-running-shoe.jpg"],
"product_rating": 4.5,
"product_num_reviews": 1200,
"visibility_score": 0.30
}
]
}
```
## OpenAPI
````yaml POST /v2/reports/shopping/products
openapi: 3.1.0
info:
title: External API
version: 0.60.2
x-scalar-sdk-installation:
- lang: Python
description: |-
```sh
pip install profound
```
- lang: TypeScript
description: |-
```sh
npm install @profoundai/client
```
- lang: Rust
description: |-
```sh
cargo add profound
```
servers:
- url: https://api.tryprofound.com
description: Production Server
security:
- APIKeyHeader:
- X-API-Key
- BearerAuth: []
paths:
/v2/reports/shopping/products:
post:
tags:
- Reports
- Reports
summary: Query Shopping Products V2
operationId: query_shopping_products_v2_v2_reports_shopping_products_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ShoppingProductsV2Query'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ShoppingProductsV2Response'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- BearerAuth: []
x-codeSamples:
- label: Python
lang: Python
source: |-
import os
from profound import Profound
client = Profound(
api_key=os.environ.get("PROFOUND_API_KEY"),
)
shopping = client.reports.shopping.products(
category_id="7c9e6679-7425-40de-944b-e07fc1f90ae7",
start_date="",
end_date="",
interval="day",
include_merchants=False,
competitor_limit=5,
)
print(shopping)
- label: TypeScript
lang: TypeScript
source: |-
import Profound from '@profoundai/client';
const client = new Profound({
apiKey: process.env['PROFOUND_API_KEY'], // defaults to the PROFOUND_API_KEY env var
environment: 'production',
});
const shopping = await client.reports.shopping.products({
category_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
start_date: '',
end_date: '',
interval: 'day',
include_merchants: false,
competitor_limit: 5,
});
console.log(shopping);
- label: rust
lang: rust
source: |-
use profound::*;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = ProfoundClient::builder()
.api_key(std::env::var("PROFOUND_API_KEY")?)
.build()?;
let response = client
.reports()
.shopping()
.products(ShoppingProductsV2Query {
category_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7".to_string(),
start_date: "".to_string(),
end_date: "".to_string(),
group_by: None,
metrics: None,
interval: None,
include_merchants: None,
target_product: None,
competitor_limit: None,
filter: None,
limit: None,
max_results: None,
cursor: None,
})
.send()
.await?;
println!("{:?}", response);
Ok(())
}
components:
schemas:
ShoppingProductsV2Query:
properties:
category_id:
type: string
format: uuid
title: Category Id
start_date:
type: string
title: Start Date
description: YYYY-MM-DD, ET, inclusive
end_date:
type: string
title: End Date
description: YYYY-MM-DD, ET, inclusive
group_by:
items:
type: string
enum:
- date
- topic
- prompt
type: array
title: Group By
metrics:
anyOf:
- items:
type: string
enum:
- visibility_score
- average_position
- visibility_rank
- position1_percentage
- position2_percentage
- position3_percentage
- position_above3_percentage
- product_rating
- product_num_reviews
type: array
- type: 'null'
title: Metrics
interval:
type: string
enum:
- day
- week
- month
title: Interval
default: day
include_merchants:
type: boolean
title: Include Merchants
description: Include per-product merchant offers (names, prices, urls, images).
default: false
target_product:
anyOf:
- type: string
minLength: 1
- type: 'null'
title: Target Product
description: Return this product plus its top competitors (item view only).
competitor_limit:
type: integer
minimum: 1
title: Competitor Limit
description: Competitors returned when `target_product` is set.
default: 5
filter:
anyOf:
- $ref: '#/components/schemas/FilterNode'
- type: 'null'
limit:
anyOf:
- type: integer
maximum: 50
exclusiveMinimum: 0
- type: 'null'
title: Limit
description: Page size; default 10, max 50.
max_results:
anyOf:
- type: integer
maximum: 50000
exclusiveMinimum: 0
- type: 'null'
title: Max Results
description: 'Stream endpoint only: cap streamed rows.'
cursor:
anyOf:
- type: string
- type: 'null'
title: Cursor
additionalProperties: false
type: object
required:
- category_id
- start_date
- end_date
title: ShoppingProductsV2Query
ShoppingProductsV2Response:
properties:
info:
$ref: '#/components/schemas/ShoppingProductsV2Info'
data:
items:
$ref: '#/components/schemas/ShoppingProductRow'
type: array
title: Data
type: object
required:
- info
- data
title: ShoppingProductsV2Response
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
FilterNode:
properties:
and:
anyOf:
- items:
$ref: '#/components/schemas/FilterNode'
type: array
- type: 'null'
title: And
or:
anyOf:
- items:
$ref: '#/components/schemas/FilterNode'
type: array
- type: 'null'
title: Or
not:
anyOf:
- $ref: '#/components/schemas/FilterNode'
- type: 'null'
field:
anyOf:
- type: string
- type: 'null'
title: Field
op:
anyOf:
- type: string
- type: 'null'
title: Op
value:
title: Value
additionalProperties: false
type: object
title: FilterNode
description: A leaf (`field`/`op`/`value`) or an `and`/`or`/`not` group.
ShoppingProductsV2Info:
properties:
total_results:
anyOf:
- type: integer
- type: 'null'
title: Total Results
description: Total products matching the query before pagination.
count:
type: integer
title: Count
description: >-
Number of products on this page. When grouped by
`date`/`topic`/`prompt`, `data` holds one row per product x bucket,
so `len(data)` can exceed `count`.
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
description: Opaque cursor for the next page; null on the last page.
models:
items:
type: string
type: array
title: Models
description: Display names of the models the report covers.
start_date:
type: string
title: Start Date
description: Echoed request start date (YYYY-MM-DD, ET).
end_date:
type: string
title: End Date
description: Echoed request end date (YYYY-MM-DD, ET).
filter:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Filter
description: Echoed normalized filter tree, or null when no filter was sent.
include_merchants:
type: boolean
title: Include Merchants
description: Whether merchant offers are included in each row.
metrics:
items:
type: string
type: array
title: Metrics
description: Metrics returned per row.
additionalProperties: true
type: object
required:
- count
- models
- start_date
- end_date
- include_merchants
- metrics
title: ShoppingProductsV2Info
ShoppingProductRow:
properties:
product:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Product
date:
anyOf:
- type: string
- type: 'null'
title: Date
topic:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
prompt:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
visibility_score:
anyOf:
- type: number
- type: 'null'
title: Visibility Score
average_position:
anyOf:
- type: number
- type: 'null'
title: Average Position
visibility_rank:
anyOf:
- type: integer
- type: 'null'
title: Visibility Rank
position1_percentage:
anyOf:
- type: number
- type: 'null'
title: Position1 Percentage
position2_percentage:
anyOf:
- type: number
- type: 'null'
title: Position2 Percentage
position3_percentage:
anyOf:
- type: number
- type: 'null'
title: Position3 Percentage
position_above3_percentage:
anyOf:
- type: number
- type: 'null'
title: Position Above3 Percentage
product_rating:
anyOf:
- type: number
- type: 'null'
title: Product Rating
product_num_reviews:
anyOf:
- type: integer
- type: 'null'
title: Product Num Reviews
product_url:
anyOf:
- type: string
- type: 'null'
title: Product Url
product_image_urls:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Product Image Urls
merchants:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Merchants
description: >-
Per-product merchant offers `{name, price}` (only with
`include_merchants`).
additionalProperties: true
type: object
title: ShoppingProductRow
description: >-
One product row. Merchant fields present only when `include_merchants`
is true.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
DimensionRef:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
name:
anyOf:
- type: string
- type: 'null'
title: Name
type: object
title: DimensionRef
description: An ``{id, name}`` reference for a grouped dimension value.
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````