Constructor Recommendations API
AI-optimized recommendation results retrieved by pod identifier for onsite recommendation placements.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@constructor.io
title: Recommendations
version: '0.1'
servers:
- url: https://ac.cnstrc.com
security: []
tags:
- name: Search results
- name: Natural language search results
- name: Autocomplete results
- name: Browse results
- name: Browse groups
- name: Browse facets
- name: Browse collections
- name: Recommendation results
paths:
/recommendations/v1/pods/{pod_id}:
get:
tags:
- Recommendation results
operationId: v1-recommendations-get-pod-results
summary: Retrieve by pod
description: Retrieve AI optimized recommendation results for products (or optionally other sections) by pod identifier. To learn more about pods, go [here](/docs/products-recommendations-learn-about-recommendations#pods).
parameters:
- name: pod_id
in: path
required: true
schema:
type: string
- name: key
in: query
schema:
description: The key of the index to use.
examples:
- key_K2pX7vBnU0bgA5xp
title: Key
maxLength: 100
minLength: 1
type: string
required: true
- name: section
in: query
schema:
description: The section of the index to use. Defaults to `Products`.
examples:
- Products
- Search Suggestions
title: Section
maxLength: 100
minLength: 1
type: string
required: false
- name: item_id
in: query
schema:
anyOf:
- type: string
- items:
type: string
type: array
description: 'The ID of the item to recommend additional items for. This parameter is required for the following recommendation strategies
* `alternative_items`
* `complementary_items`
* `bundles`
* `custom_item_item`'
title: Item Id
required: false
- name: variation_id
in: query
schema:
anyOf:
- type: string
- items:
type: string
type: array
description: The ID of the item variation to recommend additional items for. This parameter can be used with exactly one item_id specified in the request and is not required.
title: Variation ID
required: false
- name: term
in: query
schema:
description: 'The term to recommend items for. This parameter is required for the following recommendation strategies
* `query_recommendations`'
title: Term
maxLength: 100
minLength: 0
type: string
required: false
- name: filters
in: query
schema:
description: 'Any number of filtering criteria (accessible to end users) used to narrow the result set, such as `color=blue` or `group_id=sandals` or `price=100-200`. Facets and Item Groups and Collections can be used as filters. If `filter_value` has the form `<min>-<max>`, it is interpreted as a range. Filters with the same key are ORed together and filters with different keys are ANDed together by default. Only results that match the filters are returned.
This parameter is required for the following recommendation strategies
* `filtered_items`'
allOf:
- $ref: '#/components/schemas/Filters'
title: Filters
required: false
style: deepObject
explode: true
- name: filter_match_types
in: query
schema:
description: 'An object specifying whether results must match `all`, `any` or `none` of a given filter when multiple options of the same facet (e.g: color: yellow & blue) are selected.'
examples:
- color: any
size: all
title: Filter Match Types
additionalProperties:
$ref: '#/components/schemas/FilterMatchType'
type: object
required: false
style: deepObject
explode: true
- name: pre_filter_expression
in: query
schema:
description: A JSON Object containing any number of filters (inaccessible to end users) used to narrow the result set. Applied before filters accessible to end users. Only results that match the filters are returned.
allOf:
- $ref: '#/components/schemas/DictOrJsonStringWithDict'
title: Pre Filter Expression
required: false
- name: num_results
in: query
schema:
default: 10
description: The maximum number of recommended items to retrieve
maximum: 100
minimum: 0
title: Num Results
type: integer
required: false
- name: now
in: query
schema:
description: A date time representing the current moment in time when applying filtering by product age. Used to emulate "past/future" requests. Requires authentication.
examples:
- '2024-01-15T10:30:00Z'
title: Now
format: date-time
type: string
required: false
- name: variations_map
in: query
schema:
description: A JSON string containing a instructions on how to map item variation data in the response (typically used for swatches). More details, including the exact schema for this value can be found [here](/reference/shared-variations-mapping)
format: json
title: Variations Map
type: string
allOf:
- $ref: '#/components/schemas/VariationsMap'
required: false
- name: fmt_options
in: query
schema:
description: An object containing options to format the results returned
allOf:
- $ref: '#/components/schemas/FmtOptions'
title: Fmt Options
required: false
style: deepObject
explode: true
- name: origin_referrer
in: query
schema:
description: The url or app location where the request originated.
title: Origin Referrer
type: string
required: false
- name: c
in: query
schema:
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
title: C
maxLength: 100
minLength: 1
type: string
required: false
- name: us
in: query
schema:
description: User segment is a client context value (such as platform, location, etc.) that is used to evaluate redirect or refined tag rules. You can supply multiple segments by passing multiple `us` arguments.
title: us
items:
minLength: 1
type: string
type: array
required: false
- name: ui
in: query
schema:
description: 'A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices.
At least one of the parameters `i` or `ui` is required for the following recommendation strategies
* `recently_viewed_items`
* `user_featured_items`
* `abandoned_in_cart`
* `custom_user_item`'
title: Ui
type: string
required: false
- name: s
in: query
schema:
description: An integer representing the users session number (starting with `1`), incremented after a 30 minute period of inactivity.
title: S
type: integer
required: false
- name: sl
in: query
schema:
description: SL data
title: Sl
additionalProperties:
type: string
type: object
required: false
- name: i
in: query
schema:
description: 'A globally unique identifier for the user browser (or mobile application instance) making the request.
At least one of the parameters `i` or `ui` is required for the following recommendation strategies
* `recently_viewed_items`
* `user_featured_items`
* `abandoned_in_cart`'
title: I
type: string
required: false
- name: q
in: query
schema:
deprecated: true
description: '**DEPRECATED. Please, use `term` instead**'
title: Q
maxLength: 100
minLength: 0
type: string
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RecommendationsPodsGetResponse'
'400':
description: Validation Error
'404':
description: Not Found
security: []
components:
schemas:
DictOrJsonStringWithDict:
anyOf:
- title: object
type: object
- format: json
title: Encoded JSON string
type: string
title: DictOrJsonStringWithDict
FacetOptionSortOrder:
enum:
- relevance
- value
- num_matches
title: FacetOptionSortOrder
type: string
FilterMatchType:
enum:
- any
- all
- none
title: FilterMatchType
type: string
Filters:
propertyNames:
minLength: 1
title: Filters
type: object
FmtOptions:
additionalProperties: false
properties:
fields:
description: A list of specific item fields to return in the response. Allows the request to control which fields are returned.
title: Fields
items:
maxLength: 300
minLength: 1
type: string
examples:
- image_url
- price
- brand
maxItems: 20
type: array
show_hidden_fields:
default: false
description: A flag to return all `hidden` fields in the response.
examples:
- false
- true
title: Show Hidden Fields
type: boolean
hidden_fields:
description: A list of specific hidden fields to return in the response. Unlike `show_hidden_fields` this parameter allows the request to control which `hidden` fields are returned. Used to return item fields for a particular store or user segment.
title: Hidden Fields
items:
maxLength: 300
minLength: 1
type: string
examples:
- inventory_count
- store_availability
maxItems: 30
type: array
variations_return_type:
description: A flag to return `default`, `all`, or `matched` variations.
examples:
- default
allOf:
- $ref: '#/components/schemas/VariationsReturnType'
groups_max_depth:
default: 1
description: The maximum depth of the group hierarchy in the response.
examples:
- 1
- 3
title: Groups Max Depth
type: integer
groups_start:
default: current
description: A flag to specify the start of the group hierarchy returned in the response. `current` returns groups starting from the currently selected one. `top` returns groups starting from the root category in the hierarchy. `group_id:{id}`, returns the whole tree starting from group with the provided ID.
examples:
- current
- top
- group_id:jeans
title: Groups Start
type: string
groups_sort_by:
description: A string indicating the option to sort results by. Sorting options are created from item fields and facets in the product catalog.
examples:
- relevance
allOf:
- $ref: '#/components/schemas/FacetOptionSortOrder'
groups_sort_order:
description: A flag to sort either `ascending` or `descending`.
examples:
- descending
allOf:
- $ref: '#/components/schemas/SortOrderType'
show_hidden_facets:
default: false
description: A flag to return all facets configured as `hidden` in `response.facets`.
examples:
- false
- true
title: Show Hidden Facets
type: boolean
hidden_facets:
description: A list of specific hidden facets to return in the response. Unlike `show_hidden_facets` this parameter allows the request to control which hidden facets are returned. Used to return facets for a particular store or user segment.
title: Hidden Facets
items:
maxLength: 100
minLength: 1
type: string
examples:
- store_id
- region
maxItems: 50
type: array
show_hidden_facet_options:
description: A flag to return all `hidden` facets options in the response.
examples:
- true
- false
title: Show Hidden Facet Options
type: boolean
show_protected_facets:
default: false
description: A flag to return all `protected` facets in the response. Requires authentication.
examples:
- false
- true
title: Show Protected Facets
type: boolean
facet_options:
description: A list of specific facet options per facet to return in the response. This parameter accepts up to 5 facets and works only with facets of type `multiple`. Invalid facet options will be ignored. Used to return facet options for a particular facet like store or user segment.
examples:
- brand:
- nike
- adidas
color:
- red
- blue
title: Facet Options
additionalProperties:
items:
maxLength: 100
minLength: 1
type: string
maxItems: 15
type: array
type: object
facet_groups_limit:
description: The maximum limit of the facet groups returned in the response.
examples:
- 10
title: Facet Groups Limit
minimum: 0
type: integer
show_hidden_sort_options:
description: A flag to return all sort options configured as `hidden` in `response.sort_options`.
examples:
- true
- false
title: Show Hidden Sort Options
type: boolean
hidden_sort_options:
description: A list of `sort_by` fields whose hidden sort options should be included in the response. Unlike `show_hidden_sort_options` this parameter allows you to specify exactly which hidden sort options are returned.
title: Hidden Sort Options
items:
maxLength: 100
minLength: 1
type: string
examples:
- price
- rating
maxItems: 25
type: array
title: FmtOptions
type: object
SortOrderType:
enum:
- ascending
- descending
title: SortOrderType
type: string
VariationsMap:
properties:
filter_by:
description: A filtering expression that should be used to filter variations before doing any aggregations
allOf:
- $ref: '#/components/schemas/VariationsMapFilterBy'
title: Filter By
group_by:
description: An array of fields that should be used to group variations. Variations which share the value of all fields specified here will all fall under one group
title: Group By
items:
$ref: '#/components/schemas/VariationsMapGrouping'
maxItems: 5
type: array
values:
description: A set of aggregations that should be applied to each variation group. The object keys specify the name of the field under which each aggregated value will be returned in the response
title: Values
type: object
additionalProperties:
discriminator:
mapping:
all: '#/components/schemas/VariationsMapSimpleAggregation'
count: '#/components/schemas/VariationsMapCountAggregation'
distinct: '#/components/schemas/VariationsMapSimpleAggregation'
field_count: '#/components/schemas/VariationsMapSimpleAggregation'
first: '#/components/schemas/VariationsMapSimpleAggregation'
max: '#/components/schemas/VariationsMapSimpleAggregation'
min: '#/components/schemas/VariationsMapSimpleAggregation'
value_count: '#/components/schemas/VariationsMapValueCountAggregation'
propertyName: aggregation
oneOf:
- $ref: '#/components/schemas/VariationsMapSimpleAggregation'
- $ref: '#/components/schemas/VariationsMapCountAggregation'
- $ref: '#/components/schemas/VariationsMapValueCountAggregation'
dtype:
description: The expected data type of the variations_map objects in the response
enum:
- array
- object
title: Dtype
type: string
required:
- values
- dtype
title: VariationsMap
type: object
VariationsMapAnd:
additionalProperties: false
properties:
and_:
items:
type: array
title: And
type: array
required:
- and_
title: VariationsMapAnd
type: object
VariationsMapCountAggregation:
properties:
aggregation:
title: Aggregation
type: string
enum:
- count
required:
- aggregation
title: VariationsMapCountAggregation
type: object
VariationsMapFilterBy:
discriminator:
mapping:
and: '#/components/schemas/VariationsMapAnd'
not: '#/components/schemas/VariationsMapNot'
or: '#/components/schemas/VariationsMapOr'
range: '#/components/schemas/VariationsMapRange'
single: '#/components/schemas/VariationsMapSingleFilter'
propertyName: type
oneOf:
- $ref: '#/components/schemas/VariationsMapRange'
- $ref: '#/components/schemas/VariationsMapSingleFilter'
- $ref: '#/components/schemas/VariationsMapOr'
- $ref: '#/components/schemas/VariationsMapAnd'
- $ref: '#/components/schemas/VariationsMapNot'
title: VariationsMapFilterBy
VariationsMapGrouping:
properties:
name:
pattern: ^\w+([ ]?[\w]+)*$
title: Name
type: string
field:
minLength: 1
title: Field
type: string
required:
- name
- field
title: VariationsMapGrouping
type: object
VariationsMapNot:
additionalProperties: false
properties:
not_:
type: object
title: Not
required:
- not_
title: VariationsMapNot
type: object
VariationsMapOr:
additionalProperties: false
properties:
or_:
items:
type: array
title: Or
type: array
required:
- or_
title: VariationsMapOr
type: object
VariationsMapRange:
additionalProperties: false
properties:
field:
description: Path to a metadata field (dot-separated)
minLength: 1
title: Field
type: string
range:
description: This filter matches items where the specified field is within the specified range (min and max). The values are inclusive. Use "inf" for an unbounded upper limit or "-inf" for an unbounded lower limit.
items:
anyOf:
- enum:
- inf
- -inf
type: string
- type: integer
- type: number
maxItems: 2
minItems: 2
title: Range
type: array
required:
- field
- range
title: VariationsMapRange
type: object
VariationsMapSimpleAggregation:
properties:
aggregation:
enum:
- first
- all
- distinct
- min
- max
- field_count
title: Aggregation
type: string
field:
minLength: 1
title: Field
type: string
required:
- aggregation
- field
title: VariationsMapSimpleAggregation
type: object
VariationsMapSingleFilter:
additionalProperties: false
properties:
field:
description: Path to a metadata field (dot-separated)
minLength: 1
title: Field
type: string
value:
anyOf:
- type: boolean
- type: integer
- type: number
- type: string
description: The value of this field to filter by
title: Value
required:
- field
- value
title: VariationsMapSingleFilter
type: object
VariationsMapValueCountAggregation:
properties:
aggregation:
title: Aggregation
type: string
enum:
- value_count
field:
minLength: 1
title: Field
type: string
value:
anyOf:
- type: boolean
- type: integer
- type: number
- type: string
title: Value
required:
- aggregation
- field
- value
title: VariationsMapValueCountAggregation
type: object
VariationsReturnType:
enum:
- default
- all
- matched
title: VariationsReturnType
type: string
RecommendationsPodsGetResponse:
additionalProperties: false
properties:
request:
description: The request arguments how they were interpreted by the API. This field is of arbitrary type, ie it doesn't have a guaranteed schema, and data from it shouldn't be used programmatically, it is for debugging purposes only.
title: Request
type: object
result_id:
title: Result Id
type: string
response:
$ref: '#/components/schemas/PodEndpointResponseField'
required:
- request
- response
title: RecommendationsPodsGetResponse
type: object
DataField:
properties:
id:
title: Id
type: string
variation_id:
title: Variation Id
type: string
required:
- id
title: DataField
type: object
PodEndpointResponseField:
properties:
results:
items:
$ref: '#/components/schemas/ResultField'
title: Results
type: array
total_num_results:
title: Total Num Results
type: integer
pod:
$ref: '#/components/schemas/PodField'
required:
- results
- total_num_results
- pod
title: PodEndpointResponseField
type: object
PodField:
properties:
id:
title: Id
type: string
display_name:
title: Display Name
type: string
channels:
title: Channels
items:
type: string
type: array
required:
- id
- display_name
title: PodField
type: object
ResultField:
properties:
data:
$ref: '#/components/schemas/DataField'
value:
title: Value
type: string
is_slotted:
title: Is Slotted
type: boolean
labels:
default: {}
title: Labels
type: object
strategy:
$ref: '#/components/schemas/StrategyField'
required:
- data
- value
- is_slotted
title: ResultField
type: object
StrategyField:
properties:
id:
title: Id
type: string
type:
title: Type
type: string
required:
- id
title: StrategyField
type: object
securitySchemes:
http_basic_auth:
type: http
scheme: basic
http_bearer_auth:
type: http
scheme: bearer
x-readme:
explorer-enabled: false