Endpoint suggest - vyhledávání firem

Vyhledávání firem podle názvu nebo domény - získání IČO pro použití v dalších API voláních.

Aktualizováno: 30. července 2026

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

Company Search

get

/{dataset}/v4/companies/suggest

Authorizations

X-Api-KeystringRequired

Authorization header which caries ApiKey information. Copy value generated using ApiKey endpoint.
Example: abcdefgh-1234-5678-90yz-ijklmnopqrs

Path parameters

datasetstring · nullableRequired

Target dataset scope.

Query parameters

QuerystringRequired

Query string to search for in data.

FieldsToSearchstring[] · nullableOptional

Collection of fields to search in.

Limitinteger · int32 · min: 1 · max: 200Optional

Number of results to return. Default is 5.

Responses

200

Success

application/json

get/{dataset}/v4/companies/suggest

GET /{dataset}/v4/companies/suggest?Query=text HTTP/1.1
Host: api.bizmachine.com
X-Api-Key: YOUR_API_KEY
Accept: */*

200

Success

{
  "data": [
    {
      "uniqueId": "text",
      "nationalIn": "text",
      "name": "text",
      "city": "text",
      "contacts": {
        "website": {
          "url": "https://example.com"
        }
      },
      "highlights": {
        "ANY_ADDITIONAL_PROPERTY": [
          "text"
        ]
      }
    }
  ]
}

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 [e-mail]