# Endpoint suggest — vyhledávání firem

*Aktualizováno: 8. dubna 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.bizmachine.com/api-a-integrace/api-endpointy/endpoint-suggest.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.