ARES API – návod k REST API

1. Detail firmy podle IČO

Nejjednodušší volání je GET /ekonomicke-subjekty/{ico}. IČO musí mít přesně 8 číslic – kratší doplňte zleva nulami.

curl "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/27082440"

Zkrácená odpověď:

{
  "ico": "27082440",
  "obchodniJmeno": "Alza.cz a.s.",
  "dic": "CZ27082440",
  "pravniForma": "121",
  "datumVzniku": "2003-08-26",
  "sidlo": {
    "textovaAdresa": "Jankovcova 1522/53, Holešovice, 17000 Praha 7",
    ...
  },
  "seznamRegistraci": {
    "stavZdrojeVr": "AKTIVNI",
    "stavZdrojeRzp": "AKTIVNI",
    ...
  },
  ...
}

Pole seznamRegistraci říká, ve kterých zdrojových registrech subjekt je (VR = veřejný rejstřík, RŽP = živnostenský rejstřík…). Podle něj poznáte, který specializovaný endpoint má smysl volat dál.

2. Vyhledání firem podle názvu

Pro vyhledávání slouží POST /ekonomicke-subjekty/vyhledat s JSON filtrem. Kromě obchodniJmeno můžete filtrovat podle ico (pole, takže načtete více IČO jedním dotazem), sidlo, pravniForma nebo czNace.

curl -X POST "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/vyhledat" \
  -H "Content-Type: application/json" \
  -d '{"obchodniJmeno": "seznam", "start": 0, "pocet": 10}'

Odpověď:

{
  "pocetCelkem": 11,
  "ekonomickeSubjekty": [
    { "ico": "01673408", "obchodniJmeno": "Seznam.cz datová centra, s.r.o.", ... },
    { "ico": "02238586", "obchodniJmeno": "Seznam.cz investiční, s.r.o.", ... },
    ...
  ]
}

pocetCelkem je celkový počet shod, stránkujete pomocí start a pocet.

3. Ukázka v JavaScriptu

const ARES = "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest";

// Detail firmy podle IČO
async function firmaPodleIco(ico) {
  const res = await fetch(`${ARES}/ekonomicke-subjekty/${ico.padStart(8, "0")}`);
  if (res.status === 404) return null; // subjekt neexistuje
  if (!res.ok) throw new Error(`ARES: ${res.status}`);
  return res.json();
}

// Vyhledání firem podle obchodního jména
async function hledatFirmy(nazev) {
  const res = await fetch(`${ARES}/ekonomicke-subjekty/vyhledat`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ obchodniJmeno: nazev, start: 0, pocet: 20 }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.popis);
  return data.ekonomickeSubjekty ?? [];
}

4. Ukázka v Pythonu

import requests

ARES = "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest"

def firma_podle_ico(ico: str) -> dict | None:
    r = requests.get(f"{ARES}/ekonomicke-subjekty/{ico.zfill(8)}", timeout=10)
    if r.status_code == 404:
        return None  # subjekt neexistuje
    r.raise_for_status()
    return r.json()

def hledat_firmy(nazev: str) -> list[dict]:
    r = requests.post(
        f"{ARES}/ekonomicke-subjekty/vyhledat",
        json={"obchodniJmeno": nazev, "start": 0, "pocet": 20},
        timeout=10,
    )
    data = r.json()
    if not r.ok:
        raise RuntimeError(data.get("popis"))
    return data.get("ekonomickeSubjekty", [])

5. Další endpointy podle registru

Souhrnný endpoint stačí na většinu použití. Pro podrobnější data má každý zdrojový registr vlastní dvojici GET …/{ico} a POST …/vyhledat:

6. Chyby a limity, na které narazíte

Subjekt nenalezen – HTTP 404

{
  "kod": "NENALEZENO",
  "subKod": "VYSTUP_SUBJEKT_NENALEZEN",
  "popis": "Nebyl nalezen žádný subjekt, který by odpovídal zadaným hodnotám. ..."
}

Špatné IČO – HTTP 400

IČO, které nemá přesně 8 číslic, vrátí CHYBA_VSTUPU se subkódem VSTUP_NEVALIDNI_FORMAT_ICO.

Příliš mnoho výsledků – HTTP 400

Pokud vyhledávání odpovídá více než 1 000 subjektům, ARES nevrátí ani první stránku – a to bez ohledu na parametr pocet. Obecná slova jako „servis“ nebo „stavby“ proto selžou. Dotaz zpřesněte, nebo chybu ošetřete jako „název je velmi běžný“.

{
  "kod": "CHYBA_VSTUPU",
  "popis": "Zadaný dotaz vrací příliš mnoho výsledků (6 371). Povoleno je maximálně 1 000 výsledků. ..."
}

Limit dotazů

Ministerstvo financí si vyhrazuje právo zablokovat uživatele, kteří pošlou více než 500 dotazů za minutu, opakovaně posílají stejné nebo chybné dotazy, mají příliš mnoho souběžných požadavků nebo obcházejí limity z více IP adres. Odpovědi proto cachujte a hromadné zpracování rozložte v čase.

Co ARES API neumí

ARES zná jen ekonomické subjekty. Pokud ověřujete nový název firmy nebo produktu, nestačí – nekontroluje ochranné známky (ÚPV, EUIPO, WIPO) ani dostupnost domén. A databáze ochranných známek ÚPV žádné srovnatelné REST API nemá.

Seberio tyhle kontroly spojuje do jedné. Bez programování si název můžete ověřit v ověření názvu firmy.

Často kladené otázky (FAQ)