REST API · JSON přes HTTPS

Načítání ekonomických subjektů z registru ARES

Jednoduché REST API pro vyhledávání firem podle názvu a načítání detailu firmy podle IČO. Komunikace probíhá výhradně přes HTTPS, odpovědi jsou ve formátu JSON.

Autentizace Endpointy Limity požadavků Chybové stavy Vyzkoušet v prohlížeči

Vyzkoušet živé demo Mám zájem o přístup

01 Autentizace

Přístup přes Bearer token

Všechny endpointy vyžadují platný přístupový token, který se předává v hlavičce Authorization schématem Bearer. Token vám vystavíme po dohodě.

Authorization: Bearer <váš-access-token>

Strojově čitelný popis všech endpointů ve formátu OpenAPI 3.1 - pro generování klientů nebo import do Postmanu, Insomnie či Swagger UI.

Vyzkoušet v prohlížeči Stáhnout openapi.yaml

Base URL https://companies.pits.cz

GET /api/ping

Ověření dostupnosti API a platnosti přístupového tokenu.

Odpověď

{"message": "pong"}

GET /api/ares/companies

Našeptávač firem podle názvu - vrátí seznam subjektů odpovídajících dotazu.

Query parametry

querypovinné, min. 3 znaky
limitvolitelné, výchozí 10, max. 25
startvolitelné, výchozí 0; offset pro stránkování dalších výsledků

Příklad

GET /api/ares/companies?query=pits&limit=5
Authorization: Bearer <váš-access-token>

Odpověď

{
  "results": [
    {
      "companyId": "12345678",
      "companyName": "PiTS s.r.o.",
      "address": "Praha 1, 110 00"
    }
  ],
  "count": 1,
  "total": 23,
  "start": 0,
  "limit": 5,
  "hasMore": true
}

total udává celkový počet dostupných záznamů pro daný dotaz, hasMore je true, pokud lze další stránku získat opětovným voláním s vyšším start (typicky start = předchozí start + limit).

GET /api/ares/lookup název i IČO

Sjednocený lookup - pokud je dotaz čistě číselný (1-8 číslic), server jej interpretuje jako IČO a vrátí detail v autocomplete-tvaru; jinak provede našeptávač podle názvu. Výsledek je vždy stejný JSON, klient nemusí nic detekovat.

Query parametry

querypovinné; číslo (1-8 číslic) = IČO, jinak název o min. 3 znacích
limitvolitelné, výchozí 10, max. 25 (ignorováno při IČO)
startvolitelné, výchozí 0; offset pro stránkování (ignorováno při IČO)

Příklad - název

GET /api/ares/lookup?query=pits
Authorization: Bearer <váš-access-token>

Příklad - další stránka

GET /api/ares/lookup?query=pits&limit=5&start=5
Authorization: Bearer <váš-access-token>

Příklad - IČO

GET /api/ares/lookup?query=12345678
Authorization: Bearer <váš-access-token>

Odpověď

{
  "results": [
    {
      "companyId": "12345678",
      "companyName": "PiTS s.r.o.",
      "address": "Praha 1, 110 00"
    }
  ],
  "count": 1,
  "total": 23,
  "start": 0,
  "limit": 5,
  "hasMore": true
}

total je celkový počet dostupných záznamů pro dotaz, hasMore indikuje existenci další stránky. Pro IČO se vrací jeden záznam s total = 1; když IČO neexistuje, vrátí se prázdný výsledek s total = 0 - žádné 404 v happy path.

GET /api/ares/companies/{companyId}

Detail firmy podle IČO. Hodnota companyId je IČO o délce 1-8 číslic (kratší hodnoty se automaticky doplní nulami zleva).

Příklad

GET /api/ares/companies/12345678
Authorization: Bearer <váš-access-token>

Odpověď

{
  "companyId": "12345678",
  "taxId": "CZ12345678",
  "companyName": "PiTS s.r.o.",
  "legalForm": "Společnost s ručením omezeným",
  "address": {
    "full": "Ulice 123/4, 110 00 Praha 1",
    "street": "Ulice",
    "houseNumber": "123/4",
    "city": "Praha 1",
    "postalCode": "110 00",
    "countryCode": "CZ"
  },
  "registeredAt": "2010-01-01",
  "dissolvedAt": null,
  "primaryNaceCode": "62010",
  "syncedAt": "2026-05-20T08:00:00+00:00"
}

GET /api/usage statistiky

Přehled využití API pro váš přístupový token - počet požadavků po dnech a endpointech včetně počtu odpovědí obsloužených z cache. Bez parametrů vrací posledních 30 dní.

Query parametry

fromvolitelné, první den ve formátu YYYY-MM-DD
tovolitelné, poslední den ve formátu YYYY-MM-DD, výchozí dnešek; období max. 366 dní

Příklad

GET /api/usage?from=2026-10-01&to=2026-10-31
Authorization: Bearer <váš-access-token>

Odpověď

{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "totalRequests": 128,
  "totalCacheHits": 41,
  "items": [
    {
      "day": "2026-10-01",
      "endpoint": "api.ares.lookup",
      "requests": 120,
      "cacheHits": 40
    },
    {
      "day": "2026-10-01",
      "endpoint": "api.ares.company_detail",
      "requests": 8,
      "cacheHits": 1
    }
  ]
}

Cache odpovědí

Úspěšné odpovědi endpointů /api/ares/* se ukládají do cache zvlášť pro každý přístupový token na 15 minut. Hlavička X-Cache udává, zda odpověď pochází z cache (HIT), nebo byla právě spočítána (MISS). Chybové odpovědi se do cache neukládají a i odpověď z cache se započítává do rate limitu.

Odpovědi navíc nesou hlavičku ETag. Pošlete ji zpět v hlavičce If-None-Match a pokud se data nezměnila, API vrátí 304 Not Modified bez těla - ušetříte přenos dat.

X-RateLimit-Limit: celkový limit
X-RateLimit-Remaining: zbývající počet požadavků
X-RateLimit-Reset: unix timestamp obnovení limitu

Při překročení limitu API vrací stav 429 Too Many Requests.

400neplatný vstup (např. krátký dotaz pro vyhledávání)
401chybějící nebo neplatný přístupový token
404firma nebyla v registru ARES nalezena
429překročen rate limit
503registr ARES je dočasně nedostupný

Příklad chybové odpovědi

HTTP/2 400
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Parameter \"query\" must be at least 3 characters long.",
  "message": "Parameter \"query\" must be at least 3 characters long."
}

Pole message obsahuje totéž co detail a zůstává jen kvůli zpětné kompatibilitě.

Zájem o využití služby

Pokud má vaše firma zájem tuto službu používat, kontaktujte nás na pits.cz.

Informace o zpracování osobních údajů najdete na pits.cz/ochrana-osobnich-udaju.

Kontaktujte nás