/search API (v0.3)

This document outlines the usage of the Search API route, which allows for powerful querying and filtering of datasets.

Endpoint

Method	URL
GET	https://{identifier}.search.abtasty.com/search

Query parameters

All request data is sent as URL query parameters. Nested data uses bracket notation.

Serialization rule (canonical):

• Objects: filters[field][key]=value

• Arrays of scalars: repeat the param: filters[field][]=v1&filters[field][]=v2

• Arrays of objects: index the array: filters[field][0][operator]=>&filters[field][0][value]=10

Parameter	Type	Description	Required	Example
text	string	The search query string.	Yes	"toy"
filters	object	An object containing key-value pairs for filtering search results. Each key represents a field to filter on. Values can be strings, arrays of strings, or objects for range queries.	No	{"brand": ["lego", "playmobil"]}
page	integer	The page number of results to retrieve (0-indexed).	No	0
hitsPerPage	integer	The number of results to return per page.	No	20
rankingScoreThreshold	float	A ranking score from 1.0 (perfect match) to 0.0 (no match) indicates relevancy, with higher scores signifying better matches.	No	0.1
semanticRatio	float	semanticRatio balances semantic search results. Higher values bring documents from further in the semantic space into final results.	No	0.3

filters Object Structure

The filters object supports different types of filters:

• List Filters: For fields where you want to match one or more exact values.

• Format: {"field_name": ["value1", "value2"]}

• Example: "color": ["red", "blue"]

• Range Filters: For numerical fields where you want to specify a range using operators.

• Format: {"field_name": [{"operator": "operator_type", "value": number}, {"operator": "operator_type", "value": number}]}

• Supported Operators: ">", "<", ">=", "<=", "="

• Example: "price": [{ "operator": ">", "value": 10 }, { "operator": "<", "value": 20 }]

• Example: "rating": [{ "operator": ">=", "value": 4 }]

Response Body

The response body is a JSON object with the following properties:

Property	Type	Description
hits	array of objects	An array of search results, where each object represents a matching item. The structure of each item depends on the dataset.
facets	object	An object containing aggregated facet information for different fields, useful for building dynamic filtering interfaces.
totalPages	integer	The total number of available pages based on the hitsPerPage.
totalHits	integer	The total number of search results matching the query and filters.
hitsPerPage	integer	The number of results returned per page, as specified in the request or defaulted by the API.
page	integer	The current page number of the results.

facets Object Structure

The facets object provides information about different fields that can be used for filtering:

• type: Indicates the type of facet ("list" or "range").

• values:

• For "list" type: An array of arrays, where each inner array contains the facet value and its count.

• For "range" type: An object with min and max properties indicating the available range.

Example Request and Response

Request

GET https://search-api.abtasty.com/search
  ?index={identifier}_Catalog
  &text=toy
  &filters[brand][]=lego
  &filters[brand][]=playmobil
  &filters[price][0][operator]=%3E
  &filters[price][0][value]=10
  &filters[price][1][operator]=%3C
  &filters[price][1][value]=20
  &filters[color][]=red
  &filters[color][]=blue
  &filters[rating][0][operator]=%3E%3D
  &filters[rating][0][value]=4
  &page=0
  &hitsPerPage=20
  &rankingScoreThreshold=0.1
  &semanticRatio=0.1

Response

{
  "hits": [
    
{
      "id": "126455",
      "img_link": "/103446.jpg",
      "link": "/starWarsLego",
      "name": "Star wars lego",
      "price": 5.9
    },
    {
      "id": "126456",
      "img_link": "/103447.jpg",
      "link": "/playmobilCastle",
      "name": "Playmobil Castle",
      "price": 45.0
    },
    {
      "id": "126457",
      "img_link": "/103448.jpg",
      "link": "/barbieDreamhouse",
      "name": "Barbie Dreamhouse",
      "price": 120.0
    }
  ],
  "facets": {
    "brand": {
      "type": "list",
      "values": [["lego", 10], ["playmobil", 5]]
    },
    "category": {
      "type": "list",
      "values": [["toys", 15], ["games", 8]]
    },
    "price": {
      "type": "range",
      "values": {
        "min": 5,
        "max": 100
      }
    }
  },
  "totalPages": 20,
  "totalHits": 1000,
  "hitsPerPage": 50,
  "page": 1
}