ares-business-registry_skill

Overview

This skill queries the Czech ARES business registry by ICO (company ID) or by name and returns results in human-readable, JSON, or raw ARES payload formats. It includes validation, retries for transient network errors, a legal-form decoder with caching and curated overrides, and search filters like city, limit, offset, and pick.

How this skill works

Call the CLI wrapper or the Python script to lookup an ICO or perform a name search. The tool validates inputs (ICO checksum, minimum name length), calls ARES with a short timeout and retry/backoff policy, decodes legal-form codes using a cached registry, and emits either a readable summary, a normalized JSON structure, or the raw ARES response. Error outputs follow a stable JSON contract when --json is used.

When to use it

• Lookup full company details by ICO for bookkeeping, compliance, or data enrichment.
• Search for companies by name with optional city filtering and paging.
• Integrate ARES lookups into scripts or pipelines that require deterministic JSON output.
• Troubleshoot ARES responses by inspecting raw payloads.
• Automate repeated queries while relying on retry/backoff behavior for transient failures.

Best practices

• Use the CLI wrapper for consistent behavior and the recommended defaults.
• Request --json for stable keys suitable for downstream parsing and automation.
• Respect validation rules: provide an 8-digit ICO with proper checksum or name >= 3 characters.
• Limit results and use --offset to page; set --city when you need municipality-focused results but expect best-effort matching.
• Cache or persist results from repeated queries to avoid rate limits; the tool already honors Retry-After headers and retries transient errors.

Example use cases

• Validate a supplier by running: ./ares ico 27604977 --json to ingest into a vendor database.
• Find local competitors by name and city: ./ares name "Company" --city Praha --limit 10.
• Extract raw ARES payloads for debugging problematic responses with --raw.
• Perform bulk checks in a script using search with --limit and --offset and parse the normalized JSON items.
• Decode legal form codes to readable abbreviations when generating reports or invoices.