> ## 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.
# Productos
Este informe muestra la visibilidad de los productos en los resultados de compras de ChatGPT. También puede
proporcionar las ofertas de comerciantes para cada producto. El informe devuelve cada producto como
`{ name, brand }` con sus métricas como campos con nombre.
* **Métricas:** `visibility_score`; `average_position` (un número **más bajo** es **mejor**); `visibility_rank`; las métricas de frecuencia de posición `position1_percentage`, `position2_percentage`, `position3_percentage`, `position_above3_percentage`; `product_rating`; `product_num_reviews`.
* **Métricas de frecuencia de posición:** Cada una es la proporción de apariciones del producto en esa posición (`position1` = la primera; `position_above3` = por debajo de la posición 3). Los valores son **fracciones de 0 a 1**, no de 0 a 100. Los cuatro valores suman aproximadamente 1.
* **`group_by`:** `date`, `topic` o `prompt`.
* **Campos de filtro:** `topic`, `region`, `persona`, `prompt`, `tag`, `brand`, `merchant`.
### Ofertas de comerciantes
Para adjuntar las ofertas de comerciantes a cada producto, establece `include_merchants: true`.
El informe agrega entonces `merchants` (una lista de `{ name, price }`), `product_url`
y `product_image_urls`. Este modo no acepta `group_by` ni
`target_product`. Las métricas de frecuencia de posición no están disponibles en este modo.
### Modo de competidores
Para devolver un producto y sus principales competidores, establece `target_product` con el
nombre de un producto. Para definir el número de competidores, usa `competitor_limit` (el
valor predeterminado es 5). El modo de competidores solo está disponible en la vista de elementos. No lo uses
con `include_merchants`.
Los datos de compras provienen únicamente de ChatGPT. Ningún informe de compras tiene un `group_by`
de `model` ni un filtro `model`.
Los informes v2 comparten una misma estructura de solicitud. Para el árbol de filtros, la agrupación y la
paginación, consulta [Filtrado y conceptos](/es/rest-api/reports/reports-v2-overview).
`POST /v2/reports/shopping/products/stream` usa el **mismo cuerpo de solicitud**.
Devuelve [Server-Sent Events](https://developer.mozilla.org/docs/Web/API/Server-sent_events):
un evento `summary` (el bloque `info`) y luego un evento `result` por cada fila.
El stream rechaza `limit` y `cursor`. Devuelve todas las filas de forma predeterminada. Para
establecer un máximo, usa `max_results` (máximo 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
````