A few months ago I was asked to implement several open-source libraries in PHP for one czech company called Asisteam. One of them was a simple connector to ARES API (Czech economic subjects registry).

By calling this API endpoints you can get company details and/or validate whether some given company ID (IČO) really exists and correspond to some existing company known by Czech government and law.

You can find the library on github and you’re very welcome to use it and make pull requests if you know of any enhancement or bug fix.

The API itself is very easy and it’s usage is even easier. If you’re using composer you can just run the command composer require asisteam/ares.

In order to call the api you must instantiate a ares finder client at first.

$finder = new AsisTeam\ARES\Client\Finder();

Now you are ready to go. Finder has two public methods you may call:

  • findById(string $companyId): ?Subject
  • findByName(string $name): Subject[]

Use the first method findById if you have companyId (IČO) and you want to validate that it belongs to real company or to retrieve company basic details. The second method findByName may be used when searching a company by part of it’s name.

The Subject object being returned by both methods has following getters:

  • getCompanyID (returns ico [string])
  • getCompanyName (returns name [string])
  • getAddress (returns address [string])
  • getVatId (returns vat ID [string])
  • getLegalFormName (returns name of the legal form [string])
  • isPhysicalPerson (returns whether subject is physical person/individual [bool])
  • isLegalPerson (returns whether subject is legal person/company etc. [bool])

In real life scenarios the code may look like the one below:

$finder = new Finder();
$subject = $finder->findById('28319061');

if ($subject === null) {
    echo 'Company not found.';
} else {
    echo sprintf('ID %s belongs to %s', $subject->getCompanyID(), $subject->getCompanyName());
}

or

$finder = new Finder();
$subjects = $finder->findByName('kedlas');

echo sprintf('%d companies match given name', count($subject));

If you are using Nette framework you may find useful the existing Nette extension class that is already a part of the library.

The goal of this library was to implement an easy and intuitive interface for searching in Ares registry. The main program logic is covered by unit and integration tests that are implemented using Nette Tester. Because the library itself is very small and has basically just few dependencies I did not want to use Guzzle library. Instead I use php native curl_xxx commands. As I only need to send simple GET requests i think not using guzzle or another similar library is perfectly OK. What do you think?

Feel free to use this library and contribute to it’s repo.