# GET /v1/search

Vyhľadávanie firiem podľa obchodného názvu alebo IČO. Vracia stránkovaný zoznam výsledkov z SK databázy, z ARES (CZ), alebo z oboch.

```bash
curl "https://api.subjekt.sk/v1/search?q=slovnaft&country=sk&limit=1"
```

## Parametre

| Parameter | Typ | Povinný | Predvolená hodnota | Popis |
|---|---|---|---|---|
| `q` | string | áno | — | Obchodný názov alebo IČO, 2 až 120 znakov. Hľadá sa v názve a IČO, nie v adrese. Jednopísmenové slová sa porovnávajú iba so začiatkom názvu, dvojpísmenové musia v názve byť celé alebo na jeho začiatku. |
| `country` | string | nie | `both` | Krajina: `sk`, `cz` alebo `both` |
| `limit` | integer | nie | `10` | Počet výsledkov na stránku (1 – 50) |
| `cursor` | string | nie | — | Cursor z predchádzajúcej odpovede pre ďalšiu stránku |
| `prefer` | string | nie | `sk` | Preferovaná krajina pri `country=both`: `sk` alebo `cz` |
| `entity_type` | string | nie | `all` | Filter SK výsledkov: `all`, `companies` alebo `individuals`. CZ výsledky z ARES sa týmto parametrom nefiltrujú. |

## Odpoveď (200)

```json
{
  "results": [
    {
      "ico": "31322832",
      "name": "SLOVNAFT, a.s.",
      "address": {
        "street": "Vlčie hrdlo",
        "building_no": "1",
        "city": "Bratislava",
        "zip": "82412",
        "country": "SK"
      },
      "legal_form": "Akciová spoločnosť",
      "dic": "2020372640",
      "ic_dph": "SK7120001713",
      "established": "1992-05-01",
      "registration": {
        "office": "Mestský súd Bratislava III",
        "number": "Sa/426/B"
      }
    }
  ],
  "count": 1,
  "country": "sk",
  "ms": 77,
  "next_cursor": "eyJvIjoxLCJlIjoxNzkwNjU5NzgxLCJxIjoic2xvdm5hZnQiLCJjIjoic2siLCJwIjoic2siLCJsIjoxLCJ0IjoiYWxsIn0=",
  "truncated": false,
  "warnings": []
}
```

Popis polí nájdete v [schémach odpovedí](../schemy-odpovedi.md).

## Chyba (400)

```json
{
  "code": "invalid_request",
  "message": "Missing q parameter",
  "request_id": "d2be5a4f-ae16-4f95-b75f-8cd6478f4f50"
}
```

## Poznámky k správaniu

- Ak je `q` osemciferné číslo, prebehne presné vyhľadanie podľa IČO, nie fulltextové.
- `country` v odpovedi opakuje požadovaný filter. Skutočná krajina výsledku je v `address.country`; tú pošlite pri načítaní [detailu](./entity.md).
- Pri `country=both` je poradie výsledkov deterministické: presná zhoda IČO → relevancia → krajina podľa `prefer`.
- `entity_type=companies` vráti iba slovenské právnické osoby a organizácie, `entity_type=individuals` iba slovenských podnikateľov – fyzické osoby.
- Ak odpoveď obsahuje `next_cursor`, pošlite ho späť ako `cursor` pre ďalšiu stránku. Cursor platí 15 minút.
- Pri fyzických osobách – podnikateľoch (živnostníkoch) vyhľadávanie nevracia ulicu ani číslo domu, iba mesto a PSČ, lebo adresa podnikania je často adresou bydliska. Celú adresu vráti [detail subjektu](./entity.md).
- Ak ARES odmietne príliš všeobecný dopyt (viac ako 1 000 zhôd v CZ), `country=both` vráti SK výsledky a v `warnings` kód `cz_query_too_broad`; `country=cz` vráti `400`. Pozri [Schémy odpovedí](../schemy-odpovedi.md).
- Jeden dopyt vráti najviac 250 výsledkov. `truncated: true` na poslednej stránke znamená, že zhôd je viac a treba spresniť `q`. Pozri [Stránkovanie](../strankovanie.md).
- Chyba ARES vráti `502` alebo `504` aj pri `country=both`; API nevráti len slovenskú časť.
- CZ dáta sú informatívne, pozri [Prehľad](../prehlad.md). Limity a hlavičky sú na stránke [Rate limity](../rate-limity.md).