We turn ideas into reusable, scalable and client-ready turn-key solutions!
Back to product page

API Documentation

Semantic search API

Reference details for the semantic search service that powers intent-aware product discovery, navigation, recommendations, and merchandising across any eCommerce stack.

What is this?

A platform-agnostic semantic search service that returns the most relevant products and categories based on meaning and intent (not just keywords). Delivered as an API, it can power on-site search, category navigation, recommendations, and merchandising rules across any eCommerce stack.

What it enables

  • Intent-based search that maps phrases like “quick breakfast” to the right products.
  • System-agnostic integration with Magento, Intershop, Shopify, and custom stacks.
  • Plug-and-play JSON output for search UI, autosuggest, and category routing.
  • Scalable embedding + vector retrieval architecture for growing catalogs and traffic.

Endpoint

Example request URL

https://n8n.salnl.net/webhook/64f85810-0dbb-4eda-8095-2d3cc7357ca7?query=vode&limit=4&expand=true&expand_keyword_max=5

User: test

Password: Test123

Build process

How we created it

Data preparation

  • Processed ~8,000 products and 600+ categories.
  • Cleaned and normalized feed data to remove noise and improve match quality.

Semantic indexing

  • Generated vector embeddings for products and categories with LLM embedding models.
  • Stored vectors and metadata in a vector database for fast similarity retrieval.

Query-to-results pipeline (n8n-orchestrated)

  1. API endpoint for query intake.
  2. Query understanding & expansion (intent/context enrichment, synonyms, disambiguation).
  3. Vector retrieval of top candidates from the vector database.
  4. Re-ranking to improve precision using additional relevance signals.
  5. JSON response with structured, configurable fields.

Request details

Query parameters

This endpoint performs a semantic search against a vector database and can optionally expand the query based on inferred user intent and related synonyms to improve recall.

query (string, required)
The user’s original search query, embedded as the primary semantic search input. Example: query=green salad
limit (integer, optional)
Specifies the maximum number of search results to return. Example: limit=4
expand (boolean, optional)
Controls whether the system expands the original query based on intent and synonyms. Example: expand=true
expand_keyword_max (integer, optional)
Maximum number of additional keywords when expansion is enabled. Example: expand_keyword_max=5

Applications

Example use cases

  • On-site search, including long-tail queries.
  • Recommendations like “similar items” and “frequently bought together.”
  • Bundling, kits, and cross-sell logic.
  • Category redirection and merchandising rules.
  • Internal product discovery for sales and support teams.