# Items listing
- Operation ID: `ListingPost`
- HTTP method: `POST`
- Path: `/search/v2/indices/{indexId}/list`
- [Human-readable API reference](https://hub.synerise.com/api-reference/ai-search#tag/Listing/operation/ListingPost)
## Self-contained OpenAPI method
The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required.
```yaml
openapi: 3.0.0
info:
title: Synerise Public API
version: 1.9.1
paths:
/search/v2/indices/{indexId}/list:
post:
summary: Items listing
description: |
Retrieves item listing, which is a search without a query. The results can be filtered and sorted.
---
**API consumers:** AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)
**API key permission required:** `ITEMS_SEARCH_SEARCH_READ`
operationId: ListingPost
tags:
- Listing
security:
- TrackerKey: []
- JWT: []
parameters:
- name: indexId
in: path
required: true
description: ID of the index to be used in the search operation
schema:
type: string
requestBody:
description: Request for item listing
required: true
content:
application/json:
schema:
type: object
properties:
page:
type: integer
format: int32
description: Page number to return for pagination. The first page has the index `1`.
limit:
type: integer
format: int32
example: 10
default: 20
maximum: 500
minimum: 0
description: The number of items to return per page
sortBy:
type: string
description: |
IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results.
Name of the attribute by which the data will be sorted.
ordering:
type: string
default: asc
enum:
- desc
- asc
description: Sorting order
includeMeta:
type: boolean
description: |
When `true`, pagination metadata is included in the response body.
When `false`, the data is included in the response headers:
- Link: links to neighbors, first, and last pages in pagination.
- X-Pagination-Total-Count: total number of items on all pages
- X-Pagination-Total-Pages: total number of pages
- X-Pagination-Page: current page
- X-Pagination-Limit: maximum number of items on a page
- X-Pagination-Sorted-By: parameter that the items were sorted by
- X-Pagination-Ordering: sorting direction
clientUUID:
type: string
description: UUID of the profile for which the search is performed
personalize:
type: boolean
description: If set to `false`, the search result is not personalized.
default: true
correlationId:
type: string
description: |
Correlation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used.
Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchId:
type: string
deprecated: true
description: |
**DEPRECATED - use correlationId instead**
Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used.
Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetric:
type: string
enum:
- TransactionsPopularity
- PageVisitsPopularity
description: |
IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results.
Name of the metric by which the data will be sorted.
sortByGeoPoints:
type: string
example: 34.052235,-118.243685
description: |
IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results.
Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
filterGeoPoints:
type: array
example:
- 34.052235,-118.243685
- 15.0,65.0
items:
type: string
description: |
The definition of a geographical area to filter by.
Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the `filterAroundRadius` parameter.
**Example input:** `["34.052235,-118.243685"]`
Given two geo-points, the results will be limited to a rectangular area.
**Example input:** `["50,-100", "25,150"]`
Given three or more geo-points, the results will be limited to a polygonal area.
**Example input:** `["50,0", "40,20", "-20,10"]`
filterAroundRadius:
type: integer
format: int32
example: 2000
default: 1000
description: Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters:
type: string
description: IQL query string. For details, see the [Help Center](https://help.synerise.com/developers/iql/).
facets:
type: array
description: |
A list of attributes for which facets will be returned.
- A single `*` value matches all facetable attributes.
- A single `auto` value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's `dynamicFacets` configuration.
To determine which groups of facets should be returned, use the `includeFacets` parameter.
items:
type: string
customFilteredFacets:
type: object
description: |
A key-value map that takes attributes as keys and IQL query strings as values.
For each key a facet is returned that includes only the items filtered by the provided IQL query string.
additionalProperties:
type: string
description: IQL query string. For details, see the [Help Center](https://help.synerise.com/developers/iql/).
example:
brand: price > 100
price: brand == foo
facetsSize:
type: integer
default: 2000
minimum: 1
maximum: 10000
description: |
Determines how many items will be used for facets aggregation.
maxValuesPerFacet:
type: integer
default: 50
minimum: 1
maximum: 1000
description: |
Determines how many values will be retrieved per facet.
caseSensitiveFacetValues:
type: boolean
default: false
description: |
Specifies whether facets aggregation should be case sensitive.
includeFacets:
type: string
default: filtered
enum:
- all
- filtered
- unfiltered
- none
description: |
Determines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all.
To determine which attributes should be returned as facets in each group, use the `facets` and `customFilteredFacets` parameters.
facetsOrderBy:
type: string
enum:
- coverage
- name
description: |
Controls the ordering of facets in the response.
When `facets=auto`, the default ordering is by coverage (most relevant facets first).
When facets are specified explicitly, the default ordering is by name.
When two facets have equal coverage, ties are resolved by name.
context:
type: array
description: List of context strings for a search query
example:
- mobile
- listing
items:
type: string
displayAttributes:
type: array
description: List of ad hoc attributes that will be returned for each found item
example:
- title
- price
items:
type: string
distinctFilter:
type: object
description: Distinct filters regulate how many items with the same value of a particular attribute can be returned.
properties:
attribute:
type: string
description: Name of the attribute to be used for distinct filter
maxNumItems:
type: integer
description: Maximum number of items to be returned per each distinct attribute value
minimum: 1
levelRangeModifier:
type: integer
description: Level of the category, if the category attribute was used for distinct filter
minimum: 0
required:
- attribute
- maxNumItems
ignoreQueryRules:
type: boolean
description: If set to `true`, query rules are not applied.
default: false
excludeQueryRules:
type: array
example:
- 2
- 5
items:
type: integer
description: List of query rules that will not be applied.
params:
type: object
example:
source: mobile
description: Extra parameters that will be added to the `item.search` event. The total size must not exceed 500 bytes.
additionalProperties: true
responses:
"200":
description: Listing result
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: A page of matching items as objects. The parameters of each item's object depend on the configuration of displayable attributes.
items:
type: object
properties:
_promotedByRules:
type: array
items:
type: integer
description: Rule id
description: List of applied rules that had an effect in promoting this item. This field exists if and only if the item was promoted.
additionalProperties:
description: The names and value types of the item's properties depend on the configuration.
example:
itemName: TV
itemId: 87257843345
_promotedByRules:
- 475
- 477
extras:
type: object
description: Additional information
properties:
filteredFacets:
type: object
description: Facet value mappings
example:
brand:
X-brand: 1
Y-brand: 3
salePrice.value:
max: 201.99
min: 14.99
additionalProperties:
description: The type of facet, for example `category`
type: object
additionalProperties:
description: 'The values for keys in this facet type, for example `"Home Appliances>Fridges": 12`'
type: integer
allFacets:
type: object
description: Facet value mappings
example:
brand:
X-brand: 1
Y-brand: 3
salePrice.value:
max: 201.99
min: 14.99
additionalProperties:
description: The type of facet, for example `category`
type: object
additionalProperties:
description: 'The values for keys in this facet type, for example `"Home Appliances>Fridges": 12`'
type: integer
customFilteredFacets:
allOf:
- type: object
description: Facets resulting from the `customFilteredFacets` setting. Only available in `POST` requests.
- type: object
description: Facet value mappings
example:
brand:
X-brand: 1
Y-brand: 3
salePrice.value:
max: 201.99
min: 14.99
additionalProperties:
description: The type of facet, for example `category`
type: object
additionalProperties:
description: 'The values for keys in this facet type, for example `"Home Appliances>Fridges": 12`'
type: integer
correlationId:
type: string
description: |
This ID is used:
- for search result pagination
- as `correlationId` of the search event in events such as `items.search.click`
Search results are cached for 10 minutes.
The cached value will be used if the ID is provided in subsequent calls. This makes search faster and eliminates personalization non-determinism.
searchId:
type: string
deprecated: true
description: |
**DEPRECATED - use correlationId instead**
This ID is used:
- for search result pagination
- as `searchId` of the search event in events such as `items.search.click`
Search results are cached for 10 minutes.
The cached value will be used if the ID is provided in subsequent calls. This makes search faster and eliminates personalization non-determinism.
facetsOrdering:
type: array
description: |
An ordered list of facet attribute names indicating the display order of facets in the response.
When `facets=auto`, facets are ordered by coverage (most relevant first) unless `facetsOrderBy=name` is specified.
When facets are specified explicitly, the ordering is by name.
Empty when no facets are requested.
Matching query rules can override the resulting set and order via two consequences:
- `pinFacets` forces specific facets into the response, optionally at a specific 1-based slot.
Pinned facets bypass the coverage threshold in `facets=auto`.
- `hideFacets` removes specific facets from the response, also stripping them from
`customFilteredFacets`. Hide takes precedence over pin and over explicit `facets=[...]`.
The corresponding facet values appear in `filteredFacets`, `allFacets`, and `customFilteredFacets`
only for attributes present in this list.
items:
type: string
example:
- brand
- color
- size
- price
meta:
type: object
description: Optional metadata, such as pagination. This is returned if the `includeMeta` parameter was set to true in the request.
properties:
totalPages:
type: number
description: The total number of pages
totalCount:
type: number
description: The total number of search results
page:
type: number
description: The current page
limit:
type: number
description: The maximal number of items on a page
sortedBy:
type: string
description: The column (attribute) that the campaigns were sorted by
ordering:
type: string
description: Sorting order
code:
type: number
description: HTTP response code
link:
type: array
description: Links to neighboring pages, first page, and last page in pagination
items:
type: object
properties:
url:
description: Page URL
type: string
rel:
type: string
description: Position of the linked page
enum:
- first
- next
- prev
- last
"500":
description: Service not available
content:
application/json:
schema:
type: object
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
status:
type: integer
description: Status code
error:
type: string
description: Summary of the error
message:
type: string
description: Description of the problem
path:
type: string
description: URL of the requested resource
required:
- timestamp
- status
- message
x-snr-doc-urls:
- /api-reference/ai-search#tag/Listing/operation/ListingPost
x-codeSamples:
- lang: cURL
label: cURL
source: |-
curl --request POST \
--url https://api.synerise.com/search/v2/indices/%7BindexId%7D/list \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'content-type: application/json' \
--data '{"page":0,"limit":10,"sortBy":"string","ordering":"desc","includeMeta":true,"clientUUID":"string","personalize":true,"correlationId":"string","searchId":"string","sortByMetric":"TransactionsPopularity","sortByGeoPoints":"34.052235,-118.243685","filterGeoPoints":["34.052235,-118.243685","15.0,65.0"],"filterAroundRadius":2000,"filters":"string","facets":["string"],"customFilteredFacets":{"brand":"price > 100","price":"brand == foo"},"facetsSize":2000,"maxValuesPerFacet":50,"caseSensitiveFacetValues":false,"includeFacets":"all","facetsOrderBy":"coverage","context":["mobile","listing"],"displayAttributes":["title","price"],"distinctFilter":{"attribute":"string","maxNumItems":1,"levelRangeModifier":0},"ignoreQueryRules":false,"excludeQueryRules":[2,5],"params":{"source":"mobile"}}'
- lang: Python
label: Python
source: |-
import http.client
conn = http.client.HTTPSConnection("api.synerise.com")
payload = "{\"page\":0,\"limit\":10,\"sortBy\":\"string\",\"ordering\":\"desc\",\"includeMeta\":true,\"clientUUID\":\"string\",\"personalize\":true,\"correlationId\":\"string\",\"searchId\":\"string\",\"sortByMetric\":\"TransactionsPopularity\",\"sortByGeoPoints\":\"34.052235,-118.243685\",\"filterGeoPoints\":[\"34.052235,-118.243685\",\"15.0,65.0\"],\"filterAroundRadius\":2000,\"filters\":\"string\",\"facets\":[\"string\"],\"customFilteredFacets\":{\"brand\":\"price > 100\",\"price\":\"brand == foo\"},\"facetsSize\":2000,\"maxValuesPerFacet\":50,\"caseSensitiveFacetValues\":false,\"includeFacets\":\"all\",\"facetsOrderBy\":\"coverage\",\"context\":[\"mobile\",\"listing\"],\"displayAttributes\":[\"title\",\"price\"],\"distinctFilter\":{\"attribute\":\"string\",\"maxNumItems\":1,\"levelRangeModifier\":0},\"ignoreQueryRules\":false,\"excludeQueryRules\":[2,5],\"params\":{\"source\":\"mobile\"}}"
headers = {
'Authorization': "Bearer REPLACE_BEARER_TOKEN",
'content-type': "application/json"
}
conn.request("POST", "/search/v2/indices/%7BindexId%7D/list", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
- lang: JavaScript
label: JavaScript
source: |-
const data = JSON.stringify({
"page": 0,
"limit": 10,
"sortBy": "string",
"ordering": "desc",
"includeMeta": true,
"clientUUID": "string",
"personalize": true,
"correlationId": "string",
"searchId": "string",
"sortByMetric": "TransactionsPopularity",
"sortByGeoPoints": "34.052235,-118.243685",
"filterGeoPoints": [
"34.052235,-118.243685",
"15.0,65.0"
],
"filterAroundRadius": 2000,
"filters": "string",
"facets": [
"string"
],
"customFilteredFacets": {
"brand": "price > 100",
"price": "brand == foo"
},
"facetsSize": 2000,
"maxValuesPerFacet": 50,
"caseSensitiveFacetValues": false,
"includeFacets": "all",
"facetsOrderBy": "coverage",
"context": [
"mobile",
"listing"
],
"displayAttributes": [
"title",
"price"
],
"distinctFilter": {
"attribute": "string",
"maxNumItems": 1,
"levelRangeModifier": 0
},
"ignoreQueryRules": false,
"excludeQueryRules": [
2,
5
],
"params": {
"source": "mobile"
}
});
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.synerise.com/search/v2/indices/%7BindexId%7D/list");
xhr.setRequestHeader("Authorization", "Bearer REPLACE_BEARER_TOKEN");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
- lang: Node.js
label: Node.js
source: |-
const http = require("https");
const options = {
"method": "POST",
"hostname": "api.synerise.com",
"port": null,
"path": "/search/v2/indices/%7BindexId%7D/list",
"headers": {
"Authorization": "Bearer REPLACE_BEARER_TOKEN",
"content-type": "application/json"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
page: 0,
limit: 10,
sortBy: 'string',
ordering: 'desc',
includeMeta: true,
clientUUID: 'string',
personalize: true,
correlationId: 'string',
searchId: 'string',
sortByMetric: 'TransactionsPopularity',
sortByGeoPoints: '34.052235,-118.243685',
filterGeoPoints: ['34.052235,-118.243685', '15.0,65.0'],
filterAroundRadius: 2000,
filters: 'string',
facets: ['string'],
customFilteredFacets: {brand: 'price > 100', price: 'brand == foo'},
facetsSize: 2000,
maxValuesPerFacet: 50,
caseSensitiveFacetValues: false,
includeFacets: 'all',
facetsOrderBy: 'coverage',
context: ['mobile', 'listing'],
displayAttributes: ['title', 'price'],
distinctFilter: {attribute: 'string', maxNumItems: 1, levelRangeModifier: 0},
ignoreQueryRules: false,
excludeQueryRules: [2, 5],
params: {source: 'mobile'}
}));
req.end();
- lang: PHP
label: PHP
source: |-
setUrl('https://api.synerise.com/search/v2/indices/%7BindexId%7D/list');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders([
'Authorization' => 'Bearer REPLACE_BEARER_TOKEN',
'content-type' => 'application/json'
]);
$request->setBody('{"page":0,"limit":10,"sortBy":"string","ordering":"desc","includeMeta":true,"clientUUID":"string","personalize":true,"correlationId":"string","searchId":"string","sortByMetric":"TransactionsPopularity","sortByGeoPoints":"34.052235,-118.243685","filterGeoPoints":["34.052235,-118.243685","15.0,65.0"],"filterAroundRadius":2000,"filters":"string","facets":["string"],"customFilteredFacets":{"brand":"price > 100","price":"brand == foo"},"facetsSize":2000,"maxValuesPerFacet":50,"caseSensitiveFacetValues":false,"includeFacets":"all","facetsOrderBy":"coverage","context":["mobile","listing"],"displayAttributes":["title","price"],"distinctFilter":{"attribute":"string","maxNumItems":1,"levelRangeModifier":0},"ignoreQueryRules":false,"excludeQueryRules":[2,5],"params":{"source":"mobile"}}');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
- lang: Java
label: Java
source: |-
HttpResponse response = Unirest.post("https://api.synerise.com/search/v2/indices/%7BindexId%7D/list")
.header("Authorization", "Bearer REPLACE_BEARER_TOKEN")
.header("content-type", "application/json")
.body("{\"page\":0,\"limit\":10,\"sortBy\":\"string\",\"ordering\":\"desc\",\"includeMeta\":true,\"clientUUID\":\"string\",\"personalize\":true,\"correlationId\":\"string\",\"searchId\":\"string\",\"sortByMetric\":\"TransactionsPopularity\",\"sortByGeoPoints\":\"34.052235,-118.243685\",\"filterGeoPoints\":[\"34.052235,-118.243685\",\"15.0,65.0\"],\"filterAroundRadius\":2000,\"filters\":\"string\",\"facets\":[\"string\"],\"customFilteredFacets\":{\"brand\":\"price > 100\",\"price\":\"brand == foo\"},\"facetsSize\":2000,\"maxValuesPerFacet\":50,\"caseSensitiveFacetValues\":false,\"includeFacets\":\"all\",\"facetsOrderBy\":\"coverage\",\"context\":[\"mobile\",\"listing\"],\"displayAttributes\":[\"title\",\"price\"],\"distinctFilter\":{\"attribute\":\"string\",\"maxNumItems\":1,\"levelRangeModifier\":0},\"ignoreQueryRules\":false,\"excludeQueryRules\":[2,5],\"params\":{\"source\":\"mobile\"}}")
.asString();
servers:
- description: Microsoft Azure EU
url: https://api.synerise.com
- description: Microsoft Azure USA
url: https://api.azu.synerise.com
- description: Google Cloud Platform
url: https://api.geb.synerise.com
tags:
- name: Listing
components:
securitySchemes:
TrackerKey:
type: apiKey
name: token
in: query
description: Authorization by tracker key sent as a query parameter. This is the same key as used in the website tracking code.
JWT:
type: http
scheme: bearer
description: |-
JWT Bearer token. The header looks like this: `Bearer {JWT}`
Remember to include the space between 'Bearer' and the token.
Generate a token via the **Authorization** endpoints.
```