> ## Documentation Index
> Fetch the complete documentation index at: https://docs.istari.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Supplier discovery

> Given a product and a location, return a clean supplier shortlist, manufacturers and distributors, every time.

**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`.

```python theme={null}
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

<Warning>
  **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.
</Warning>

* **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`](/mcp/tools).
* **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).