Skill: pghostek/ares-business-registry (version 0.2.0)

--- name: ares-business-registry description: Query Czech ARES business registry by ICO or name with human/JSON/raw outputs, retries, and legal-form decoding. --- # ARES Business Registry (CZ) Use `scripts/ares_client.py` for ICO lookup and business search. ## Working directory - From workspace root: - `python3 skills/ares-business-registry/scripts/ares_client.py ...` - From `skills/ares-business-registry`: - `python3 scripts/ares_client.py ...` ## Commands You can run via the wrapper (recommended): - `./ares ico <ico>` - `./ares name "NAME" [--nace CODE ...] [--city CITY] [--limit N] [--offset N] [--pick INDEX]` The underlying script also supports: - `python3 scripts/ares_client.py search --name "NAME" ...` - `python3 scripts/ares_client.py search --nace CODE [CODE ...] ...` - `python3 scripts/ares_client.py search --name "NAME" --nace CODE ...` (combined) ## Output modes - default: human-readable summary - `--json`: normalized JSON output (stable keys) - `--raw`: full raw ARES payload ## Examples ```bash # ICO lookup python3 scripts/ares_client.py ico 27604977 python3 scripts/ares_client.py ico 27604977 --json python3 scripts/ares_client.py ico 27604977 --raw # Search by name python3 scripts/ares_client.py search --name Google python3 scripts/ares_client.py search --name Google --limit 3 --json python3 scripts/ares_client.py search --name Google --city Praha --limit 10 --offset 0 python3 scripts/ares_client.py search --name Google --limit 3 --pick 1 # Search by NACE code (CZ-NACE, exactly 5 digits) python3 scripts/ares_client.py search --nace 47710 --limit 10 # all clothing retailers python3 scripts/ares_client.py search --nace 47710 --city Praha --json # clothing retailers in Praha python3 scripts/ares_client.py search --nace 47710 47910 --limit 5 # clothing retail + mail order # Combined: name + NACE (AND filter) python3 scripts/ares_client.py search --name sport --nace 47710 --json # "sport" in clothing retail ``` ## Normalized JSON - `ico` output: - `{ "subject": { "name", "ico", "dic", "datumVzniku", "address", "codes", "decoded" } }` - `search` output: - `{ "query", "total", "items", "picked?" }` - `query` includes: `name` (nullable), `city` (nullable), `nace` (nullable array), `limit`, `offset` - `dic` can be `null`. - `datumVzniku` can be `null`. ## Error JSON contract (`--json` only) ```json { "error": { "code": "validation_error | ares_error | network_error", "message": "Human readable message", "status": 429, "details": {} } } ``` ## Validation and exits - ICO: exactly 8 digits + mod11 checksum - Search: at least `--name` (length >= 3) or `--nace` required; both can be combined - `--nace`: exactly 5 digits per code (CZ-NACE format, e.g. `47710`); multiple codes accepted (space-separated) - `--limit`: default 10, capped to 100 - `--offset`: must be >= 0 - Exit codes: - `0` success - `1` validation error - `2` ARES non-OK response - `3` network/timeout ## Caching and decoding - Legal form decoding (`PravniForma`) is loaded via POST `/ciselniky-nazevniky/vyhledat` - Cache path: `skills/ares-business-registry/.cache/pravni_forma.json` - Cache TTL: 24h - In-memory fallback is used if cache file is stale/unavailable - Curated overrides: - `112 -> s.r.o.` - `121 -> a.s.` - `141 -> z.s.` - `701 -> OSVČ` - `301 -> s.p.` - `331 -> p.o.` ## NACE code search - `--nace` sends the `czNace` field to the ARES complex filter endpoint - Codes must be exactly 5 digits (CZ-NACE_2025 format) - Multiple codes can be passed (space-separated) — ARES returns entities matching **any** of them - When combined with `--name`, both filters apply as AND (entities must match name AND have the NACE code) - NACE-only search (without `--name`) is supported — useful for browsing all entities in a sector - Common e-commerce NACE codes: - `47710` — Retail sale of clothing - `47910` — Retail sale via mail order or internet - `47410` — Retail sale of computers and software - `47750` — Retail sale of cosmetic and toilet articles - `46420` — Wholesale of clothing and footwear - Full CZ-NACE list: https://www.czso.cz/csu/czso/klasifikace_ekonomickych_cinnosti_cz_nace ## City filter limitation - `--city` maps to `sidlo.nazevObce` (structured filter). - Matching remains best-effort only; ARES server-side matching/ranking can still return records outside the expected municipality. ## Retries and rate limits - HTTP timeout: connect 5s, read 20s - Retries for transient failures: `429/502/503/504` + network timeout/connection issues - Backoff: `1s`, `2s`, `4s` - Honors `Retry-After` for 429 where provided


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)