Documentation / The Data / How Semantic Search Works

How Semantic Search Works

Find pages about your subject, even when they use different words.

Semantic similarity, not words

A keyword search finds pages containing your words. A semantic search finds pages about the same subject. A search for "reducing restaurant food waste" can find a page about "kitchen efficiency": the words differ, but the subjects are related.

How it works

  1. OppAlerts turns each document into a vector: a list of numbers that represents its subject.
  2. Your search text is turned into a vector in the same way.
  3. OppAlerts finds the documents with the nearest vectors.
  4. Each result gets a similarity score from 0 to 100 percent, showing how close the vectors are.
  • Your own text: Similarity text in the web app, "similarity_target": "similarity_text" with the text in similarity_text in MCP and the API. Write one to three sentences that describe the subject, with enough context to distinguish it from related subjects.
  • Your campaign: a stored description of your market, based on AI model answers about your industry when the campaign was finalized. The type pages and many brand pages use it. In MCP and the API, send "similarity_target": "campaign".
  • One document: Similar News and Similar Prospects find the pages nearest to one result.

The similarity score

  • similarity_score is 0 to 100. It is the cosine similarity of the two vectors, times 100.
  • It is null when the search had no vector ("similarity_target": "none"). It is never 0 for "no similarity".
  • Min similarity excludes results below your chosen value. Advanced Search defaults to 30%, and the saved opportunity form also defaults to 30. In MCP and the API, the field is similarity_score_min, and it has no default.
  • Consider the order of results and the gaps between them, alongside the score.

Semantic similarity and words together

  • Add Title query or Body query words. Every word you enter is required, unless an operator such as OR or MAYBE says otherwise. See Advanced Search Operators.
  • A page must then match the words, be at or above Min similarity, and pass every other filter.
  • relevance_weight is the word-match weight. It has no upper limit: compare it only with other results in the same response.

Limits

  • A semantic search in the web app shows at most 100 rows. A call to an MCP or API search tool returns at most 1,000 rows, and at most 100 on a free account.
  • It starts with a limited set of candidates, then filters and groups them. Changing your text can bring in different candidates and produce a new list.
  • Finding no results does not mean nobody has written about the subject. Rephrase your text or lower Min similarity.

Tips

  • Describe the situation, not one keyword: "restaurants that cannot fill shifts at short notice, and the effect on service" beats "staffing".
  • If the results cover a related subject, add details that distinguish your subject from it.
  • If the results match your subject, read them before changing the text.