Search Catalog
POST /v3/catalog/query — Search the Price Hero catalog (products and taxonomy entities).
POST https://api.pricehero.ai/v3/catalog/query
Legacy path: POST /api/v3/catalog/search (same behavior).
Search the catalog by text query with optional facet filters. You can search products (default) or a specific entity type (e.g. model, style, dial) using taxonomy_node; use category_id to scope which entity types are valid for that category (see the parameters table).
Request
curl -X POST https://api.pricehero.ai/v3/catalog/query \
-H "Authorization: Bearer ph_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Louis Vuitton Speedy",
"taxonomy_node": "product",
"page": 0,
"page_size": 20,
"includes": ["taxonomy", "pricing"]
}'Body parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | — | Free-text search |
category_id | string | — | Optional category slug or id to scope the search and validate taxonomy_node for that category’s allowed entity types. |
filters | array | — | Facet filters: each item is { "field": "<attribute field>", "ids": ["id1", …] }. OR among ids for the same field; AND between different fields. Same catalog field / id strings as product attributes. Unknown or inapplicable facets yield no rows, not an error. |
taxonomy_node | string | product | Document kind to search: product, brand, model, style, family, case, dial, or category. If you pass a category_id filter, only types allowed for that category are accepted; otherwise the API returns 400 and may include allowed_taxonomy_nodes. |
page | integer | 0 | Page index |
page_size | integer | 20 | Page size (server-capped, default max 100) |
includes | string[] | ["taxonomy"] | taxonomy, pricing only (catalog is rejected with 400) |
filters (facet narrowing)
Optional array of objects: { "field": "<attribute field>", "ids": ["id1", "id2", …] }.
- OR (same
field): a product matches if any id in that object’sidslist appears on the product’sattributesfor thatfield(e.g. several brands → match if the product is any of those brands). - AND (different
fields): each object in the array must be satisfied. Example: one object forbrandand one formodelmeans the product must match both a chosen brand and a chosen model (ids must match that attribute’s entity type on the product). fielduses the same strings as product attributes (brand,model,family,style, etc.). Each id inidsmust appear on the product’s attributes for that field.- If a facet does not apply to the chosen category, you may get zero results (not an error).
Example (multiple brands or within brand, plus one model — all and-ed with query):
"filters": [
{ "field": "brand", "ids": ["brand_abc", "brand_def"] },
{ "field": "model", "ids": ["model_xyz"] }
]Response
Successful responses include includes, resolved_taxonomy (node + level), total_results, page, total_pages, credits_used, and data. level is derived from the category’s attribute hierarchy when a category filter is set, or from the first hit’s category when there are results.
Each item has id, name, popularity, images, and thumbnails. attributes (objects with field, id, name) is included only when includes contains taxonomy. The variants array is included only when the row is a product (taxonomy_node === product); each variant includes fields only when includes contains taxonomy. With includes containing pricing, each variant includes a pricing object: market_estimates is null or an array of one object per catalog_market_estimates row for that variant (all regions and sources, e.g. google_shopping and ebay); historical_estimates and pricing_data are each null or an array of { "region": "…", "url": "…" }.
Non-product hits (e.g. a model row) return the display name in name (sourced from the row’s internal entity name when applicable) and do not include a variants field.
Credits
See Credits. You are charged only when this response includes at least one row in data (the results count for that response is greater than zero). The taxonomy include is billed as the catalog credit; adding pricing adds the pricing module credits when the request is billable.