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

1

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.

2

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

3

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.

4

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.

5

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.

6

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.

7

Process the API response

Handle the JSON response returned by the Search API:

Response structure:

{
  "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:

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

Example facets object:

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

8

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.

9

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.