Semantic Search

GET

/v1/semantic-search

AI-powered search using vector embeddings. Returns results ranked by semantic similarity to your query.

Unlike keyword search which matches exact words, semantic search understands the meaning of your query. For example, searching "eco-friendly packaging" will find businesses that mention "sustainable wrapping materials" even though the words don't overlap.

How It Works

Your query text is converted to a 1536-dimensional vector using OpenAI's text-embedding-3-small model
The vector is compared against pre-computed embeddings for all businesses and products in the directory using pgvector cosine similarity
Results above the similarity threshold are returned, ranked by relevance
Each result includes a similarity score (0-1, where 1 = perfect match)

Query Parameters

Parameter	Type	Default	Description
`q`	string	—	Required. Natural language search query
`types`	string	`business,product`	Comma-separated types to search: `business`, `product`, or both
`limit`	integer	10	Max results per type (1-50)
`threshold`	float	0.3	Minimum similarity score (0-1). Lower = more results, less relevant
`include_internal`	boolean	`false`	Include businesses with `internal` visibility

Example Request

cURLbash

curl "https://rjpxllsycikfabazvkdh.supabase.co/functions/v1/directory-api/v1/semantic-search?q=organic%20food%20supplier%20bali&types=business&limit=5&threshold=0.25" \
  -H "X-API-Key: your-key"

TypeScripttypescript

const results = await directoryApi(
  '/v1/semantic-search?q=organic food supplier bali&types=business&limit=5'
);

for (const biz of results.businesses) {
  console.log(`${biz.name} (similarity: ${biz.similarity.toFixed(3)})`);
}

Response

{
  "query": "organic food supplier bali",
  "businesses": [
    {
      "id": "uuid-1",
      "name": "Bali Organic Farm Co.",
      "slug": "bali-organic-farm-co",
      "description_en": "Certified organic produce and health food supplier...",
      "category_id": "cat-uuid",
      "region_id": "bali-uuid",
      "verified": true,
      "featured": false,
      "similarity": 0.847
    },
    {
      "id": "uuid-2",
      "name": "Green Earth Provisions",
      "slug": "green-earth-provisions",
      "description_en": "Natural and sustainable food distribution...",
      "similarity": 0.723
    }
  ],
  "products": [],
  "total_businesses": 2,
  "total_products": 0
}

Use Cases

Natural language supplier discovery: "affordable furniture maker that ships to Jakarta"
Finding related suppliers: Use a product description as the query to find suppliers offering similar items
Multilingual search: Queries in English will match businesses with descriptions in Indonesian if the meaning aligns
AI agent integration: Use as a context-gathering step before sending results to an LLM

Semantic search requires an OpenAI API key configured on the server. If not configured, the endpoint returns a 503 Service Unavailable error.

Hybrid Search

Last updated on March 15, 2026