nette-ruian
nette-ruian is a Nette extension that validates Czech addresses against RÚIAN, suggests the nearest real address for a typo, and offers step-by-step selection and municipality autocomplete.
nette-ruian is a Nette extension that validates and completes Czech addresses against RÚIAN, the state register of territorial identification, addresses and real estate. A courier returns a parcel because the order said "Kaprvoa 14, Praha" with no postcode and no orientation number. The form accepted the address because the "street" field takes any text. With nette-ruian, the address is compared with the register before it is saved: the library says whether such an address exists and, if not, offers the nearest real one together with a match score. In the screenshot above it turned the typo "Kaprvoa 14" into "Kaprova 14/13, Praha, 11000" with a score of 0.94.
Where the data comes from
RÚIAN is run by the Czech Office for Surveying, Mapping and Cadastre, and its official interface is SOAP with extensive documentation. The library therefore calls the RUIAN API by fnx.io, which offers a plain REST interface with JSON on top of the freely downloadable RÚIAN data. The key is free, arrives by email and is limited to 1,000 requests per hour; the operator explicitly promises neither availability nor data accuracy. For an ordinary form with caching that is enough.
An address can be typed or picked
Validating a typed address
validate() takes whatever the user filled in: municipality, municipality part, street, postcode, building, orientation or registration number, or the RÚIAN address ID directly. It returns a ValidateResult with the status MATCH (exact match), POSSIBLE (match with a deviation), NOT_FOUND or ERROR, and with the place found, which carries the region, municipality and municipality part IDs, the street, the numbers, the postcode and the address point ID. getFormattedAddress() builds a line for a shipping label from it. The value most worth storing in the database is the address ID: it is stable, and the address can be looked up again from it at any time through validateByRuianId().
A POSSIBLE result without any typo is normal: the query "Kaprova 14, Praha" without an orientation number returned the address 14/13 as a possible match, not an exact one. The application can then ask the user whether this is the address they meant.
Step-by-step selection
For forms where the user should pick an address instead of typing it, there are four steps: getRegions() returns the regions, getMunicipalities() the municipalities in a region, getStreets() the streets in a municipality (or municipality parts where there are no streets) and getPlaces() the address points in a street with numbers and postcodes. Each step takes an ID from the previous one. In Frýdlant (municipality ID 564028) the third step returned 118 streets and the fourth 34 address points in Zámecká street.
When only the municipality ID is known, getAddressHierarchy() returns the region, the municipality and the streets at once. It finds the region by going through the municipality lists of each region, so the first call is up to 14 requests and later ones come from the cache. For Frýdlant the screenshot shows Liberecký kraj (CZ051) and 118 streets. For an ID that no region contains, the region and municipality are null.
Municipality autocomplete without a database of your own
getAllMunicipalities() goes through all regions and builds a list of every municipality. In a test on 6 November 2026 that was 6,256 municipalities from 14 regions in under a second, and the list is cached for seven times the configured period, a week by default. searchMunicipalities() searches it from two characters: first municipalities whose name starts with the query, then those that contain it. An autocomplete on a "municipality" field therefore does not require importing a code list into your own database.
The list is sorted in Czech alphabetical order: Č after C, Ch after H, Ř after R, Š after S and Ž after Z. With the intl extension a Collator does that; without it a built-in approximation is used. In the screenshot the list starts with Abertamy and ends with Žumberk and Županovice.
Errors that can be told apart
A wrong key ends in RuianAuthException, an exceeded limit in RuianRateLimitException, and missing parameters, a server error or an unreadable response in RuianApiException. All of them extend RuianException. When the limit runs out, an application can accept the address unvalidated and flag it for review instead of rejecting the order.
Cache and key
Every response is stored in Nette Caching, for 24 hours by default, and the cache key is built from the query parameters. Validating the same address again therefore does not use up the limit. The cache can be switched off in the configuration or cleared with clearCache(). The API key is marked #[SensitiveParameter] in the constructor, so it does not appear in error stack traces. It is, however, sent in the request URL, because that is what fnx.io requires.
Project status
Version 1.0.0 came out on 17 January 2026, version 1.0.1 from 22 March 2026 changed how the cache key is built, and version 1.0.2 from 6 November 2026 is the latest. The library runs on PHP 8.2 and newer. The tests in Nette Tester cover house number formatting, the address hierarchy, the Czech sort order of municipalities and error mapping. They replace the HTTP layer with canned responses, so they run without a network; they passed on PHP 8.2 and 8.4. The live API calls have no automated tests; they were checked only by the manual run of 6 November 2026 that the screenshot comes from.
Getting started
composer require nks-hub/nette-ruian
extensions:
ruian: NksHub\NetteRuian\DI\RuianExtension
ruian:
apiKey: %env.RUIAN_API_KEY%
cache:
ttl: 86400
The key is requested on the ruian.fnx.io page. PHP 8.2 or newer and Nette 3.1 or newer are required; the intl extension is optional.
Source code
The code is on GitHub in the nks-hub/nette-ruian repository under the MIT licence, and the package is on Packagist as nks-hub/nette-ruian. Registered company addresses by company ID come from nette-ares.