Semantic search API: what it is and how to choose one

What exactly does a semantic search API do?

Three things, always the same, whatever the provider:

1. It indexes your catalogue. It turns each element into a numeric vector, called an embedding, that represents its meaning. Two texts that mean the same end up close together, even if they use different words.
2. It turns each query into a vector with the same model.
3. It returns the elements closest to the query, ordered by a similarity score.

That is why “cordless earphones for running” can return “Bluetooth sports headphones”: they share no words, but their vectors are close.

How is it different from a keyword search engine?

A keyword search engine compares letters: it finds what contains the terms of the query. It works very well with codes, references and exact names, and fails with synonyms and with queries that describe a need. A semantic one does the opposite. The best results come from combining the two, and that is called hybrid search. We cover it in semantic search versus keyword search.

What do I need to use one?

• Your data as short texts: one product, one article or one question per element.
• An API key, which is secret and lives on your server.
• An HTTP call from your server every time someone searches.

With XEYE, this is the call. The list name and the search text are the only required fields:

curl -X POST https://search.xeye.es/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $XEYE_API_KEY" \
  -d '{
    "list_name": "products",
    "search_term": "cordless earphones for running",
    "limit": 5
  }'

And the response brings each result with its score and with the parameters you stored alongside the element, so you can render it without a second query:

{
  "success": true,
  "results": [
    {
      "item": "Wireless Bluetooth headphones with noise cancelling",
      "score": 0.93,
      "params": {
        "id": 1842,
        "sku": "HP-BT-900",
        "url": "/products/bluetooth-headphones-900",
        "price": 89.9
      }
    }
  ],
  "total_results": 1,
  "duration_ms": 42
}

The full reference for parameters, errors and limits is in the API integration guide.

What should I look at when choosing one?

When do I not need one?

• If your users search mostly by exact code or reference, a keyword search engine is enough and cheaper.
• If you need facets, filters and results as you type with the interface included, a full search product suits you better. We compare them in XEYE versus Algolia.
• If your data is already in PostgreSQL and you have someone to code it, you can do it in your own database. We compare them in XEYE versus pgvector.
• If you handle millions of documents or need aggregations, see XEYE versus Elasticsearch.

How do I get started with XEYE?

1. Create an account. You start with welcome credit and no card is needed.
2. Create a list, mark it as public and add elements by hand or by importing a JSON file.
3. Launch the training from the Trainings tab and wait for it to finish.
4. Try searches in the console playground, which is free.
5. Create an API key and call the endpoint from your server.

The full walkthrough, step by step, is in getting started. If you use Nuxt, Shopify or WooCommerce, there is a tutorial for each in resources.