# /search API (v0.4)

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                                |
| sort                  | Array of string | Sorting values sent to Meilisearch to sort the search results.                                                                                                                       | No                   | \["price:asc", "name:desc"]       |
| 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.                                                 | <p><br></p><p>No</p> | 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

```http
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
  &sort=price:desc
```

### Response

```json
{
  "hits": [
    
   {
      "id": "126455",
      "img_link": "/103446.jpg",
      "link": "/starWarsLego",
      "name": "Star wars lego",
      "price": 120
    },
    {
      "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": 5.9
    }
  ],
  "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
}

```