Supplier discovery - Documentation

Inputs: product (free text) · location (a country). Returns: a deduped shortlist of suppliers. A bare POST /v2/search with only a free-text describe field mixes in repair shops, rental firms, and parts makers, and the order drifts between runs. The quality comes from disciplined parameters that this template bakes in.

The recipe

Set ISTARI_API_KEY, then swap in your product and country. The request maps to POST /v2/search.

import os
import requests

API_KEY = os.environ["ISTARI_API_KEY"]


def find_suppliers(product: str, country: str) -> list[dict]:
    body = {
        "describe": f"{product} supplier manufacturer distributor wholesale vendor",
        "keywords": {
            "must_any": [
                "supplier", "distributor", "wholesale",
                "manufacturer", "reseller", "vendor", "trading",
            ],
            "must_not": [
                "repair", "rental", "service center", "maintenance", "recruitment",
            ],
        },
        "filters": {
            "country": [country],
            "nace_code": [
                "NACE C: Manufacturing",
                "NACE G: Wholesale and retail trade",
            ],
        },
        "columns": ["domain", "name", "country", "nace_code", "organization_type"],
        "size": 12,
        "dedup": True,
    }
    resp = requests.post(
        "https://api.istari.ai/v2/search",
        headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
        json=body,
    )
    return resp.json()["data"]


for row in find_suppliers("industrial valves", "Spain"):
    print(row["domain"], "-", row["name"])

What each lever does

Lever	Role
`filters.nace_code` = C + G	The main levers. Admits makers (C) and traders (G); excludes repair, rental, consulting by category. This is what removes the noise: don’t drop it.
`describe`	Weights the product + supply intent. Self-adjusts: leans distributor for imported goods, manufacturer where made locally.
`keywords.must_any`	Forces supply-side language to be present (also required so `must_not` can run).
`keywords.must_not`	A soft down-weight, not a hard filter: real exclusion comes from NACE.
`dedup`	Collapses duplicate organization names.

Validated example

product="industrial valves", country="Spain" → a clean mix of manufacturers and distributors:

Organization	Type	NACE
Babcock Valves, Tecval, FHT, ICP Valves	Manufacturer	C
VAINDUSA, ACOM, DIMAC	Distributor	G

The same template was validated across different use cases like MacBooks (UAE, distributor-heavy), hydraulic pumps (Germany, maker-heavy), solar panels (India, mixed), electronic components (Singapore, trading hub), and surgical gloves (India — Asma, Kanam Latex, Saachi), one parameter set, product-appropriate skew in every geography.

Notes

Don’t set min_score. Keywords trigger hybrid retrieval, where a min_score of ~0.45 can collapse a clean 12-result query down to 1. Let NACE + keywords do the precision work.

Country is activity-based. GOI resolves location by where an organization is active, not solely legal HQ: a firm operating in your market can appear even if incorporated abroad. If strict incorporation matters, post-validate.
City filters are coarse. municipality=["Dubai"] can return zero (geocoding granularity). Prefer country, or region/state via resolve_location.
Ignore the Total field in keyword mode: it reports 0 while returning a full page. Count the returned rows.
For strict product matching, add "must_all": ["<core noun>"] inside keywords (fewer results, higher precision).

​The recipe

​What each lever does

​Validated example

​Notes

The recipe

What each lever does

Validated example

Notes