return facetted recommendations for a user

11 Minutes to read

Print
Share
Dark
Light

return facetted recommendations for a user

11 Minutes to read

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback!

Post

/recommendations/facetted

The facetted recommendations api allows retrieval of the most recommended garments for a user. The result set can be filtered by specifying one or more filters. Optionally retrieval of information about the number of hits for other values of the filter are returned

The currently recognized aggregations are

garment_category
brand
occasion
must_have
retailer_labels (previously known as retailer_categories): significance dependent on retailer and data present in feed
store: if dressipi has been provided with per-store availability data, this filters or aggregates on availability by store
feature_ids (dressipi feature ids)
not_features_ids (dressipi feature ids). This returns results without any of the listed feature ids
price
reduced_by (range filter that accepts values from 0 to 100)

The retailer_labels aggregation allows you to query against fields in the product feed consumed by dressipi (these should be agreed with dressipi)

For example to request a garment category of 1 (dresses) submit

{
  "facets": [
    {
      "name": "garment_category",
      "value": [1]
    }
  ]
}

Multiple values can be passed for a single filter, these will be or-ed.

For example, to select garments that have all of

feature id 1 or 2,
feature id 3 or 4

submit

{
  "facets": [
    {
      "name": "feature_ids",
      "filters": [
        {"value": [1,2]},
        {"value": [3,4]}
      ]
    }
  ]
}

Multiple filters can be passed, these will be and-ed (Specifying multiple filters with the same name is not supported) For example, to return items matching a specific retailer label and available from a specific store, submit

{
  "facets": [
    {
      "name": "retailer_labels",
      "value": [1,2]
    },
    {
      "name": "store",
      "value": ["storeID1","storeID2"]
    }
  ]
}

If the size for a facet is set to non 0, count information will be returned about other filter values. Conceptually, the count returned in an agggregation bucket is the number of results you would get if the query was filtered by that aggregation value.

Numerical facets use a slightly different syntax, for example

{
  "facets": [
    {
      "name": "price",
      "filters": [
        {
          "from": 50,
          "to": 100
        }
      ],
      "ranges": [
        {"to": 50},
        {"from": 50, "to": 100},
        {"from": 100}
      ]
    }
  ]
}

returns items whose price between 50 (inclusive) and 100 and the number of results within each of the indicated price ranges.

{
  "facets": [
    {
      "name": "reduced_by",
      "filters": [
        {
          "from": 30
        }
      ]
    }
  ]
}

Returns items reduced by at least 30%

Depending on the garment_format requested, extra fields may be present on the garment, however garment_id and raw_garment_id will always be present

Security

API Key

Header parameter namex-api-key

API Key

Header parameter namex-dressipi-jwt

The JWT for the user

Query parameters

garment_format

string

The desired response format.

The response includes a description of the outfits / similar items but no data on the items themselves: since these may be repeated within the response, garment data is provided separately in the response.

The detailed format includes the most amount of item metadata (name, description, price etc).

The document format only includes item identifiers, and if requested dressipi generated information about the item, such as predicted size.

The retailer_ids format only returns the item identifiers.

Valid values[ "detailed", "document", "retailer_ids" ]

Default"retailer_ids"

fields

array of string

A list of garment attributes to fetch. Only supported for garment_format=document or detailed. Custom fields may be available - contact dressipi for details

pretty

boolean

If true, pretty print json output. This increases response size and should usually be off in production environments

include_dressipi_ids

boolean

Controls whether dressipi garment ids (raw_garment_id) are included in response

Defaulttrue

page

integer (int32)

The page from which to start results

Default1

per_page

integer (int32)

The number of result to return per page

Default12

device_type

string

A device type identifier. This allows segmenting a/b test statistics in the same way as you do.

locale

string

A locale parameter describing what stock information to use and what language to return text in (if applicable). This parameter will only function if the corresponding information is in the product feed & processed accordingly. If stock local and UI language are not the same, specify the language parameter in addition to this one.

language

string

Allows you to specify a locale used for feed attributes such as product name that should be localized using a different locale to price & stock information. This parameter will only function if the corresponding information is in the product feed & processed accordingly.

Body parameters

Expand All

object

return facetted recommendations for a user

root_event_id

string

When requesting the 2nd or later pages of recommendations, provide the root_event_id from the previous page

facets

Array of object

object

name

string Required

The name of the facet

Valid values[ "garment_category", "occasion", "must_have", "retailer_categories", "retailer_labels", "feature_ids", "not_feature_ids", "brand", "price", "store", "reduced_by", "product_ids" ]

value

Array of string

The values to filter by (deprecated in favor of the filters parameter)

string

Default"1"

size

integer (int32)

The number of facet entries to retrieve. The feature_ids and not_feature_ids facets do not support non zero sizes

Default0

filters

Array of object

An array of filters, that will be added together. Each filter has a value property which is the array of values to match against

object

value

Array of string

the array of permitted values

Example[ "1", "2", "3" ]

string

from

Array of integer

for numerical facets, the minimum value

integer (int32)

Array of integer

for numerical facets, the maximum value

integer (int32)

identifier_type

string

the type of identifiers in the value of a filter with name name, default is 'product-code' when unspecified

Valid values[ "dressipi-id", "product-code", "ancillary-product-code" ]

ranges

Array of object

For numerical facets, a list of ranges for which to retrieve counts

object

from

integer (int64)

identifier_type

string

the type of identifiers in the value of a filter with name name, default is 'product-code' when unspecified

Valid values[ "dressipi-id", "product-code", "ancillary-product-code" ]

Responses

200

Information about the recommended garments

Expand All

object

Retrieve items that the user has previously liked filtered by garment category.

For example to request a garment category of 1 (dresses) submit

{
  "facets": [
    {
      "name": "garment_category",
      "value": [1]
    }
  ]
}

Example{ "event_id": "5b36697489560a0060000009", "reparentable": false, "content_id": "5b36697489560a006000000a", "recommendations": [ { "garment_id": "01AC017NAV", "raw_garment_id": 4508067, "ancillary_product_code": "N-111", "garment_category_id": 42, "garment_category_name": "Dresses", "department": "female", "has_outfits": true, "has_extended_verdicts": true, "size": { "exact": [ "5", "UK 10" ], "plus_one": [ "6", "UK 12" ], "minus_one": [ "4", "UK 8" ] }, "verdict": true, "owned": false, "why": [ "A neat slim leg flatters your slender shape", "A hint of flare helps to balance out your shoulders." ], "occasions": [ "casual", "holiday" ], "recommendedness": { "score": 8, "reason": "Good for you" }, "features": [ { "id": 1, "name": "Basic", "feature_category_name": "Wardrobe" }, { "id": 2, "name": "A/W 2020", "feature_category_name": "Season" } ], "feed_image_urls": [ "https://assets.retailer.com/images/01AC017NAV", "https://assets.retailer.com/images/01AC017NAV" ], "eans": [ "ABCD01", "ABCD02", "ABCD03" ], "brand_name": "Some Brand", "retailer": "Some Retailer", "name": "Black Maxi dress", "price": "35.00 GBP", "old_price": "35.00 GBP", "url": "https://www.someretailer.com/dresses/01AC017NAV", "garment_status": "in stock", "custom_attributes": [ { "name": "retailer_specific_attribute_1", "value": "abcedfg", "array_value": [] } ] }, { "garment_id": "05AC011MUL", "raw_garment_id": 4508222, "ancillary_product_code": "M-222", "garment_category_id": 42, "garment_category_name": "Dresses", "department": "female", "has_outfits": true, "has_extended_verdicts": true, "size": { "exact": [ "5", "UK 10" ], "plus_one": [ "6", "UK 12" ], "minus_one": [ "4", "UK 8" ] }, "verdict": true, "owned": false, "why": [ "A neat slim leg flatters your slender shape", "A hint of flare helps to balance out your shoulders." ], "occasions": [ "casual", "holiday" ], "recommendedness": { "score": 8, "reason": "Good for you" }, "features": [ { "id": 1, "name": "Basic", "feature_category_name": "Wardrobe" }, { "id": 2, "name": "A/W 2020", "feature_category_name": "Season" } ], "feed_image_urls": [ "https://assets.retailer.com/images/01AC017NAV", "https://assets.retailer.com/images/01AC017NAV" ], "eans": [ "ABCD01", "ABCD02", "ABCD03" ], "brand_name": "Some Brand", "retailer": "Some Retailer", "name": "Black Maxi dress", "price": "35.00 GBP", "old_price": "35.00 GBP", "url": "https://www.someretailer.com/dresses/01AC017NAV", "garment_status": "in stock", "custom_attributes": [ { "name": "retailer_specific_attribute_1", "value": "abcedfg", "array_value": [] } ] }, { "garment_id": "05AC018MUL", "raw_garment_id": 4508225, "ancillary_product_code": "M-333", "garment_category_id": 42, "garment_category_name": "Dresses", "department": "female", "has_outfits": true, "has_extended_verdicts": true, "size": { "exact": [ "5", "UK 10" ], "plus_one": [ "6", "UK 12" ], "minus_one": [ "4", "UK 8" ] }, "verdict": true, "owned": false, "why": [ "A neat slim leg flatters your slender shape", "A hint of flare helps to balance out your shoulders." ], "occasions": [ "casual", "holiday" ], "recommendedness": { "score": 8, "reason": "Good for you" }, "features": [ { "id": 1, "name": "Basic", "feature_category_name": "Wardrobe" }, { "id": 2, "name": "A/W 2020", "feature_category_name": "Season" } ], "feed_image_urls": [ "https://assets.retailer.com/images/01AC017NAV", "https://assets.retailer.com/images/01AC017NAV" ], "eans": [ "ABCD01", "ABCD02", "ABCD03" ], "brand_name": "Some Brand", "retailer": "Some Retailer", "name": "Black Maxi dress", "price": "35.00 GBP", "old_price": "35.00 GBP", "url": "https://www.someretailer.com/dresses/01AC017NAV", "garment_status": "in stock", "custom_attributes": [ { "name": "retailer_specific_attribute_1", "value": "abcedfg", "array_value": [] } ] } ], "facets": [ { "name": "garment_category", "buckets": [ { "id": "6", "name": "Tops", "count": 137 }, { "id": "8", "name": "Jeans", "count": 100 } ] } ], "pagination": { "total_pages": 13, "total_entries": 39, "current_page": 1 } }

event_id

string

An event id. This should be used when posting events relating to this dataset.

Example5a621005c2c9adc12e1192b7

reparentable

boolean

If true, the eventid should be posted to /events//reparent

content_id

string

An opaque identifier identifying this section of the response. This should be used when posting events relating to an item in this outfit.

Example5a621005c2c9adc12e1192b7

recommendations

Array of object (Garment)

The recommended items

object

Fetches information about a garment. The garment format is implicitly set to detailed.

Example{ "garment_id": "01AC017NAV", "raw_garment_id": 4508067, "ancillary_product_code": "N-1-D-1111", "garment_category_id": 42, "garment_category_name": "Dresses", "department": "female", "has_outfits": true, "has_extended_verdicts": true, "size": { "exact": [ "5", "UK 10" ], "plus_one": [ "6", "UK 12" ], "minus_one": [ "4", "UK 8" ] }, "verdict": true, "owned": false, "why": [ "A neat slim leg flatters your slender shape", "A hint of flare helps to balance out your shoulders." ], "occasions": [ "casual", "holiday" ], "recommendedness": { "score": 8, "reason": "Good for you" }, "eans": [ "ABCD01", "ABCD02", "ABCD03" ], "features": [ { "id": 1, "name": "Basic", "feature_category_name": "Wardrobe" }, { "id": 2, "name": "A/W 2020", "feature_category_name": "Season" } ], "feed_image_urls": [ "https://assets.retailer.com/images/01AC017NAV", "https://assets.retailer.com/images/01AC017NAV" ], "brand_name": "Some Brand", "retailer": "Some Retailer", "name": "Black Maxi dress", "price": "35.00 GBP", "old_price": "35.00 GBP", "url": "https://www.someretailer.com/dresses/01AC017NAV", "garment_status": "in stock", "custom_attributes": [ { "name": "retailer_specific_attribute_1", "value": "abcedfg", "array_value": [] } ] }

garment_id

string

The garment_id. The type of identifier used depends on the requests' garment_format

ExampleABC-123

raw_garment_id

integer (int32)

The internal dressipi id for the garment. This may be omitted depending on garment_format

Example123456

ancillary_product_code

string

An alternative identifier to identify the product, hidden when not provided in feed

ExampleA1B2C3

has_extended_verdicts

boolean

Whether garment has extended verdicts. Only presents for verdicts/dislikes, also not present if format=retailer_ids

ExampleTrue

has_outfits

boolean

Whether outfits can be generated. not present if format=retailer_ids

size

object (Sizing)

exact

Array of string

Information about the recommended size

string

plus_one

Array of string

Information about size immediately bigger than the recommended one (if available)

string

minus_one

Array of string

Information about size immediately smaller than the recommended one (if available)

string

why

Array of string

If whys have been requested & if the profile has shape data, a list of human readable reasons for recommendation

string

verdict

boolean

If verdicts have been requested, the approval status of the garment (true=like, false=dislike, nil=no verdict given)

owned

boolean

If owned has been requested, whether the use has previously purchased the product

recommendedness

object (Recommendedness)

score

integer (int32)

A numerical score for the garment (out of 10)

reason

string

A human readable interpretation of the score

features

Array of object (BasicFeature)

If features have been requested, a list of whitelisted feature objects

object

integer (int32)

The id for the feature

Example170

name

string

The human readable name for the feature

ExamplePlain Pattern

feature_category_name

string

The feature category of the feature

ExamplePattern

garment_category_id

integer (int32)

The category id for the product.

department

string

The garment department (female male girls boys).

eans

Array of string

If eans have been requested, the array of eans present in the product feed.

string

garment_category_name

string

The category name for the product.

occasions

Array of string

Array of the product occasions. Only present if format=detailed

string

retailer

string

The retailer name for the product. Only present if format=detailed

feed_image_urls

Array of string

The array of image_urls present in the product feed. Only present if format=detailed

string

brand_name

string

The brand name for the product. Only present if format=detailed

name

string

The product name. Only present if format=detailed

price

string

The current price, as it appears in the feed. Only present if format=detailed

old_price

string

The previous price, as it appears in the feed. Only present if format=detailed

url

string

The URL for the PDP for the garment. Only present if format=detailed

garment_status

string

The status of the garment. Only present if format=detailed

custom_attributes

Array of object (CustomAttribute)

Product feed attributes, as agreed with dressipi

object

name

string

The name of the attribute

value

string

The value of the attribute (if string valued)

array_value

Array of string

The value of the attribute (if array valued)

string

facets

Array of object (Facet)

The requested facet information

object

name

string

The name of the facet

Examplegarment_category_id

buckets

Array of object (Bucket)

The returned buckets for the facet

object

string

For non numeric facets, the id of the bucket, usable as search values in subsequent requests

Example1

name

string

For non numeric facets, a human readable description of the bucket

ExampleDresses

count

integer (int32)

The approximate number of items matching the value

Example19

from

integer (int64)

For numeric facets, the lower endpoint of the bucket

integer (int64)

For numeric facets, the upper endpoint of the bucket

pagination

object (Pagination)

total_pages

integer (int32)

The total number of pages that can be requested

total_entries

integer (int32)

The total number of results that can be requested

current_page

integer (int32)

The current page

422

error message

Expand All

object

Generic error object

error

object

message

string

A human readable error message

Was this article helpful?

What's Next

return themed recommendations for a user