# Using search with API

This tutorial guides you through integrating AB Tasty Search using the Search API. You will learn how to construct API requests, implement filters, handle pagination, and process search responses to deliver search functionality on your website.

### Prerequisites

Before you begin, ensure you have:

* A validated AB Tasty search configuration with satisfactory performance
* Your unique search identifier (provided by AB Tasty)
* Development environment with API request capabilities
* Understanding of REST APIs and JSON formatting
* Access to your product catalog structure and filterable attributes

### Steps

{% stepper %}
{% step %}

#### Understand the API endpoint

The Search API uses a single GET endpoint to perform all search operations:

**Endpoint**: `https://{identifier}.search.abtasty.com/search`

Replace `{identifier}` with your unique search identifier provided by AB Tasty. All request parameters are sent as URL query parameters using standard HTTP GET conventions.
{% endstep %}

{% step %}

#### Construct a basic search request

Create a simple search request using the required text parameter:

**Basic request structure**:

```
GET https://{identifier}.search.abtasty.com/search?text=toy
```

**Required parameter**:

* `text`: The search query string entered by the visitor

**Optional parameters** to enhance your request:

* `page`: Page number of results (0-indexed, default: 0)
* `hitsPerPage`: Number of results per page (default: 20)
* `rankingScoreThreshold`: Minimum relevancy score from 0.0 to 1.0 (default: no threshold)
* `semanticRatio`: Balance for semantic search results from 0.0 to 1.0 (default: 0.0)

**Example with pagination**:

```
GET https://{identifier}.search.abtasty.com/search?text=toy&page=0&hitsPerPage=20
```

{% endstep %}

{% step %}

#### Implement list filters

Add list filters to match exact values for specific fields:

**Filter syntax**:

```
filters[field_name][]=value1&filters[field_name][]=value2
```

List filters allow visitors to narrow results by selecting one or more values for categorical attributes such as brand, color, or category.

**Example request with brand filter**:

```
GET https://{identifier}.search.abtasty.com/search
  ?text=toy
  &filters[brand][]=lego
  &filters[brand][]=playmobil
```

**Example request with multiple list filters**:

```
GET https://{identifier}.search.abtasty.com/search
  ?text=toy
  &filters[brand][]=lego
  &filters[color][]=red
  &filters[color][]=blue
```

Apply list filters for any filterable attributes configured in your search settings.
{% endstep %}

{% step %}

#### Implement range filters

Add range filters for numerical fields using comparison operators:

**Filter syntax**:

```
filters[field_name][0][operator]=operator_type&filters[field_name][0][value]=number
```

**Supported operators**:

* `>`: Greater than
* `<`: Less than
* `>=`: Greater than or equal to
* `<=`: Less than or equal to
* `=`: Equal to

**Example request with price range**:

```
GET https://{identifier}.search.abtasty.com/search
  ?text=toy
  &filters[price][0][operator]=>
  &filters[price][0][value]=10
  &filters[price][1][operator]=<
  &filters[price][1][value]=20
```

This example returns products priced between 10 and 20.

**Example request with minimum rating**:

```
GET https://{identifier}.search.abtasty.com/search
  ?text=toy
  &filters[rating][0][operator]=>=
  &filters[rating][0][value]=4
```

Combine multiple range conditions to create precise numerical filters.
{% endstep %}

{% step %}

#### Combine multiple filter types

Create comprehensive search requests by combining list filters and range filters:

**Complete example request**:

```
GET https://{identifier}.search.abtasty.com/search
  ?text=toy
  &filters[brand][]=lego
  &filters[brand][]=playmobil
  &filters[price][0][operator]=>
  &filters[price][0][value]=10
  &filters[price][1][operator]=<
  &filters[price][1][value]=20
  &filters[color][]=red
  &filters[color][]=blue
  &filters[rating][0][operator]=>=
  &filters[rating][0][value]=4
  &page=0
  &hitsPerPage=20
```

This request searches for toys from Lego or Playmobil brands, priced between 10 and 20, available in red or blue, with a rating of 4 or higher, returning the first 20 results.

**URL encoding note**: Operators like `>` must be URL-encoded (`%3E`) in actual requests.
{% endstep %}

{% step %}

#### Configure ranking and semantic parameters

Fine-tune search relevance using advanced parameters:

**Ranking score threshold**: Set a minimum relevancy score to filter out low-quality matches:

```
GET https://{identifier}.search.abtasty.com/search
  ?text=toy
  &rankingScoreThreshold=0.1
```

Ranking scores range from 0.0 (no match) to 1.0 (perfect match). Higher thresholds return fewer but more relevant results.

**Semantic ratio**: Balance semantic search to include conceptually related products:

```
GET https://{identifier}.search.abtasty.com/search
  ?text=toy
  &semanticRatio=0.3
```

Higher semantic ratio values (closer to 1.0) bring documents from further in the semantic space into results, increasing variety but potentially reducing exact match precision.

Adjust these parameters based on your catalog characteristics and desired search behavior.
{% endstep %}

{% step %}

#### Process the API response

Handle the JSON response returned by the Search API:

**Response structure**:

```json
{
  "hits": [...],
  "facets": {...},
  "totalPages": 20,
  "totalHits": 1000,
  "hitsPerPage": 50,
  "page": 1
}
```

**Response properties**:

1. **hits**: Array of matching products with their attributes
   * Each object contains the displayable attributes configured in your search settings
   * Example properties: id, name, price, link, img\_link
2. **facets**: Aggregated filtering information
   * List type facets: Array of \[value, count] pairs
   * Range type facets: Object with min and max values
   * Use facets to build dynamic filtering interfaces
3. **totalPages**: Total number of available pages
4. **totalHits**: Total number of matching results
5. **hitsPerPage**: Number of results per page
6. **page**: Current page number

**Example hits array**:

```json
"hits": [
  {
    "id": "126455",
    "name": "Star wars lego",
    "price": 5.9,
    "link": "/starWarsLego",
    "img_link": "/103446.jpg"
  }
]
```

**Example facets object**:

```json
"facets": {
  "brand": {
    "type": "list",
    "values": [["lego", 10], ["playmobil", 5]]
  },
  "price": {
    "type": "range",
    "values": {"min": 5, "max": 100}
  }
}
```

Parse the response to display search results and build filtering interfaces on your website.
{% endstep %}

{% step %}

#### Implement pagination

Handle multi-page search results by controlling the page parameter:

**Navigate to specific pages**:

```
GET https://{identifier}.search.abtasty.com/search
  ?text=toy
  &page=0
  &hitsPerPage=20
```

**Pagination logic**:

1. Calculate total pages: Use the `totalPages` value from the response
2. Display page numbers or navigation controls based on `totalPages`
3. Update the `page` parameter when visitors navigate between pages
4. Maintain all active filters across page changes

**Example pagination implementation**:

* Current page: Read from `page` in response
* Total pages: Read from `totalPages` in response
* Next page: Increment `page` parameter by 1
* Previous page: Decrement `page` parameter by 1

Ensure pagination controls are visible and functional when `totalPages` exceeds 1.
{% endstep %}

{% step %}

#### Build dynamic filtering interfaces

Use facet data to create interactive filtering options:

**For list type facets**:

1. Extract facet values and counts from the response
2. Display as checkboxes or multi-select options
3. Show the count next to each option
4. Update the `filters` parameter when visitors select options

**Example**: Brand facet with values `[["lego", 10], ["playmobil", 5]]` displays as:

* ☐ Lego (10)
* ☐ Playmobil (5)

**For range type facets**:

1. Extract min and max values from the response
2. Display as range sliders or input fields
3. Update the `filters` parameter with appropriate operators when visitors adjust ranges

**Example**: Price facet with `{"min": 5, "max": 100}` displays as a slider from 5 to 100.

Refresh search results by making new API requests whenever visitors modify filter selections.
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.abtasty.com/search/getting-started/using-search-with-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.