Natural Language Product Search: From Plain English Queries to Typed JSON

Why keyword search keeps failing your users

Open the search bar on any e-commerce site and watch real queries roll in. You'll see things like:

• "lightweight running shoes for marathon under €100"
• "a quiet dishwasher that fits in a 60cm gap"
• "warm winter jacket but not bulky, with a hood"
• "laptop for my kid in college, mostly for writing essays and zoom"

None of these are keyword queries. They are natural-language product queries — full sentences with constraints, intent, and context. A traditional search index, even one with synonyms and typo tolerance, will return something for each — usually the wrong something.

A real natural language product search experience starts from the assumption that the user is describing what they want, not naming it. This article walks through how to build that — what the system needs to understand, how to ground results in real product data, and where teams reliably fall into traps.

What "natural language search" actually means

The phrase gets used loosely. To be precise, a useful AI product search layer does four things:

1. Parses intent — distinguishes "running shoes" (category) from "lightweight" (attribute) from "for marathon" (use case) from "under €100" (constraint).
2. Maps to structured constraints — translates fuzzy language into filters: category=running_shoes, weight_g<250, price_eur<100.
3. Retrieves candidates — returns products that satisfy the constraints, ideally typed and structured.
4. Ranks by relevance — surfaces the products that best fit the whole query, not just the keywords.

The first two are language understanding. The last two are retrieval and ranking. A keyword index handles only the last two, badly, because it doesn't know what the user meant.

The shape of the response matters

A semantic product search API is only useful if its response is structured. Returning a list of 50 product pages and asking the application to figure out the constraints is the same problem you started with — you've just moved the work.

What you want back is closer to this:

{
  "query_understood": {
    "category": "running_shoes",
    "constraints": {
      "weight_g": { "max": 250 },
      "price_eur": { "max": 100 },
      "use_case": "marathon"
    }
  },
  "products": [
    {
      "brand": "Asics",
      "model": "Magic Speed 3",
      "category": "running_shoes",
      "weight_g": 210,
      "price_eur": 95,
      "image": "https://...",
      "match_reason": "lightweight, marathon-oriented, in budget"
    }
  ]
}
Show more (21 lines)

Now the application can render the result with confidence: it knows why each product matched, it has typed fields it can re-rank or filter further, and it can show the user a chip-style summary of how their query was interpreted (a huge trust win for conversational UIs).

A request that maps to a sentence

A search endpoint that supports natural-language queries shouldn't require you to pre-parse the query yourself. You pass the sentence; the API does the understanding:

curl "https://productapi.dev/api?search=lightweight+running+shoes+for+marathon+under+100+euros&country=FR&lang=fr&currency=EUR&fields=brand,model,weight_g,price_eur,image" \
  -H "X-API-Key: your-api-key"

The user wrote a sentence; the API returns typed products with the constraints already applied. Your front end doesn't need an NLP layer of its own.

Why retrieval has to be grounded

A big risk in any AI-flavored search is hallucination — the system returning a product that sounds right but doesn't actually exist, or attributing specs to it that aren't true. For a search bar, this is fatal: a user clicks through, the product doesn't exist or has different specs, and trust is gone.

A grounded product search retrieves real products from real sources and returns their actual fields. The language model parses the query, but it doesn't invent the result. The structured fields you get back are tied to the actual product, not synthesized.

In practice, this means:

• Every product in the response has a verifiable name and brand.
• Numeric fields (weight, price, battery life) are sourced, not generated.
• Descriptions are constrained by the structured facts.
• Out-of-catalog queries return an honest empty result, not a confident-looking fabrication.

If you're building search for a domain where wrong answers are costly (e-commerce, regulated categories, B2B procurement), grounding is the line between something users trust and something they screenshot for the bad-AI Twitter timeline.

Designing the UX around natural-language search

The API is half the problem. The other half is UX. A few patterns that work:

Show the query interpretation back

When the user types a complex sentence, render a chip strip with the parsed constraints: Category: running shoes · Weight: ≤250g · Budget: €100 · Use: marathon. Let them click to remove or edit any constraint. This makes the magic visible and gives users control when the parse isn't quite right.

Don't snap to zero results

If a strict interpretation returns nothing, soften the constraints automatically and label the result clearly: "No marathon-ready running shoes under €100; here are the closest matches under €130." Hard-fail UX punishes users for being specific.

Make follow-up queries cheap

Conversational search lives or dies on iteration. "Show me lighter ones." "What about with a wider toe box?" "Same but for trail running." Treat the search bar as a chat surface, not a single-shot input — preserve query context across turns.

Mix structured filters with natural language

Don't replace your filter sidebar — pair them. The natural-language query sets the initial constraints; the filter chips let the user adjust. The two work together, especially as users gain trust.

When to use it (and when not to)

A natural-language product search layer is the right choice when:

• Users describe what they want in sentences (gift guides, buying advice, complex specs).
• Your catalog is broad enough that strict-match keyword search misses obvious answers.
• You're building an AI shopping agent or conversational commerce surface.
• You want to support queries in multiple languages without maintaining one synonym list per locale.

It is not the right choice when:

• Your queries are all SKU lookups. Keyword search is faster and more predictable.
• Your catalog is narrow and well-faceted (a 50-product brand site doesn't need NLP).
• You need sub-50ms p99 latency on every query. Grounded retrieval is meaningfully slower than a local Elasticsearch shard.

Most teams want it on the discovery surface (category pages, gift finders, agent integrations) and keep keyword/SKU search on the transactional surface (header search, "buy this exact thing again").

Multilingual search comes (almost) free

A pleasant side effect of grounded natural-language search is that it handles non-English queries without an explicit translation step. The user writes in their language; the API understands it and returns localized products.

curl "https://productapi.dev/api?search=lave-vaisselle+silencieux+60+cm+moins+de+700+euros&country=FR&lang=fr&currency=EUR" \
  -H "X-API-Key: your-api-key"

Same call, French sentence in, French product names out, in euros, available in France. You did not maintain a French synonym dictionary. You did not write a translation middleware. The API handled it.

This is where natural-language search compounds with localized product data — you get cross-language search and locale-correct results in one request.

How it slots into AI agents

For LLM-driven shopping agents, natural-language product search is the obvious tool-use surface. The agent doesn't have to pre-parse the user's request; it forwards the sentence to a single tool, gets back a typed list, and reasons over the structured response.

const tool = {
  name: "search_products",
  description: "Search the product catalog using natural language. Returns typed product records.",
  input_schema: {
    type: "object",
    properties: {
      query: { type: "string" },
      country: { type: "string" },
      currency: { type: "string" },
      lang: { type: "string" },
    },
    required: ["query"],
  },
};

Forward the user's message to this tool, get back grounded products, let the model summarize. This is the spine of every well-built shopping agent. See grounding AI shopping agents for the full pattern.

Pitfalls to avoid

A few traps that bite teams the first time they ship natural-language search:

Treating it like a chatbot

A search bar is not a chat surface unless you commit to building one. If your UI is a single input and a list of products, keep responses concise and structured — don't have the model write a paragraph about each result.

Hiding the interpretation

Users distrust AI surfaces they can't see into. Always show what the system thought the query meant, even when you got it right. Especially when you got it right.

Over-promising on inventory accuracy

Natural-language search is great at finding products. It is not a real-time inventory feed. Don't render "in stock at MegaShop right now" against a search result unless you have a direct retailer integration. Keep the search layer about discovery; let your checkout layer handle live availability.

Skipping evals

The thing about natural-language interfaces is they break in ways keyword search doesn't. Build an eval set — a fixed list of queries with expected categories, expected constraints, and expected top-3 results — and run it on every API change. Catch regressions before users do.

Try it

A sentence in, typed products out:

curl "https://productapi.dev/api?search=quiet+60cm+dishwasher+under+700+euros&country=FR&lang=fr&currency=EUR&fields=brand,model,db_noise,width_cm,price_eur" \
  -H "X-API-Key: your-api-key"

Get an API key — 20 free credits, no card required.

TL;DR

• Users describe products in sentences, not keywords. Natural language product search treats that as the input format, not a problem to be normalized away.
• A good semantic product search API parses the query into structured constraints, retrieves grounded products, and returns typed fields you can re-rank.
• Show the parsed interpretation in the UI. Soften constraints instead of hard-failing. Keep keyword search for transactional surfaces and SKU lookups.
• Grounded retrieval gives you cross-language search and locale-correct results without a synonym dictionary per region.
• Build an eval set. Natural-language interfaces drift in ways keyword search doesn't.