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
- OppAlerts turns each document into a vector: a list of numbers that represents its subject.
- Your search text is turned into a vector in the same way.
- OppAlerts finds the documents with the nearest vectors.
- Each result gets a similarity score from 0 to 100 percent, showing how close the vectors are.
What the search compares with
- Your own text: Similarity text in the web app,
"similarity_target": "similarity_text"with the text insimilarity_textin 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_scoreis 0 to 100. It is the cosine similarity of the two vectors, times 100.- It is
nullwhen 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
ORorMAYBEsays otherwise. See Advanced Search Operators. - A page must then match the words, be at or above Min similarity, and pass every other filter.
relevance_weightis 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.