Search Partle's product catalog by name or description.
Two distinct modes:
- **Default (no flags)** — fast keyword search. ~100ms. Acts like a normal
"dumb" search box: matches the literal words you typed against product
names and descriptions, with stemming. Good for queries where the user
knows the product's likely name ("BC547", "Arduino Uno", "Bosch
drill"). Returns noisy/wrong results on cross-language or attribute
queries ("compost bin" matches Spanish "composta", not real composters).
- **`super_search=True`** — slow, high-quality. ~1–2s. Run when the user
describes what they want rather than naming it: cross-language
("Schraubenzieher Set" → real screwdriver sets even without German
catalog entries), attribute-style ("small metal part with a flat
head"), or any case where the default returns junk. Embeds the query
with voyage-3-large, takes the cosine top-50 over the corpus (with an
exact-name precision boost for part numbers), then a cross-encoder
reranks them.
The two modes are mutually exclusive in practice — pick one based on
whether the user knows the product's name or is describing it.
Use this when the user asks to find a specific product or browse products
matching a query. Prefer over `search_stores` when the intent is product-led
("find a drill") rather than store-led. Use `get_product` afterwards if the
user wants full details for one specific result.
Read-only. No authentication. Rate-limited to 100 requests/hour per IP.
Args:
query: Free-text search term. In default mode, treated as keywords
(each word matched against product text). In `super_search=True`,
treated as a natural-language description.
min_price: Lower bound on price in EUR. Omit for no lower bound.
Null-priced rows are NOT excluded by this filter — pass
`has_price=True` if you need only priced listings.
max_price: Upper bound on price in EUR. Omit for no upper bound.
Tip — narrow by budget: `min_price=10, max_price=50,
sort_by="price_asc", has_price=True`. Products without a listed
price (a large fraction of the scraped catalog) sort last under
either price ordering and are kept in results unless `has_price`
filters them out.
tags: Comma-separated tag filter (e.g. "electronics,bluetooth"). Tags
are AND-ed together.
store_id: Restrict results to a single store. Use the integer `id` from
`search_stores` results.
sort_by: One of `price_asc`, `price_desc`, `name_asc`, `newest`,
`oldest`. Omit to use the default search-relevance ranking.
has_price: When True, exclude products without a listed price (~most
of the scraped catalog). Use this for competitive pricing or
budget-bounded shopping. When False, return only null-priced
listings (rarely useful). Omit to include both.
semantic: Legacy flag. Pure vector ordering, ~250ms. Mostly
superseded by `super_search=True` (which uses the same vector
retrieval plus a cross-encoder rerank for materially better
ordering at the cost of another ~700ms). Keep using it only if
you specifically want vector retrieval *without* the rerank.
super_search: **Enable for natural-language / "describe what I
want" queries.** ~1–2s. Embeds the query with voyage-3-large,
takes the cosine top-50 (with a precision boost for exact-name
matches like part numbers / SKUs), then a cross-encoder reranks
them. Use whenever the user is describing rather than naming —
cross-language ("Schraubenzieher Set"), attribute-style
("small black metal bracket"), or any case where the default
keyword path returns junk. Don't combine with cheap
browse-style queries where the user typed an exact product
name — keyword default is faster there.
On `relevance_score` here: better than the bi-encoder cosine,
but still not a "did I find what the user wanted" gauge.
Behavior to expect: gibberish or fully-off-topic queries cap
around 0.35; loosely-related catalogue clusters can score 0.7+
even when no item truly matches (a "ceramic vase" query in a
catalog with no vases but many ceramic flowerpots will still
score high). **Read the product names** before claiming a
match. The score is most useful as a relative signal within
one result set — a sharp drop between rank N and N+1 marks
where the catalog stops being useful for this query.
limit: Max results (1–100, default 20). Larger limits are slower and
consume rate budget faster.
offset: Skip this many results before returning. Use for pagination
(offset += limit on each follow-up call).
Returns:
A list of products. Each includes `id`, `name`, `price`, `currency`,
`url`, `description`, `store` (id/name/address), `tags`, `images`, a
canonical `partle_url`, and `relevance_score` (cosine similarity 0–1
between the query and the product's embedding when a query was
provided; `None` otherwise). **Always share `partle_url` with the
user so they can view the listing.**
Caveat on `relevance_score`: it is monotonic *within a single search
result set* (useful for spotting a big drop-off between rank 3 and
rank 4), but its absolute value is not well-calibrated across
queries — most results land in 0.55–0.80 regardless of whether the
catalog has truly relevant items. Don't infer "this is a great
match" from a 0.75 score alone.
