Halla I/O (2.0.0)

Download OpenAPI specification:Download

Authentication

api_key

Security Scheme Type API Key
Query parameter name: key

Get Products

Real-time, contextual product recommendation, substitution, and search. Returns a list of products with attached relevance scores.

Authorizations:
query Parameters
strategy
required
string
Enum: "recommend" "substitute" "search"

Determines which service should be used for this request.

text
string

Required parameter when strategy is set to search. Value is the consumer-entered text to be searched. Must be sent URL encoded, e.g. "mango mochi" > "mango%20mochi"

productId
string

Subscriber specific product identifier to recommend based on. Required for substitution strategy.

cartProductIds
string

A comma delimited string of subscriber specific product identifiers for a consumer's current cart. If productId is not passed in the query, then recommendations will be based on the cartProductIds. If a productId is passed in the query, then cartProductIds will be used to improve recommendation relevance.

consumerId
string

Subscriber specific consumer identifier to personalize recommendations. If productId and cartProductIds are not passed in the query, then recommendations will be based on previous consumer behavior.

storeId
string

Subscriber specific store identifier, selecting the catalog of products to recommend from. If storeId is invalid or is not passed in the query, then recommendations will be sourced from the subscriber's master product list.

placement
string

Field to specify where these results are being placed in the UI. e.g. ‘checkout page’ or ‘home page sponsored container’”.

  • Used to obtain granularity into how each use case is performing.
  • If a configuration is previously created by a subscriber for a given placement, this field will link the request to use those configuration params if they are not explicitly provided in the request.
limit
integer

Upper bound on the number of products to return.

  • Defaults to 15.
  • Max is 100.
relevanceThreshold
number

This number defines the minimum raw relevance score (before any subscriber facing normalization is applied) required for an item to make it into the results. Relevance depends on the use case and any additional biases / filters but is usually between 0 and 1.

  • Defaults to 0.0.
candidateGenerationMethod
string
Enum: "PRODUCT" "CART" "CONSUMER" "SUPPORT"

This enum determines the ordering of how results are generated.

  • Note that if no generation method is specified, then results will be generated in a default manner based on the request params.

For example:

  • If "PRODUCT" is enabled, then results will first be generated by product affinity before secondary affinities are applied.
  • If "CART" is enabled, then results will first be generated by cart affinity before secondary affinities are applied.
  • If "CONSUMER" is enabled, then results will first be generated by consumer affinity before secondary affinities are applied.
  • If "SUPPORT" is enabled, then results will first be generated by product purchase frequency before secondary affinities are applied.
contextToPersonalizationRatio
number

This number between 0-1 determines how much Halla uses secondary context to determine the ranking of results for a given use case.

  • Defaults to 0.91.

For example:

  • If a subscriber is using Halla to power recommendations on the cart page and first generates candidates by CART, then this number determines how much to adjust these candidate recommendations by consumer preference.
  • As this number decreases, more weight is given to secondary context.
queryAdjusted
boolean

This boolean determines whether or not Halla uses its NLP substitution engine to group products together to transfer popular product affinities to rarer items.

  • Defaults to false.

For example:

  • If set to true, then a rarely purchased "Tequila" will have its affinities updated by its most substitutable products that do have adequate purchase information on them.
  • If set to false, then products will only use their sku level information to determine the ranking of results.
candidatesNormalized
boolean

This boolean determines whether or not Halla uses product order frequency in a given set of results.

  • Defaults to false.

For example:

  • If set to true, then Halla uses product order frequencies as a feature to best approximate purchasing likelihood.
  • If set to false, then every product should have a roughly equal probability of appearing in a set of results.
maxNormalized
boolean

This boolean determines whether or not Halla normalizes the raw final results by the max value returned.

  • Defaults to false.

For example:

  • If set to true, then the first result will always have a score of 1.0. This is useful if a client wants to know the relative scores inside of a given set of results.
  • If set to false, then results will contain their raw scores. This is useful if a client wants to know absolute scores across sets of results. However, as models change frequently, this number is not guaranteed to stay consistent.
attributeBias
string

This parameter lets a client add biases on Categories, Brands, and / or Tags which allow the Halla models to adjust results to meet merchandising needs.

  • Use an encoded pipe (i.e. %7C) to separate the attribute text and the bias value.
  • Biases will be added to the raw relevance score to adjust ordering of results. Note that biases can also be negative to move certain products down in the results list.
  • Each bias must have one of the following attribute types prepended to the desired attribute value.
    • "Tag:", "Category:", or "Brand:"
  • The Halla system does require an exact match between the desired bias and the product data that is sent to the system.
  • Clients can add as many biases as desired and biases will sum together when applicable.
  • Data must be sent URL encoded, e.g. "GRAINS/CEREALS" > "GRAINS%2FCEREALS".
  • Defaults to none.

For example:

  • To add a brand bias of 0.25 and a category bias of 0.15 attach &attributeBias=Brand:Tide%7C0.25&attributeBias=Category:Pantry%7C0.15 to the request.
pastPurchaseBias
number

This number determines how much Halla positively biases products that a user has previously purchased.

  • This is designed for use cases where reordering a product is useful for the shopper, such as search.
  • Defaults to 0.0.

For example:

  • If .1 is set here, then previously purchased products will get a boost of .1 to their resulting scores.
resultOntologicalVariationBias
number

This number defines how much Halla negatively biases results for duplicate / redundant products in a set of recommendations.

  • Halla uses its NLP engine to determine product similarity and negative biases will be applied based on the degree of similarity between two products.
  • This feature will negatively bias hummus in a result set if a different hummus is already present.
  • Defaults to 0.0.

For example:

  • If this number is set to .3 for cart page recommendations, then Halla will add a negative bias of .3 when a product is similar to something that is already in the results set.
resultVectorVariationBias
number

This number defines how much Halla negatively biases results from the same purchasing space.

  • This is useful to spread out cart recommendations to account for multiple co-occurrence clusters in a single set of results.
  • This feature will negatively bias salsa in a result set if tortilla chips are already present.
  • Defaults to 0.0.

For example:

  • If this number is set to .3 for cart page recommendations, then Halla will add a negative bias of .3 when a product is purchased in a similar cluster to something already in the set of recommendations.
queryOntologicalVariationBias
number

This number defines how much Halla negatively biases results for duplicate / redundant products that appear in the query.

  • Halla uses its NLP engine to determine product similarity and negative biases will be applied based on the degree of similarity between two products.
  • Defaults to 0.0.

For example:

  • If this number is set to .3 for cart page recommendations, then Halla will add a negative bias of .3 when a product is similar to something in the consumers cart.
consumerEngagementFilter
string
Enum: "PREVIOUSLY_PURCHASED" "NEVER_PURCHASED" "ALL"

Filter to further restrict the domain of response products based on whether or not they have been engaged with by said customer.

  • Note that products contained in productId and cartProductIds request fields are removed by default.
  • Defaults to ALL.

For example:

  • ALL will not restrict the domain.
  • PREVIOUSLY_PURCHASED will restrict the domain to just products that a consumer has previously purchased, if consumerId is invalid no products will be returned.
  • NEVER_PURCHASED will restrict the domain to just products that a consumer has not previously purchased, if consumerId is invalid this filter will not be applied.
attributeFilter
string

This parameter lets a client add filters to Categories, Brands, and / or Tags which allow the Halla models to filter results to just those products that match the filter conditions.

  • Use multiple filter parameters to filter by multiple attributes using and logic.
  • Use an encoded pipe (i.e. %7C) to filter by multiple attributes using or logic.
  • Use an encoded exclamation mark (i.e. %21) to exclude attributes using not logic.
  • Each filter must have one of the following attribute types prepended to the desired attribute value.
    • "Tag:", "Category:", or "Brand:"
  • The Halla system does require an exact match between the desired filter and the product data that is sent to the system.
  • Data must be sent URL encoded, e.g. "GRAINS/CEREALS" > "GRAINS%2FCEREALS".
  • Defaults to none.

For example:

  • Products that contain 'vegan' AND 'better_for_you' tags
    • &attributeFilter=vegan&attributeFilter=better_for_you
  • Products that contain 'vegan' OR 'better_for_you' tags
    • &attributeFilter=vegan%7Cbetter_for_you
  • Products in the "Cheese" category that contain 'vegan' OR 'better_for_you' tags
    • &attributeFilter=Category:Cheese&attributeFilter=vegan%7Cbetter_for_you
  • Products not in the "Cheese" category
    • &attributeFilter=Category:%21Cheese
header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Responses

Get Product Metadata

Get back Halla computed metadata for a given product.

Authorizations:
path Parameters
productId
required
string

Subscriber specific primary product id.

header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Responses

Get Product

Get back a product by it's primary product id

Authorizations:
path Parameters
productId
required
string

Subscriber specific primary product id.

header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Responses

Add Orders

Adds new orders, updating associated consumer profiles to allow for real-time personalization. Amount of orders in a single request should not exceed 100k

Authorizations:
header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Request Body schema: application/json

The orders to create.

Array of objects (Order)

Responses

Request samples

Content type
application/json
{
  • "orders":
    [
    ]
}

Add Store

Creates / overwrites a store with a distinct catalog.

Notes:

  • Halla will perform best on inventories between 1,000 and 50,000 products.
  • Primary product ids persist across multiple stores for a given client.
Authorizations:
header Parameters
serviceAccount
required
string

Identifies the serviceAccount for authorization purposes.

Request Body schema: application/json

The store to create.

id
required
string

Used across services to link to this store object.

channel
string
Enum: "E_COMMERCE" "SELF_SCAN" "SMART_CART" "PROMOTIONS" "OTHER"

The application type that will be using Halla's services.

type
string
Enum: "GROCERY_STORE" "SUPER_STORE" "CONVENIENCE" "DELI" "OTHER"

The type of store that will be using Halla's services.

brand
string

Brand of store.

postalCode
string

postal code of store location.

country
string

2 digit country abbreviation. 'US for United States and UK for United Kingdom.'

Array of objects (Product)

Products in the given store's catalog.

object (ProductSummary)

Descriptive information on a store's products.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "channel": "E_COMMERCE",
  • "type": "GROCERY_STORE",
  • "brand": "string",
  • "postalCode": "string",
  • "country": "string",
  • "products":
    [
    ],
  • "productSummary":
    {
    }
}