> For the complete documentation index, see [llms.txt](https://help.bizmachine.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.bizmachine.com/api-a-integrace/api-endpointy/endpoint-suggest.md).

# Endpoint suggest - vyhledávání firem

*Aktualizováno: 30. července 2026*

## Endpoint: suggest (vyhledávání firem)

```
GET /{dataset}/v4/companies/suggest
```

Vyhledá firmy podle **názvu**, **IČO**, **DIČ** nebo **webové domény**. Pro každou nalezenou firmu vrátí základní identifikaci - název, IČO, město a web. Výchozí vyhledávání prohledává všechna tato pole zároveň - stačí jeden parametr `Query`.

***

### Kdy tento endpoint použít

* Znáte název firmy nebo doménu a potřebujete zjistit IČO
* Stavíte vyhledávací pole, kde uživatel začne psát název, IČO, DIČ nebo web firmy a dostane okamžité návrhy
* Jako první krok v pipeline před voláním `aggregated-data`, `metrics` nebo jiných endpointů

#### Podle čeho lze vyhledávat

Výchozí vyhledávání (bez `FieldsToSearch`) prohledává **všechna pole zároveň**. Není nutné žádné dodatečné nastavení:

| Příklad dotazu         | Co se hledá                                     |
| ---------------------- | ----------------------------------------------- |
| `Query=BizMachine`     | Název firmy (funguje i na část: `Query=BizMac`) |
| `Query=27082440`       | IČO firmy                                       |
| `Query=CZ27082440`     | DIČ firmy                                       |
| `Query=bizmachine.com` | Webová doména - najde firmu i bez shody v názvu |

#### Kdy použít jiný endpoint

| Potřebujete                          | Použijte místo toho    |
| ------------------------------------ | ---------------------- |
| Znáte IČO a chcete data o firmě      | `aggregated-data` (v4) |
| Hromadný dotaz na více firem zároveň | Kolekční endpointy     |

***

### Technické informace

{% openapi src="/files/XsgqAcv6XJjIzqRU0Ubr" path="/{dataset}/v4/companies/suggest" method="get" %}
[api-spec.temp.json](https://2865951599-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9IXbHwc2ctAHDxOoCdoX%2Fuploads%2Fgit-blob-de88966fec10805d50f17dc1d05ba0ecb23e8eb2%2Fapi-spec.temp.json?alt=media)
{% endopenapi %}

#### Na co si dát pozor

* Vyhledávání funguje i na část názvu - `Query=BizMac` najde BizMachine s.r.o. Výsledky jsou řazeny podle relevance, ne abecedně - vždy ověřte název a město.
* Bez parametru `FieldsToSearch` query prohledává všechna pole zároveň (název, IČO, DIČ, web a další).
* Parametrem `Limit` určíte počet výsledků na jeden dotaz (1-200, výchozí hodnota je 5).

***

### Instrukce pro AI agenty

Zkopírujte tento blok a předejte ho agentovi - popisuje, jak endpoint správně používat.

```
## BizMachine API: suggest endpoint (company search / lookup)

Purpose: Search for companies by name or domain and retrieve their national identifier (IČO / nationalIn)
for use with other BizMachine API endpoints.

When to use:
- You have a company name and need its IČO
- You have a domain/website and need the company's IČO
- You are implementing autocomplete over company data
- As the first step in a pipeline before calling aggregated-data, metrics, contacts, etc.

When NOT to use:
- You already know the IČO → call the target endpoint directly
- Bulk search by filters (region, NACE, size) → use collection endpoints

URL:
  GET https://api.bizmachine.com/{dataset}/v4/companies/suggest

Required:
  - Path: dataset — "cz", "sk", "hu", "pl", "de"
  - Query: Query — search string (company name, IČO, DIČ, or domain)
  - Header: X-Api-Key: {api_key}

Optional:
  - Query: Limit — number of results (1–200, default 5)

Key response fields:
  data[0].nationalIn             — company IČO → use as {nationalIn} in other endpoints
  data[0].uniqueId               — unique ID (format: "cz-company-27082440")
  data[0].name                   — company name
  data[0].city                   — city (use to verify correct company)
  data[0].contacts.website.url   — company website

Search behavior:
  - Default search (no FieldsToSearch) queries all fields simultaneously (name, IČO, DIČ, website, and more)
  - Partial name match works: "BizMac" will find "BizMachine s.r.o."
  - Domain search works without any extra parameters: Query=bizmachine.com finds "BizMachine s.r.o."
  - Use Limit to control number of results (1–200, default 5)

Gotchas:
  - data[0] is the most relevant result but always verify via name + city
  - Relevance ranking is not purely alphabetical — short queries may return larger companies first

Typical workflow (name to IČO):
  1. suggest?Query={company_name}&Limit=1  → get nationalIn from data[0].nationalIn
  2. /{dataset}/v4/companies/{nationalIn}/aggregated-data  → get company profile

Typical workflow (domain to IČO):
  1. suggest?Query={domain}&Limit=1  → get nationalIn from data[0].nationalIn
  2. Call target endpoint with nationalIn
```

***

Potřebujete pomoc? Ozvěte se na <support@bizmachine.com>