Search API

Getting search results and completions from the Froomle platform is done through the search API. The search results and completions in the API will only contain items which are stored in the specified environment. In addition to requesting search results and completions, the search API also supports fetching previously computed search results.

Specifications

Description

Request search results.

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"
}

GET /{environment}/searches/lists

Description

Query cached items in a list computed.

Parameters

Type Name Description Schema

Path

environment
required

The environment for which a request is made.

string

Query

limit
required

The number of items to fetch.

integer

Query

list_key
required

String identifier of the previously computed list to request recommended items from.

string

Query

offset
required

The rank of the first item to be requested. Starts at counting at 1.

integer

Responses

HTTP Code Description Schema

200

OK

404

list_key not found, it either expired or never existed

No Content

Produces

  • application/json

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"
}

GET /{environment}/searches/completions

Description

Request completions.

Parameters

Type Name Description Schema

Path

environment
required

The environment for which a request is made.

string

Query

device_id
optional

string

Query

page_type
optional

The page_type for which a request is made.

string

Query

q
required

The query term.

string

Query

request_id
optional

string

Query

user_id
optional

string

Responses

HTTP Code Description Schema

200

OK

Produces

  • application/json


POST /{environment}/searches/completions

Description

Request completions.

Parameters

Type Name Description Schema

Path

environment
required

The environment for which a request is made.

string

Body

body
required

Responses

HTTP Code Description Schema

200

OK

Consumes

  • application/json

Produces

  • application/json


Definitions

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 the Froomle support team 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


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


CompletionRequest

Request for Completions

Name Description Schema

device_id
optional

User Identifier

string

filter_by
optional

fuzziness
optional

Give results for nearest correct query

integer

histories
optional

q
optional

Part-word query

string

user_id
optional

User Identifier

string


Completion

Completions based on Search query

Name Description Schema

completions
required

< Item > array

request_id
required

integer

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