Narrative API - Technical Reference

Introduction

Boxalino Narrative API is a REST API supporting a configurable JSON data structure as input and output.

Several configuration can be defined and available in different URL end-points.

This document both describes the standard aspects of the API as well as the most commonly used default configuration which covers the vast majority of cases for the typical Boxalino WPO (Welcome, Search, Up-Sell and Cross-Sell).

End-point (URL)

The End-point is always structured as follows:

POST https://[SUB-DOMAIN].bx-cloud.com/narrative/[ACCOUNT]/[PATH]/[VERSION]?profileId=[PROFILE_ID]

with:

SUB-DOMAIN: the Boxalino Real-Time Cloud (RTC)

  • “main” for production (do not use for dev / stage)

  • “r-st” for dev / stage

  • “ch” for Swiss Data Center Fall-Back (will be available soon)

  • “track” for tracker, batch and other Newsletter requests

ACCOUNT: your account name

PATH: a configurable path for your narrative, typically the value is “api”

VERSION: the version number of your end-point configuration (1 if you don’t use versioning)

PROFILE_ID: the same value as what you provide in the base parameters described below (content of the _cemv cookie), for batch request, take the first customerId of the list

As an first alternative, you can provide provide a parameter sessionId or _bxv instead of the profile id

As an second alternative, you can also not set the profileId parameter and instead set HTTP-Headers with either X-BX-PROFILEID (with the value of the _cemv cookie), or X-BX-CUSTOMERID (with the value of the customerId)

Above: Example query with ARC (Advanced Rest Client) Chrome extension

https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo/related

Before testing your integration with code, we recommend you test it with this extension to make sure it technically works.

Request JSON

Your JSON request (to be passed in the body of your POST request) is fully configurable.

We will not cover in this document how to configure it but will document how it works out-of-the-box in the case of the standard configuration which is automatically available with your account without any special configuration.

Base parameters

These parameters are always required, independently of the type of request you do:

{ "username": "your_account", "apiKey": "your api key", "apiSecret": "your api secret", "dev": false, "test": false, "sessionId": "the visitor session id", "profileId": "the visitor profile id", "customerId": "the customer account id", "widget": "search", "language": "de", "hitCount": 10 }

Name

Example value

Description

Name

Example value

Description

username

your_account

The name of your account

apiKey

[your api key]

if you don’t have an apiKey, please request it to Boxalino

WARNING: your apiKey and apiSecret will not be the same for dev:true or dev:false requests

https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/713785345

apiSecret

[your api secret]

if you don’t have an apiKey, please request it to Boxalino

WARNING: your apiKey and apiSecret will not be the same fir dev:true or dev:false requests

https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/713785345

dev

true/false

false for production data index access

true for dev / stage data index access

WARNING: you might use a different account for stage / dev in which case you might need to set this parameter to false but change your username (and apiKey and apiSecret) to match your stage / dev account

test

true/false

false for your live configuration

true for your current unpublished configuration (test mode)

Your test configuration is based on the state of your configuration in the Boxalino Intelligence admin (intelligence.bx-cloud.com) which was set with the button “Save & Test” but not yet published.

sessionId

[any unique string]

the string uniquely identifying the session of the user

WARNING: this value should remain the same for the entire session and match the value of the cookie cems used by Boxalino tracker. Make sure to set the cookie if not set and to read it if already set by our tracker (or by yourself in prior requests). Make sure the cookie disappears at the end of the session.

profileId

[any unique string]

the string uniquely identifying the visitor (should be the same for several visits if the user doesn’t flush his browser cookies)

WARNING: this value should remain the same for the entire session and match the value of the cookie cemv used by Boxalino tracker. Make sure to set the cookie if not set and to read it if already set by our tracker (or by yourself in prior requests). Make sure the cookie last across many sessions for a minimum duration of 1 year.

customerId

[the account id of the customer as provided in the customer export data]

(optional) if the user is logged in, the customerId should be passed to the request

widget

home/search/navigation/similar/complementary/basket

the name of your configured widget (to get the list of your configuration widgets, go to the Boxalino Intelligence admin (intelligence.bx-cloud.com) in the main (Widget & Page Optimizers) view

language

de/fr/en/it/…

the 2 letter language code

WARNING: your data must be available in this language

hitCount

10

the number of results you would like to be returned (in some cases like search, the number of returned hits might be smaller than the requested amount)

Typical parameters

These parameters are often needed, independently of the type of request you do:

{ //... (see base parameters) "offset": 10, "groupBy": "products_group_id", "returnFields": ["title", "discountedPrice", "products_brand"], "filters": [ { "field": "id", "negative": true, "values": ["123","456"] }, { "field": "discountedPrice", "from": 10.80, "to": 28.10, "fromInclusive": true, "toInclusive": true } ], "orFilters":false, "parameters": { "campaign":"mycampaign", "User-Host": "62.2.185.11", "User-Referer": "https://www.google.ch", "User-URL": "https://www.yourside.ch", "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36" } //... }

These parameters are all optional as they can be defined as default values in the Boxalino Admin Configuration, however, it might be desired to set them explicitly in the query.

Name

Example value

Description

Name

Example value

Description

offset

10

for pagination, in case you don’t want to retreive the first X results, but the results starting from a specific offset (offset = 0 means first result)

groupBy

products_group_id

If you want the results to be grouped according to a specific property (often, we use the field “products_group_id” for this)

returnFields

["title", "discountedPrice", "products_brand"]

The list of fields that should be returned for each bx-hit in the response (see below the Bx-Hit section for more details)

filters

orFilters

 

a list of filters to be applied

if the filters should be applied as an or or as an and

  • field

“id”

the name of the field to be applied for the filter

  • negative

true/false

should the filter be positively or negatively applied (return results matching the filters or not matching the filter)

  • values

[“a”, “b”]

a list of string values

only needed for filters checking specific values can be left unset otherwise

  • from

  • to

  • fromInclusive

  • toInclusive

  • 10.80

  • 25.50

  • true/false

  • true/false

a range of numerical values

only needed for filters checking a range of numerical values

only work for numeric fields

from and to inclusive define if the provided number should be included or excluded in the filter matching logic

parameters

{
"campaign":"mycampaign",
"User-Host": "62.2.185.11",
"User-Referer": "https://www.google.ch",
"User-URL": "https://www.yourside.ch",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36"
}

configured parameters

make sure to always provide:

  • User-Host : with the IP

  • User-Referer: with the referer URL

  • User-URL: with the current URL

  • User-Agent; the User-Agent string

do not have any automatic effect but might be require for specific configuration (for example: to indicate the current campaign which will help the system identify what are the best matches related to this campaign).

Other parameters

The other parameters will be described below for each of the LEVEL 1 WPO: Welcome, Search, Navigation, Up-Sell, Cross-Sell, Re-buy and Individualize:

If you are not sure what WPO you are integrating, please contact Boxalino for clarification.

Response JSON

Your JSON response (returned as the content of your POST request) is fully configurable.

However, a base structure is fixed and present regardless of the configuration.

We will not cover in this document how to configure it but will document how it works out-of-the-box in the case of the standard configuration which is automatically available with your account without any special configuration.

Fixed base structure

The base structure consists of one JSON with a parameter “blocks” providing a list of blocks.

Each block has a list of subBlocks (which can be empty) in the parameter “blocks”.

There are some exceptions to this base structure (e.g.: batch requests) which are described in a later section which adds an encapsulating structure around this based structure, but even in such cases, the base structure is still provided inside.

{ "blocks": [ { "blocks": [] }, { "blocks": [ { "blocks": [] } ] } ] }

The list of blocks corresponds to the layout blocks to be displayed to the user. Therefore, the Boxalino Narrative API is not a Data API (providing you detailed information about a model data object) but a Layout&Content API which provides you directly a list of blocks to be displayed to the user in the provided order.

Typically, to provide a grid-layout to the user, the first level of blocks represents the rows, and the second level (the children blocks of the main blocks) the cols. However, you are free to configure any structure that you want, the only important aspect is that the order in which the blocks are provided matches the order in which the elements are displayed to the user (typically considering a responsive design with elements appearing on a mobile view).

In addition, advanced technical parameters are provided in the root parameters: “performance” and “advanced”, go to the Annex “Advanced Response Parameters” to see the details.

Use other positions than the main “blocks”

If you define a parameter position in one of your Templates (e.g.: “left”), then, instead of being added with the other blocks in the main “blocks” property of the response, they will be set in a property name matching your position value (e.g.: “left”).

Here is an example response with a position “left” set in some of the returned blocks:

Block parameters

Block parameters are directly provided in the JSON object parameter of each block.

Their format varies (as exemplified below in the parameter1/2/3/4 but is often represented in the format of parameter1 as a list of strings).

Typical Parameters

The following parameters are not fixed, but are automatically present in the standard (and most custom) configuration:

Name

Example Value

Description

Name

Example Value

Description

template

product_list

the name of the template which should be used to display the block and its parameters

model

ProductList

(optional) the model that should be use in your MVC to manage the logic for this template rendering.

In the majority of the cases you should not require any business logic and render the template directly, but in special situation (e.g.: to do a real-time look-up of a price before display) some controller method might be required in your template

position

main

(optional) if you use a multiple column layout (e.g.: with search facets on the left column and results on the main column) this parameter will indicate for which column of your layout this block is destined.

important: this parameter will change the structure of the response, see Fixed base structure above for details

bx-attributes

as below

not all, but most of the blocks have bx-attributes properties and values to be mapped to your html tagging (see next section)

bx-attributes: Tagging for your HTML

The property bx-attributes provide you with a list of names and values to tag your HTML (typically the DIV tag representing the block).

The name and values can be simply added to your div as additional attributes, except for the class, which should be added to the pre-existing class of the div.

The bx-attributes are provided as a list of “name” and “value” objects, as here:

Here is the list of all the bx-attributes which can be returned, however it is recommended to simply loop through the array and add them to the div directly, so if this list changes over time, your integration won’t need to be modified to reflect the new changes:

Name

Example Value

Description

Name

Example Value

Description

data-bx-variant-uuid

94370d66-a88b-461b-afc7-9347d946c7c8

a unique identifier for a container block (a block which contains a list of dynamic elements) which is unique per display of the page

data-bx-narrative-name

product-list

narrative name (typically defined as “product-list”)

data-bx-narrative-group-by

products_group_id / id

the group by field which is used to group the dynamic elements returned in this container block.

class

“bx-narrative”/”bx-narrative-item”
/”bx-narrative-root-item bx-narrative-item”

not all, but most of the blocks have bx-attributes properties and values to be mapped to your html tagging (see next section)

data-bx-item-id

1234

the group by value of a specific element in the list of dynamic elements belonging in a conatiner

data-bx-related-variant-uuid

94370d66-a88b-461b-afc7-9347d946c7c8

a unique identifier for a referred container block (a block which contains a list of dynamic elements) which is unique per display of the page (a referred container block means that the elements of the current block are related to the elements of another block of the page, for example, the product recommendations related to a banner appearing before)

data-bx-related-narrative-name

product-list

related narrative name (typically defined as “product-list”)

data-bx-related-narrative-group-by

products_group_id / id

the group by field which is used to group the dynamic elements returned in the related container block.

data-bx-related-item-id

1234

the related group by value of a specific element in the list of dynamic elements belonging in a conatiner

All these attributes, if returned, are required for the scroll and click behaviors to be properly tracked on the page.

The following HTML exemplifies what HTML tagging is required for our JavaScript Tracker to work optimally. You can see there that several classes are needed but static, while the following tags need to be dynamically injected from our response:

  • data-bx-variant-uuid (in the container div, from the parmaeter variantUuid)

  • data-bx-narrative-group-by (in the container div, from the parameter groupBy)

  • data-bx-item-id (for each hit, see Bx-hit section below for the field “groupValue”)

Default Narrative Configuration

From now on, we will define the data structure appearing in the responses connected to standard aspects (such as bx-hit, bx-facets, bx-pagination, and bx-sort). The exact location in the response where these parameters will appear depends on your Narrative configuration.

bx-hit : Product / Blog / Hit Block

The bx-hit parameter is typically inside the children blocks of the main block containing a list of products (search results, a slider of product recommendations, etc.).

A standard parameter “bx-hit” is provided with the key information about the hit (product, blog article, etc.):

Parameters of bx-hit:

Name

Example Value

Description

Name

Example Value

Description

id

155525

a string value matching the unique hit id returned.

In case you use a group-by on another field, the id will match the top-scored matching id in that group.

See Group-By details in general request parameters above.

groupValue

155525

a string value matching the group by Value (in case of no group-by, the value will be the same as of the id).

See Group-By details in general request parameters above.

IMPORTANT: must be provided in the HTML tag as value for attribute “data-bx-item-id” as in HTML example above

score

99.82

a numeric value indicating the score (the highest score is on top)

the score depends of your Boxalino Optimization strategy and is logic is not described in this document

other product fields

 

The fields indicated in addition depend on your configuration and the list of Return Fields in your request.

See Return Fields details in general request parameters above.

  • numeric & multi-value

[1,2.5,3]

a list of numeric values in an array

  • numeric & not multi-value

23.5

one single numeric value

  • string & multi-value

[“a”,”b”,”c”]

a list of string values in an array

  • string & not multi-value

“a”

one single string value

LEVEL 1 - AWARENESS - WELCOME

The Welcome WPO consists in the integration of product recommendations on the home page or on general landing pages.

The home page doesn’t require any special parameter and the response doesn’t include any special parameters either, so the documentation of the prior sections covers it fully.

Some other start pages might need to pass some parameters (it is a best practice to have a landing page for each campaign defined in Boxalino admin) in “Request > Typical parameters” section above.

LEVEL 1 - CONSIDERATION - SEARCH

The Search WPO consists of the integration of the search and navigation (product listing) pages.

We describe here first the case of navigation (as all the cases are also applicable for search) and then the case of Search (as it has several cases which are specific to search and not applicable for navigation).

NAVIGATION

The navigation widget consists of the display of a listing of products as well as facets (i.e.: filtering options), pagination, and sorting options.

Facets Request Parameters

These parameters are always required to set the value of a facet. It is also possible to set a facet request without setting a value for the facet (so that the facet will be included in the response) but it is also possible to do that directly in the Boxalino Intelligence Admin.

Facets with selected Value by the user:

Example of 2 facets set with values in the request without any additional parameters

Name

Example value

Description

Name

Example value

Description

  • field

products_brand

The name of the field (same as for filters)

  • values

[“a”, “b”]

a list of string values (same as for filters)

only needed for facets checking specific values can be left unset otherwise

  • valueKey

null/”id”

in case the facet value sent is not the indexed value, but an id, indicate here the name of the facet key used.

  • numerical

  • range

  • boundsOnly

  • from

  • to

  • true

  • true

  • true

  • 10.80

  • 25.51

a range of numerical values

only needed and only works for numeric fields

numerical, range and boundsOnly should all be set to true

from is inclusive but to is exclusive (typically, add 0.001 to the value to include the selected to value)

Facets without selected Value by with additional parameters:

Example of a facet set in the request without values but with additional parameters (this is optional and can be done in Boxalino Intelligence Admin):

Name

Example value

Description

Name

Example value

Description

maxCount

100

the maximum number of facet values which can be returned (return only top N)

minPopulation

5

What is the minimum counter value (population / number of response hits) for the facet value to be returned?

By default 1 as any value having 1 hit or more is shown as facet value

sort

“1”/”2”

sorting of the values of the facets:
1 = by counter value (population / number of response hits)
2 = by alphabetical order

sortAscending

true/false

should the value be ordered in ascending or descending way (typically false for sort “1” to show highest counters first)

andSelectedValues

true/false

when the user selects more than 1 value should the values be both matching each product or any of the value is enough? (only matters if UI makes it possible for the user to select more than one value)

bx-facets: Facets in Response

The bx-facets parameter is typically within one of the main blocks of the response.

A standard parameter “bx-facets” is provided with the key information about the facets

Parameters of bx-facets:

Name

Example Value

Description

Name

Example Value

Description

field

products_brand

The name of the field

url

brand/cat

an encoded version of the field name to be passed to the url

label

Brand

the label of the facet field to be displayed to the user (returned in the language of the request)

values

 

the returned facet values

  • value

kuhn rikon

the value as stored in your hits fields fro that field

  • url

 

  • label

kuhn-rikon

 

Kuhn Rikon

url: the value as set in a SEO-friendly URL

label: the value as it should be displayed to the user

NB: these are not standard parameters, they will depend on the key values defined during your data integration for facets. For more information, please contact Boxalino.

  • label

 

 

  • hitCount

3

the counter (population / number of hits) of this facet value

  • selected

true

is this facet value currently selected by the user

make sure to use this information for the display and not if it is selected or not in the request as it is possible that the facet was not set in the request but got set in the response (e.g.: for Search semantic filtering).

is always true or not set (never set to false)

  • children

[an array of sub-values]

only for hierarchical fields, the children are sub-elements with the same structure (value, url, label, hitCount, selected and children)

position

left/right/top/bottom

optional: to indicate in which zone of the display the facet should appear (e.g.: top facets versus left facets)

enumDisplayMaxSize

enumDisplaySize

7

5

How many values should be displayed before a “show more” link which expands the list of facets.

There are two values and enumDisplayMaxSize > enumDisplaySize.

All values should be displayed without “show more” link unless there are more than enumDisplayMaxSize values returned. In this case, only enumDisplaySize should be displayed before showing the “show more” link

showCounter

true/false

Should the counter (population / number of hits) be displayed (typically between () ) next to the label or not

displaySelectedValues

““/top/only

““ = the selected value(s) should appear within the list in their normal ordering

top = the selected value(s) should appear on the top before the other non-selected values

only = only the selected value(s) should appear and the others should not be displayed to the user

visualization

  • enum

  • multiselect

  • range

  • radio

  • slider

  • pushbutton

  • switch

  • dropdown

  • multiselect-dropdown

  • search

  • stars

  • colorpicker

  • datepicker

  • sizepicker

  • checkbox

  • genderpicker

  • thumbs

  • textarea

  • textfield

what type of visualization should be done for the display (logic to be implemented in your templates)

valueorderEnums

 

sortCode

counter
alphabetical
custom

1,2

informative : in which logic the values have been ordered (custom is not ordered, to be done on your side)

sortCode is similar but with same 1,2 information as in request

isNumerical
isRange
isBoundsOnly

false/true
false/true
false/true

indicate if the facet is a numerical range filter (e.g. for the price), typically either all 3 are set to false or all 3 to true

isAndSelectedValues

false/true

when the user selects more than 1 value should the values be both matching each product or any of the value is enough? (only matters if UI makes it possible for the user to select more than one value)

minDisplayCoverage

0.8

by summing the counters of all of the facet values we get a value indicating how many of the results are related to this facet.

This threshold defines what is the minimum ratio (compared to the returned total hit count) so that facet is considered relevant in this context and should be indeed displayed.

resetOnRemove

true/false

Can only be set to true in cases when the user has selected several values and the request was sent with the parameter andSelectedValue set to false (so the multi-value selection is an OR logic)

If (and only if) set to true, it means that if the user removes a value from this facet, then all the values should be removed, not only the one the user selected to be removed.

bx-pagination (bx-hitCount): Pagination in Response

The bx-pagination parameter is typically within one of the children’s blocks of a main block of the response.

Name

Example value

Description

Name

Example value

Description

totalHitcount

22

the total number of results

offset

0

the current offset of the current results

pageSize

10

the current page size

User Sorting in Request

In order to order the results in a special way, you can set the sort parameter in your request.

Name

Example value

Description

Name

Example value

Description

sort

 

sort fields set by the user (should not be set at all for default sorting)

sort fields are applied in the order provided (from the most to the least important)

sort fields overwrite completely the ranking logic of Boxalino and should only be used if the user wants to change the ranking and not for other reasons

  • field

title

the field to apply the sorting on

WARNING: the field must be set not to be multi-value (multi-valued fields cannot be used for sorting)

  • reverse

true/false

true : biggest value first

false : smallest value first

bx-sort: User Sorting options in Response

The bx-sort parameter is typically within one of the children’s blocks of a main block of the response.

Name

Example value

Description

Name

Example value

Description

  • field

title

the field to apply the sorting on

WARNING: the field must be set not to be multi-value (multi-valued fields cannot be used for sorting)

  • reverse

true/false

true : biggest value first

false : smallest value first

SEARCH

In this section, we describe the aspects specific to the search.

The main specific aspect of Search is the autocomplete (the display of textual and product suggestions while the user is typing). Such logic must be integrated in Ajax. We describe here the request and response to be done on your server and to be returned to the browser through Ajax.

It is highly recommended to simply pass through our response as it is already in JSON.

However, you might want to modify it to include information which is not available in Boxalino in real-time (such as the product price).

SEARCH-AUTOCOMPLETE REQUEST

Name

Example value

Description

Name

Example value

Description

acQueriesHitCount

7

the maximum number of textual suggestions matching the typed query to be returned

required field, the detection if it is a normal request or a autocomplete request is done based on the existance of this parameter.

acHighlight

true/false

should the text match be highlighted

acHighlightPre

<em>

what should be injected before the highlight

acHighlightPost

</em>

what should be injected after the highlight

SEARCH-AUTOCOMPLETE RESPONSE

The Search Autocomplete Response is a standard Narrative response with the exception of a special parameter “bx-acQuery” for the textual suggestions.

bx-acQuery

The bx-acQuery parameter is typically inside the children blocks of the container block of auto-complete queries (normally the first one).

A standard parameter “bx-acQuery” is for each child block providing the key information about the suggested Search Terms

Parameters of bx-hit:

Name

Example Value

Description

Name

Example Value

Description

suggestion

red pants

the suggested query

highlighted

 

optional : indicates which part of the query should be highlighted

score

315

a numeric score indicating the score of this query suggestion

LEVEL 1 - EVALUATION- UP-SELL / CROSS-SELL

The Up-Sell WPO consists of the integration of product recommendations on the product detail page.

The Cross-Sell WPO consists of the integration of product recommendations on the basket page or on a pop-up appearing after a product is added to the basket.

The response of the Up-Sell and Cross-Sell is fully similar to the one of the Welcome and is therefore not re-described here.

UP-SELL / CROSS-SELL REQUEST

Both Up-Sell and Cross-Sell require the setting of Context-Items in the request.

In the case of Up-Sell, it corresponds to one value matching the current product detail page.

In the case of the Cross-Sell, it corresponds to the list of values matching the products already in the basket of the user.

Name

Example value

Description

Name

Example value

Description

items

 

the list of context items (current product for product detail page and list of product in the basket for basket page)

  • field

“id”,”products_group_id”,…

the identifier field

On a product detail page, it might be “products_group_id” because the page is for a group of skus (different size / color options) and not for one specific product

On the basket page it is always “id” as each product on the basket should be a specific sku

  • value

“1234”

the identifier of the product (value should match the provided field)

  • role

mainProduct / subProduct

(optional, should be set to mainProduct by default)

if needed a value identifying the importance of the product in the list can be set (e.g.: the most expensive product of the basket is set to “mainProduct” and the other to “subProduct”)

LEVEL 1 - PURCHASE- RE-BUY

The Purchase WPO consists of the integration of product recommendations on the account page or other special pages requiring the visitor to be logged in.

These pages don’t require any special parameter and the response doesn’t include any special parameters either, so the documentation of the prior sections covers it fully.

LEVEL 1 - PURCHASE- INDIVIDUALIZE

The Individualize WPO consists of the integration of product recommendations on the e-mail (or other outbound messages) sent to the user.

The specialties of the Individualize integration are the following:

  1. As you will request product recommendations for many different clients to be sent in E-mail, you need to make Batch requests grouping many (typically 500 - 1000 requests in one batch)

  2. You should not use “main.bx-cloud.com” but “track.bx-cloud.com” as the main clouds should not receive heavy loads of requests at a specific moment which might affect the average request time performances!

BATCH REQUEST

Name

Example value

Description

Name

Example value

Description

batch

 

the list of customer requests to be processed all in one call

  • customerId

1234

the customer Id

  • parameters

{“campaign”:[“myCampaign”]}

configured parameters, optional, needed for parameters specific to each customer.

Global parameters which should apply to all customers can be provided as normal.

do not have any automatic effect but might be require for specific configuration (for example: to indicate the current campaign which will help the system identify what are the best matches related to this campaign).

BATCH RESPONSE

Instead of the standard Response JSON structure as described above:

The Batch request provides a different structure:

So, instead of one object with a “blocks” parameter, the response is a list of objects each having a “customerId” parameter in addition to the “blocks” parameter.

The Inner Structure of the “blocks” parameters is unchanged.

Annex #1 - Advanced Response Parameters

In addition to the “blocks” parameter, other parameters are provided with some key technical information

The performance block indicates the start and completion timestamps (in ms) of your narrative API request. This is the total time spent on our servers (without counting the networking between yours and our servers).

Annex #2 - Advanced Request Parameters

The API supports also the settings of advanced parameters for special use-cases.

Correlations

What is it about?

Boxalino standard processes as well as your own custom projects in Google BigQuery can generate highly relevant data to be deployed and made available in Boxalino Real-Time Platform as described here:

One of the most used table in the Open Data Science Lab is the “correlations” as documented here: . It will be in your own BigQuery project in “[your_account_name]_lab.correlations”.

Most of the times these data will be used within the Boxalino configuration and will influence the algorithms deciding which products (or content) are returned in which order for each customer.

But sometimes, you might need to retrieve these data as they are saved in the “correlations” table. This can be done with configuration in the Boxalino Admin, but this can also be directly requested (without requiring any configuration) in your API request, which is the use-case we are documenting here.

What to send in the request?

In your request, you need to send another parameter called “correlations” as follows:

it is an array of object, each with 3 parameters:

name

example value

comment

name

example value

comment

origin

boxalino_std

(optional, will be ‘boxalino_std’ by default)

To be set if you have loaded the data by yourself in the lab.correlations table with another origin value

type

xxx

a string value as is in the type column of the correlation table

source

yyy

a string value as is in the source column of the correlation table

What will be in the response?

As the advanced parameters, there will be another parameter in the response also called “correlations”

The values you can retrieve are stored in the array parameter “target” as in the example (“zzz”) above.