POST /{environment}/searches/requests

Description

Request search results for an environment-aware setup.

Parameters

Type Name Description Schema

Path

environment
required

The environment for which the request is made.

string

Body

body
required

Responses

HTTP Code Description Schema

200

OK

Consumes

  • application/json

Produces

  • application/json

Example HTTP request

Request body

{
  "autocorrect" : true,
  "channel" : "web",
  "device_id" : "the-cookie-id-123",
  "filter_by" : { },
  "group_by" : [ ],
  "histories" : {
    "followed_categories" : [ {
      "id" : "electronics",
      "item_type" : "category",
      "timestamp" : 1581854333
    }, {
      "id" : "beauty",
      "item_type" : "category",
      "timestamp" : 1581952165
    }, {
      "id" : "gaming",
      "item_type" : "category",
      "timestamp" : 1581954120
    } ]
  },
  "limit" : 5,
  "list_size" : 10,
  "num_lists" : 5,
  "page_type" : "home",
  "q" : "Froomle AI",
  "user_id" : "the-user-id-123-like-cookie"
}

Example HTTP response

Response 200

{
  "list_size" : 10,
  "lists" : [ {
    "grouped_by" : [ ],
    "items" : [ {
      "item_id" : "b0156c7e-2265-4d7f-8c75-e0ec31138377",
      "item_type" : "some_type",
      "title" : "some_title"
    }, {
      "item_id" : "3f3c895a-1508-4045-9ff4-97bcef2b801b",
      "item_type" : "some_type",
      "title" : "some_title"
    } ],
    "limit" : 2,
    "list_key" : "a_unique_list_identifier",
    "list_name" : "Search results 1",
    "list_size" : 5
  } ],
  "num_lists" : 1,
  "request_id" : "2141141"
}

Item

One content-item.

Name Description Schema

information_field
required

The Froomle API can be configured to return additional information fields (if present in the item information). Please contact your Froomle Solution Architect to set this up.

string

item_id
required

The identifier of the recommended item.

string

type
required

The document type of the object being returned.

string

List

A list of limit items is returned. Potentially the list consists of list_size items in total, of which the next can be queried by passing the list_key to the /lists endpoint.

Name Description Schema

grouped_by
optional

Values of group_by-keys that are common among Items in a List. Default: []

< string > array

items
optional

List of limit Items. limit is equal to the minimum of limit specified in the request and the number of recommendations found.

< Item > array

limit
optional

Number of Items returned

integer

list_key
optional

Bytestring identifier of the List

string

list_name
optional

Bytestring name of the list. Generated by Froomle.

string

list_size
optional

Total number of Items in this List (of which only limit Items are returned)

integer

Filter

Filters to be specified in a Search to determine which Items should be allowed and which should not. Filters are key-value pairs of properties on an Item. Filters can be applied on any property of an Item given by the client.

Name Description Schema

<field>
optional

The Froomle Search API can be configured to allow for certain filters to be applied. Please contact your Froomle Solution Architect to set this up.

string

Histories

Dict of additional customer-defined histories each having a maximum length of 50 tuples

Type : < string, < HistoryItem > array > map

HistoryItem

Single event entity defined by at least an identifier

Name Description Schema

id
required

Identifier of the entity of the event, we support most entities that would appear in a detail_pageview, item_interaction, group_pageview or group_interaction.

string

item_type
optional

Type of the entity (e.g. item, article, video, category, group, …). These types are Froomle-defined, please consult your solutions architect for the correct type.

string

reconsumable
optional

True if the entity is allowed to appear in the generated recommendations

boolean

timestamp
optional

Unix timestamp (seconds since Jan 1st 1970 00:00:00) of the event

integer

SearchRequest

Specification of a Search request.

Name Description Schema

autocorrect
optional

Boolean to indicate whether the query should be autocorrected the nearest correct query.
Default : true

boolean

channel
optional

The channel used to request the search results (e.g. web, android, ios, …)

string

device_id
required

Unique identifier for a unregistered user (e.g. cookie).

string

filter_by
optional

group_by
optional

Fields by which to group search results into different Lists.

< string > array

histories
optional

limit
optional

Number of Items to be returned per List. This does not have to be equal to list_size.

integer

list_size
optional

Number of Items per list to be cached, to be queried later.

integer

num_lists
optional

Number of Lists requested. Additional lists that were computed will not be returned or cached.

integer

page_type
required

The page type to request search results for.

string

q
required

The search query as inputted by the user.

string

user_id
optional

Unique identifier for a user.

string

SearchResults

Name Description Schema

auto_suggest
optional

New query term, if the query term was autocorrected.

string

lists
required

List of lists of items

< List > array

num_lists
required

Number of Lists requested as specified in Search. Repeated for ease of use.

integer

perfect_match
optional

A perfect match for the search query if there was one.

request_id
required

The request ID of the search request

string

user_group
optional

The group the user is assigned to. If users get the Froomle experience, this will always be "froomle".

string

version
optional

The version the user is assigned to. Used for AB testing purposes

string