API referencia

Vyhľadávanie firiem podľa názvu alebo IČO

GET /v1/search: parametre vyhľadávania slovenských a českých firiem, filtre, stránkovanie a JSON odpoveď.

Vyskúšaj tento endpoint 
{ "stav": "pripravený" }

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.

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)

{
  "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í.

Chyba (400)

{
  "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.
  • 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.
  • 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í.
  • 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.
  • 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. Limity a hlavičky sú na stránke Rate limity.

Táto stránka vo formáte Markdown