nette-ares

nette-ares is a Nette extension that loads a company from the Czech ARES register by company ID or name: business name, address, VAT ID and legal form. It can verify the ID checksum and caches results.

nette-ares: looking up the Ministry of Finance by company ID 6947 in ARES, a cached answer and a search by name

nette-ares is a Nette extension that fetches company details from ARES, the Czech state register of economic entities, by company ID (IČO) or by name. A typical case: a customer registers with a wholesaler and the order form asks for the company name, registered address, postcode and VAT number. They copy it from an invoice or from memory, swap the building number with the street number, leave out "s.r.o." and the mistake then travels onto every later document. When the form takes only the company ID and fills in the rest from ARES, the user types eight digits instead of six fields, and the details match what the state holds about the company.

What ARES puts into the form

The findByIco() method returns an AresResult object with the business name, VAT ID (DIČ), legal form code, street, building and orientation number including its letter, municipality, municipality part, postcode, country code, the full address as text, and the dates of establishment and dissolution. Helper methods are ready for forms: getStreet() builds "Letenská 525/15", getFormattedPsc() returns "118 00" and getCity() adds the municipality part when it differs. toArray() returns the same data as an array with English keys (company, street, city, zip) and an isPhysicalPerson flag, which recognises a sole trader from legal form codes 100 to 109. That is useful when a form asks a sole trader different questions from a joint-stock company.

Search by name (searchByName()) needs at least three characters and returns at most as many companies as the limit allows; the default is ten and the ceiling is one hundred. In the screenshot above, the query "Ministerstvo" with a limit of five returned five ministries with their company IDs.

The user types 6947, the library asks for 00006947

Company IDs of state institutions and older firms start with zeros, and people leave them out. Before the request, the library strips spaces and pads the number with zeros on the left to eight digits, so "6947" and "00 006 947" both find the Ministry of Finance. Anything that still is not eight digits ends in an AresException before a request is sent. findByIco() does not validate the checksum; the separate static method AresClient::isValidIco() does (modulo 11, no network call), so a typo can be rejected before ARES is asked. A non-existent number with a correct checksum is recognised only by ARES, which returns 404, and the library turns that into the same exception with code 404.

The second query does not touch the network

Results are stored in Nette Caching for the period set in cacheTtl, one month by default. In a test on PHP 8.4, the first ARES query took 213 to 430 ms and a repeated query for the same company ID took about 5 ms from the file cache. The cache can be cleared for a single company ID (clearCacheByIco()) or entirely (clearCache()), which helps after a company moves. Failed lookups are not stored, so a mistyped company ID does not stay in the cache as "not found".

Connecting it to a form

The extension registers itself through extra.nette.extensions in composer.json and adds the AresClient service to the container. The most common use is an AJAX handler that the form's script calls once the company ID is filled in:

public function handleAresLookup(string $ico): void
{
    try {
        $this->sendJson($this->ares->findByIco($ico)->toArray());
    } catch (AresException $e) {
        $this->sendJson(['error' => $e->getMessage()]);
    }
}

Error messages are in Czech ("Neplatné IČO", "Subjekt s IČO '12345678' nebyl nalezen v ARES"), so a Czech site can show them to the user as they are. To check VAT registration, getDic() is enough.

A dissolved company versus an ARES outage

isActive() returns false for a company with a dissolution date, for an ID that ARES does not know (HTTP 404) and for a malformed ID. When ARES is unreachable, times out or answers with a server error, the method throws AresException, so an outage is never mistaken for a dissolved company. The "not found" exception has code 404, other API errors carry the HTTP status and a connection failure has code 0.

No extra dependency

The library calls version 3 of the ARES REST API (GET /ekonomicke-subjekty/{ico} and POST /ekonomicke-subjekty/vyhledat) with PHP's built-in functions. It needs neither Guzzle nor any other HTTP client, only the Nette packages for DI, caching, the configuration schema and JSON. The connection verifies the server certificate and waits at most 10 seconds for a response. ARES requires no sign-in and no API key.

Things to watch for

  • The result of findByIco() stays in the cache for cacheTtl (one month by default), so isActive() also sees a dissolution only after the cache expires or after clearCacheByIco().
  • searchByName() searches by business name only; searching by address or VAT ID is not possible.

Tests

Since version 1.1.0 the repository has tests in Nette Tester. They replace the HTTP layer with a canned response, so they run without a network and cover isActive() (active, dissolved, unknown and malformed company, outage, server error), the text of the "not found" exception and the checksum. They passed on PHP 8.1 and 8.4. The screenshot comes from a manual run against live ARES on 6 November 2026.

Getting started

composer require nks-hub/nette-ares

It needs PHP 8.1 or newer and Nette 3.1 or 4. Configuration is optional; the only parameter is the cache lifetime (ares: cacheTtl: '1 week'). The latest version is 1.1.0 from 6 November 2026.

Source code

The code is on GitHub in the nks-hub/nette-ares repository under the MIT licence. The package is on Packagist as nks-hub/nette-ares. For personal and delivery addresses, which ARES does not hold, there is the companion library nette-ruian.

← Back to overview