ARES API: REST rozhraní, příklady kódu a limity

Endpointy ARES API: základní a další

Všechny endpointy mají společný základ adresy https://ares.gov.cz/ekonomicke-subjekty-v-be/rest a odpovídají v JSON. Základní je GET /ekonomicke-subjekty/{ico}: souhrnné údaje o subjektu ze všech registrů. Pro předvyplnění odběratele nebo kontrolu dodavatele obvykle stačí jen on, a proto ho návod rozebírá do detailu. Další endpointy hledají podle jiných kritérií, hlídají změny, nebo vracejí data jednoho konkrétního registru — ARES jim říká pohledy a mají stejnou URL s příponou registru (například -vr pro veřejný rejstřík). U nich odkazujeme rovnou na oficiální dokumentaci ve Swagger UI (verze rozhraní 1.4.0).

Každý pohled má vedle GET …/{ico} i hledání POST …/vyhledat (například POST /ekonomicke-subjekty-vr/vyhledat) — parametry najdete ve Swagger UI u daného pohledu. Celý popis rozhraní: Swagger UI, strojově OpenAPI.

Základní endpoint: firma podle IČO

GET https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/{ico} vrátí souhrnné údaje o jednom subjektu — firmě, OSVČ, úřadu nebo spolku. IČO musí mít vždy 8 číslic (kratší doplňte nulami zleva: 177041 → 00177041). Nepotřebujete klíč ani zvláštní hlavičky.

Volání z kódu

Ukázky načtou Škoda Auto a.s. (IČO 00177041) a vypíšou název a adresu sídla; funkce v PHP, Pythonu a JavaScriptu vrátí pro neexistující IČO prázdnou hodnotu místo chyby. Tlačítko „Vyzkoušet živě" vyplní stejné IČO do formuláře nahoře.

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

<?php
function aresSubjekt(string $ico): ?array
{
    // ARES chce přesně 8 číslic: 177041 → 00177041
    $ico = str_pad(preg_replace('/\D/', '', $ico), 8, '0', STR_PAD_LEFT);
    $url = 'https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/' . $ico;

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_HTTPHEADER     => ['Accept: application/json'],
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

    if ($code === 404) {
        return null; // subjekt v ARES není
    }
    if ($body === false || $code !== 200) {
        throw new RuntimeException("ARES vrátil HTTP $code");
    }
    return json_decode($body, true, 512, JSON_THROW_ON_ERROR);
}

$firma = aresSubjekt('177041');
echo $firma['obchodniJmeno'], ' – ', $firma['sidlo']['textovaAdresa'], PHP_EOL;

import requests

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

def ares_subjekt(ico: str) -> dict | None:
    ico = "".join(c for c in ico if c.isdigit()).zfill(8)  # 177041 → 00177041
    r = requests.get(f"{ARES}/ekonomicke-subjekty/{ico}", timeout=10)
    if r.status_code == 404:
        return None  # subjekt v ARES není
    r.raise_for_status()
    return r.json()

firma = ares_subjekt("177041")
print(firma["obchodniJmeno"], "–", firma["sidlo"]["textovaAdresa"])

async function aresSubjekt(ico) {
  ico = String(ico).replace(/\D/g, '').padStart(8, '0'); // 177041 → 00177041
  const res = await fetch(
    `https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/${ico}`,
    { headers: { Accept: 'application/json' } }
  );
  if (res.status === 404) return null; // subjekt v ARES není
  if (!res.ok) throw new Error(`ARES vrátil HTTP ${res.status}`);
  return res.json();
}

const firma = await aresSubjekt('177041');
console.log(firma.obchodniJmeno, '–', firma.sidlo.textovaAdresa);

PHP ukázka potřebuje rozšíření curl, Python knihovnu requests a verzi 3.10 nebo novější, JavaScript běží v prohlížeči i v Node.js 18+.

Co základní endpoint vrací

Odpověď je JSON objekt. Tady je zkrácená skutečná odpověď pro Škoda Auto (zachycená 1. 10. 2026, vynechané části označuje „…"):

{
  "ico": "00177041",
  "obchodniJmeno": "Škoda Auto a.s.",
  "sidlo": {
    "kodStatu": "CZ",
    "kodObce": 535419,
    "nazevObce": "Mladá Boleslav",
    "nazevUlice": "tř. Václava Klementa",
    "cisloDomovni": 869,
    "psc": 29301,
    "kodAdresnihoMista": 21249407,
    "textovaAdresa": "tř. Václava Klementa 869, Mladá Boleslav II, 29301 Mladá Boleslav"
  },
  "pravniForma": "121",
  "financniUrad": "013",
  "datumVzniku": "1990-11-20",
  "datumAktualizace": "2026-09-16",
  "dic": "CZ00177041",
  "czNace": ["70200", "471", "77110", "…"],
  "seznamRegistraci": {
    "stavZdrojeVr": "AKTIVNI",
    "stavZdrojeRes": "AKTIVNI",
    "stavZdrojeRzp": "AKTIVNI",
    "stavZdrojeDph": "AKTIVNI",
    "stavZdrojeIr": "NEEXISTUJICI",
    "…": "…"
  },
  "primarniZdroj": "ros",
  "dalsiUdaje": ["…"]
}

Kódy (právní forma, finanční úřad, CZ-NACE) převedete na názvy endpointem číselníků POST /ciselniky-nazevniky/vyhledat. Číselníky se mění zřídka — stáhněte je jednou a uložte, ať se na ně neptáte u každé firmy:

curl -s -X POST "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ciselniky-nazevniky/vyhledat" \
  -H "Content-Type: application/json" \
  -d '{"kodCiselniku": "PravniForma", "zdrojCiselniku": "res"}'

Kontrola IČO před dotazem

IČO má kontrolní číslici počítanou modulo 11. ARES ji neověřuje: osmimístné číslo s chybným součtem nevrátí chybu vstupu, ale 404 „subjekt nenalezen". Kontrolou před dotazem odfiltrujete překlepy a neposíláte do ARES dotazy, které nemohou uspět — podmínky provozu opakované chybné dotazy uvádějí jako důvod k omezení přístupu.

<?php
// Kontrola IČO (modulo 11) – ARES ji nedělá, neplatné číslo vrátí jako 404.
function icoPlatne(string $ico): bool
{
    $ico = str_pad(preg_replace('/\D/', '', $ico), 8, '0', STR_PAD_LEFT);
    if (strlen($ico) !== 8) {
        return false;
    }
    $soucet = 0;
    for ($i = 0; $i < 7; $i++) {
        $soucet += (int) $ico[$i] * (8 - $i);
    }
    return (11 - $soucet % 11) % 10 === (int) $ico[7];
}

var_dump(icoPlatne('00177041')); // bool(true)
var_dump(icoPlatne('12345678')); // bool(false)

def ico_platne(ico: str) -> bool:
    """Kontrola IČO (modulo 11) – ARES ji nedělá, neplatné číslo vrátí jako 404."""
    ico = "".join(c for c in ico if c.isdigit()).zfill(8)
    if len(ico) != 8:
        return False
    soucet = sum(int(ico[i]) * (8 - i) for i in range(7))
    return (11 - soucet % 11) % 10 == int(ico[7])

print(ico_platne("00177041"))  # True
print(ico_platne("12345678"))  # False

// Kontrola IČO (modulo 11) – ARES ji nedělá, neplatné číslo vrátí jako 404.
function icoPlatne(ico) {
  ico = String(ico).replace(/\D/g, '').padStart(8, '0');
  if (ico.length !== 8) return false;
  let soucet = 0;
  for (let i = 0; i < 7; i++) soucet += Number(ico[i]) * (8 - i);
  return (11 - (soucet % 11)) % 10 === Number(ico[7]);
}

console.log(icoPlatne('00177041')); // true
console.log(icoPlatne('12345678')); // false

Chyby a jak na ně reagovat

Chyby vrací ARES u všech endpointů stejně: JSON se třemi poli kod (skupina), popis (lidsky čitelný text, části oddělené svislítkem) a subKod (konkrétní důvod). Programově se rozhodujte podle subKod, ne podle textu:

{
  "kod": "NENALEZENO",
  "popis": "Nebyl nalezen žádný subjekt, který by odpovídal zadaným hodnotám. Upravte parametry vyhledávání.|Záznam nenalezen",
  "subKod": "VYSTUP_SUBJEKT_NENALEZEN"
}

Na chyby 5xx a vypršení času reagujte opakováním s prodlužující se prodlevou (1 s, 2 s, 4 s) a po několika neúspěších dotaz vzdejte. Výsledek 404 je platná odpověď — uložte ho do cache stejně jako nalezený subjekt, ať se na neexistující IČO neptáte znovu. Chyby hledání a dávek jsou u hledání.

Další endpointy

Tři situace, na které základní endpoint nestačí: hledání bez IČO nebo hromadné načtení, hlídání změn a podrobné údaje z jednoho registru. U každé shrnujeme, co endpoint dělá a na co si dát pozor; parametry a schéma odpovědí najdete ve Swagger UI.

Hledání a dávka až 100 IČO: POST /ekonomicke-subjekty/vyhledat

Pro hledání podle názvu, sídla nebo dalších kritérií pošlete JSON tělo. Výsledky se stránkují parametry start (posun) a pocet (velikost stránky, výchozí je 20); odpověď obsahuje pocetCelkem a pole ekonomickeSubjekty se stejnými objekty, jaké vrací základní endpoint. Kódy obcí a ulic jsou kódy RÚIAN — obec sídla zjistíte třeba ze sidlo.kodObce libovolné firmy v dané obci. Všechna kritéria: Swagger UI.

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

<?php
$dotaz = [
    'obchodniJmeno' => 'Škoda Auto',
    'sidlo'         => ['kodObce' => 535419], // Mladá Boleslav (kód obce z RÚIAN)
    'start'         => 0,
    'pocet'         => 10,
];
$ch = curl_init('https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/vyhledat');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($dotaz, JSON_UNESCAPED_UNICODE),
]);
$data = json_decode(curl_exec($ch), true);

if (($data['subKod'] ?? '') === 'VYSTUP_PRILIS_MNOHO_VYSLEDKU') {
    exit("Víc než 1000 výsledků – zužte dotaz\n");
}
echo "Nalezeno: {$data['pocetCelkem']}\n";
foreach ($data['ekonomickeSubjekty'] as $s) {
    echo $s['ico'], '  ', $s['obchodniJmeno'], PHP_EOL;
}

import requests

dotaz = {
    "obchodniJmeno": "Škoda Auto",
    "sidlo": {"kodObce": 535419},  # Mladá Boleslav (kód obce z RÚIAN)
    "start": 0,
    "pocet": 10,
}
r = requests.post(
    "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/vyhledat",
    json=dotaz, timeout=10,
)
data = r.json()
if data.get("subKod") == "VYSTUP_PRILIS_MNOHO_VYSLEDKU":
    raise SystemExit("Víc než 1000 výsledků – zužte dotaz")
r.raise_for_status()

print("Nalezeno:", data["pocetCelkem"])
for s in data["ekonomickeSubjekty"]:
    print(s["ico"], s["obchodniJmeno"])

const res = await fetch(
  'https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/vyhledat',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      obchodniJmeno: 'Škoda Auto',
      sidlo: { kodObce: 535419 }, // Mladá Boleslav (kód obce z RÚIAN)
      start: 0,
      pocet: 10,
    }),
  }
);
const data = await res.json();
if (data.subKod === 'VYSTUP_PRILIS_MNOHO_VYSLEDKU') {
  throw new Error('Víc než 1000 výsledků – zužte dotaz');
}
console.log('Nalezeno:', data.pocetCelkem);
for (const s of data.ekonomickeSubjekty) console.log(s.ico, s.obchodniJmeno);

Dávka až 100 IČO: když potřebujete údaje o známém seznamu firem, nepošlete sto dotazů na /ekonomicke-subjekty/{ico}, ale jeden dotaz s polem ico. Nezapomeňte nastavit pocet, jinak dostanete jen prvních 20; IČO, která ARES nezná, v odpovědi prostě chybí.

import requests

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

def ares_davka(ica: list[str]) -> dict[str, dict]:
    """Až 100 IČO jedním dotazem (víc ARES odmítne s VSTUP_PRILIS_MNOHO_HODNOT)."""
    vysledek = {}
    for i in range(0, len(ica), 100):
        kus = [ico.zfill(8) for ico in ica[i:i + 100]]
        r = requests.post(URL, json={"ico": kus, "pocet": 100}, timeout=20)
        r.raise_for_status()
        for s in r.json().get("ekonomickeSubjekty", []):
            vysledek[s["ico"]] = s
    return vysledek  # IČO, která chybí, ARES nezná

firmy = ares_davka(["00177041", "00006947"])
for ico, s in firmy.items():
    print(ico, s["obchodniJmeno"])

curl -s -X POST "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/vyhledat" \
  -H "Content-Type: application/json" \
  -d '{"ico": ["00177041", "00006947"], "pocet": 100}'

• Strop 1 000 výsledků: pokud dotazu odpovídá víc subjektů, ARES nevrátí ani první stránku, ale chybu 400 VYSTUP_PRILIS_MNOHO_VYSLEDKU s celkovým počtem v textu (například „2 866"). Dotaz je potřeba zúžit obcí, právní formou nebo CZ-NACE; pro práci s celým registrem použijte otevřená data.
• Víc než 100 IČO v jednom dotazu ARES odmítne s chybou 400 VSTUP_PRILIS_MNOHO_HODNOT — rozdělte je do dávek po 100.
• Hledání podle adresy. Filtr sidlo.kodAdresnihoMista ARES ignoruje a dotaz bez jiného kritéria skončí chybou 400 VSTUP_PRAZDNY. Firmy na stejné adrese najdete přes obec a ulici, nebo podle sidlo.textovaAdresa, a výsledky pak dofiltrujte podle kódu adresního místa.
• Kódování těla. Tělo musí být v UTF-8 (platí pro všechny POST endpointy). Na Windows (Git Bash, starší PowerShell) se diakritika z příkazové řádky snadno odešle v jiném kódování a ARES odpoví 500 JSON parse error: Invalid UTF-8. Pošlete tělo ze souboru uloženého v UTF-8 (curl --data-binary @dotaz.json) nebo použijte knihovnu, která JSON kóduje sama.

Hlídání změn: notifikační dávky

Pokud potřebujete vědět, že se u sledovaných firem něco změnilo, neptejte se ARES na každou z nich každý den. ARES průběžně vydává notifikační dávky — seznamy IČO, u kterých se v daném registru změnil záznam, s typem změny INS (nový), UPD (změna) nebo DEL (výmaz). Seznam dávek vrátí POST /ekonomicke-subjekty-notifikace/vyhledat (Swagger), obsah jedné dávky GET …/datovy-zdroj/{zdroj}/cislo-davky/{cislo} (Swagger). Dávky existují pro veřejný rejstřík (vr), RES, registr osob, živnostenský rejstřík a další zdroje; za září 2026 jich ARES pro veřejný rejstřík vydal 26, každá se stovkami až tisíci změn.

# 1) Seznam dávek změn ve veřejném rejstříku (zhruba za poslední měsíc)
curl -s -X POST "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty-notifikace/vyhledat" \
  -H "Content-Type: application/json" \
  -d '{"datovyZdroj": "vr"}'

# 2) Obsah jedné dávky: seznam IČO a typ změny (INS / UPD / DEL)
curl -s "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty-notifikace/datovy-zdroj/vr/cislo-davky/738"

import requests

B = "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty-notifikace"
SLEDUJI = {"00177041", "00006947"}  # IČO, která vás zajímají
posledni_zpracovana = 737          # číslo dávky si ukládejte mezi běhy

davky = requests.post(f"{B}/vyhledat", json={"datovyZdroj": "vr"}, timeout=10).json()
for d in davky["notifikacniDavky"]:
    if d["cisloDavky"] <= posledni_zpracovana:
        continue
    obsah = requests.get(f"{B}/datovy-zdroj/vr/cislo-davky/{d['cisloDavky']}", timeout=20).json()
    for zmena in obsah["seznamNotifikaci"]:
        if zmena["icoId"] in SLEDUJI:
            print(d["datumUvolneniDavky"], zmena["typZmeny"], zmena["icoId"])
    posledni_zpracovana = d["cisloDavky"]

Seznam dávek sahá zhruba měsíc zpět, takže je potřeba je stahovat pravidelně a pamatovat si číslo poslední zpracované dávky. U IČO, která se objeví v dávce a sledujete je, pak načtete čerstvá data základním endpointem.

Pohledy registrů: VR, RŽP, RES a další

Pohled vrací údaje z jednoho registru v jeho vlastní, podrobnější struktuře — ne v té, kterou popisujeme u základního endpointu. Volá se stejně, GET /ekonomicke-subjekty-{registr}/{ico}. Který má smysl volat, poznáte podle seznamRegistraci v odpovědi základního endpointu: pro registr, ve kterém subjekt není, vrátí pohled 404 VYSTUP_SUBJEKT_NENALEZEN. Pohledy VR, RŽP a RES si můžete vyzkoušet ve formuláři nahoře; schéma odpovědí je ve Swagger UI (VR, RŽP, RES). Nejčastěji se používá veřejný rejstřík, který má pár nástrah:

• Historie místo aktuálního stavu. Pohled VR vrací většinu údajů jako pole verzí [{"datumZapisu", "datumVymazu", "hodnota"}]. Aktuální je záznam bez datumVymazu — nebrat automaticky první prvek pole.
• Čísla jako text se středníkem. Částky (například základní kapitál) přicházejí jako řetězec "13129700000;00", kde středník je desetinná čárka. U podílů typu ZLOMEK ale "51;100" znamená zlomek 51/100. Parsujte podle typu, ne jedním pravidlem.
• Osobní údaje. U fyzických osob ve statutárních orgánech a mezi společníky vrací pohled VR jméno, datum narození a adresu. Pokud je ukládáte nebo zobrazujete, řiďte se GDPR — ARES.CZ z nich například ukazuje jen jméno a obec.
• Zahraniční osoby bez IČO. Zahraniční právnické osoby mezi společníky nebo akcionáři IČO nemají — počítejte s chybějícím polem ico.

Limity a podmínky provozu

Platí pro všechny endpointy dohromady. Podmínky provozu ARES dovolují Ministerstvu financí omezit nebo zablokovat přístup uživateli, který pošle víc než 500 dotazů za minutu. Denní strop REST API nemá. Stejně tak může přístup omezit při:

• opakovaném posílání stejných dotazů nebo dotazů s chybně vyplněnými údaji,
• velkém počtu souběžných automatizovaných dotazů,
• obcházení limitu dotazy z více IP adres,
• automatickém prohledávání databáze náhodnými údaji,
• pokusech o narušení bezpečnosti serveru.

ARES neposílá hlavičky se zbývajícím limitem (X-RateLimit-*) ani Retry-After, hlídat se musíte sami. Odpověď na jednoduchý dotaz trvá obvykle 0,15–0,35 s. Doporučujeme držet se zhruba poloviny limitu a výsledky ukládat do cache — identifikační údaje firem se mění zřídka a na změny upozorní notifikační dávky.

„60 000 dotazů denně" už neplatí. Tento často citovaný limit patřil starému XML rozhraní (10 000 dotazů ve dne a 50 000 v noci). Pro REST API rozhoduje jen minutový práh a chování popsané výše.

Změny verzí API. Ministerstvo financí ohlašuje změny v changelogu a RSS. Verze 1.4.0 (30. 9. 2026) například zrušila pole statniObcanstvi u fyzických osob ve VR a přidala clenstvi u společného podílu. Čtěte pole defenzivně a neznámá ignorujte.

Migrace ze starého XML ARES (wwwinfo.mfcr.cz)

Původní XML služby ARES na adrese wwwinfo.mfcr.cz/cgi-bin/ares/… skončily a doména dnes vůbec neodpovídá. Pokud účetní program, e-shop nebo skript přestal načítat údaje o firmách, nejspíš volá právě je. Převodní tabulka podle archivní dokumentace XML služeb:

Hlavní rozdíly: místo XML se jmennými prostory dostanete JSON, IČO musí mít vždy 8 číslic, adresa je ve strukturovaném objektu sidlo s kódy RÚIAN a místo denního limitu platí minutový práh. Starou adresu typu wwwinfo.mfcr.cz/cgi-bin/ares/darv_bas.cgi?ico=27074358 tedy nahradí ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/27074358.

Co ARES API neobsahuje

Dnešní REST API odpovídá v JSON a obor činnosti vrací jako kódy CZ-NACE (pohled RES i převažující činnost) i s kategorií počtu zaměstnanců. Některé údaje ale ve veřejných registrech nejsou, a proto je nenajdete ani v ARES:

• Finanční údaje (obrat, zisk) — české firmy je zakládají do sbírky listin jako PDF, strojově čitelné API pro ně neexistuje. Slovenské účtovné závierky nabízí RegisterUZ.
• Kontakty (telefon, e-mail, web) ani datovou schránku — ARES je nevrací.
• Spolehlivost plátce DPH a bankovní účty — jsou v registru plátců DPH (ADISREG), ne v ARES.
• Insolvence a exekuce v detailu — insolvenční řízení najdete v ISIR, exekuce v placené Centrální evidenci exekucí.
• Garance dostupnosti — ARES je státní služba bez smlouvy o úrovni služeb (SLA). Kdo potřebuje garantovanou dostupnost, kontakty nebo finance v jednom rozhraní, sáhne po komerčních poskytovatelích, kteří data z registrů agregují.

Časté otázky k ARES API