Skip to main content

​
POST /products/search

curl -X POST http://localhost:8000/products/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "I need a laptop for programming",
    "limit": 5
  }'
Perform semantic search on products using natural language queries. This endpoint uses vector similarity search with pgvector and Google’s Gemini AI to find relevant products and provide intelligent recommendations.

​
Request body

​
query
string
required
Natural language search query describing what the user is looking for
​
limit
integer
default:"5"
Maximum number of products to return in the search results

​
Response

​
query
string
The original search query submitted by the user
​
recommendation
string
AI-generated recommendation text from Google Gemini based on the search results and query context
​
results
array
Array of products matching the search query, ordered by semantic similarity
{
  "query": "I need a laptop for programming",
  "recommendation": "Based on your search for a programming laptop, I recommend the HP Pavilion 15. It features an Intel Core i5 processor and 8GB RAM, which provide good performance for development tasks. The 256GB SSD ensures fast boot times and application loading.",
  "results": [
    {
      "id": 1,
      "name": "Laptop HP Pavilion 15",
      "description": "15.6 inch laptop with Intel Core i5, 8GB RAM, 256GB SSD",
      "category": "Electronics"
    },
    {
      "id": 2,
      "name": "Dell XPS 13 Developer Edition",
      "description": "Compact laptop with Intel Core i7, 16GB RAM, optimized for developers",
      "category": "Electronics"
    }
  ]
}

​
How it works

The semantic search process:
  1. Query embedding: Your natural language query is converted to a 3072-dimensional vector using Google’s Gemini embedding model
  2. Vector similarity: The query vector is compared against all product embeddings in the database using cosine similarity via pgvector
  3. Result ranking: Products are ranked by semantic similarity score, not just keyword matching
  4. AI recommendation: The top results are sent to Google Gemini LLM along with the original query to generate a personalized recommendation
Unlike traditional keyword search, semantic search understands the meaning and intent behind your query. Searching for “laptop for programming” will match products even if they don’t contain those exact words.

​
Example queries

Here are some example natural language queries you can use:
  • “I need something for gaming”
  • “Looking for professional work clothes”
  • “Want to buy ingredients for Italian cooking”
  • “Need a gift for a tech enthusiast”
  • “Searching for outdoor camping equipment”
The system understands context and intent, returning relevant results even with varied phrasing.

Build docs developers (and LLMs) love

Get started for freeTalk to us