PHPackages nks-hub/nette-ruian - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. nks-hub/nette-ruian ActiveLibrary[API Development](/categories/api) nks-hub/nette-ruian =================== Nette extension for RUIAN (Czech Address Registry) API client with caching support v1.0.1(3mo ago)04MITPHPPHP >=8.2 Since Jan 17Pushed 3mo agoCompare [ Source](https://github.com/nks-hub/nette-ruian)[ Packagist](https://packagist.org/packages/nks-hub/nette-ruian)[ Docs](https://github.com/nks-hub/nette-ruian)[ RSS](/packages/nks-hub-nette-ruian/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (14)Versions (3)Used By (0) [![Latest Stable Version](https://camo.githubusercontent.com/c8fb32c35cb957273c8514b6db6eeec3357eb73b8789223ffb288101e7824141/68747470733a2f2f706f7365722e707567782e6f72672f6e6b732d6875622f6e657474652d727569616e2f76)](https://packagist.org/packages/nks-hub/nette-ruian)[![Total Downloads](https://camo.githubusercontent.com/818a4ad096a77e22d2cc879f1e059e5aa967361b8597a024bc89da000699eb36/68747470733a2f2f706f7365722e707567782e6f72672f6e6b732d6875622f6e657474652d727569616e2f646f776e6c6f616473)](https://packagist.org/packages/nks-hub/nette-ruian)[![PHP Version](https://camo.githubusercontent.com/d840cef9807c8f76051ad687841d67f4d830c84e0d83236968e53124ef6742d5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e322d3838393242462e737667)](https://php.net/)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE) Nette RUIAN =========== [](#nette-ruian) Nette extension for [RUIAN API](https://ruian.fnx.io/) - Czech Address Registry (Registr územní identifikace, adres a nemovitostí). Requirements ------------ [](#requirements) - PHP 8.2+ - Nette 3.1+ Installation ------------ [](#installation) ``` composer require nks-hub/nette-ruian ``` Configuration ------------- [](#configuration) Register extension in your `config.neon`: ``` extensions: ruian: NksHub\NetteRuian\DI\RuianExtension ruian: apiKey: 'your-api-key-here' cache: enabled: true # Enable caching (default: true) ttl: 86400 # Cache TTL in seconds (default: 86400 = 24 hours) ``` ### Getting API Key [](#getting-api-key) Request your free API key at [ruian.fnx.io](https://ruian.fnx.io/). Free tier allows 1000 requests per hour. Usage ----- [](#usage) ### Inject RuianClient [](#inject-ruianclient) ``` use NksHub\NetteRuian\Client\RuianClient; class AddressPresenter extends Nette\Application\UI\Presenter { public function __construct( private RuianClient $ruianClient, ) { parent::__construct(); } } ``` ### Validate Address [](#validate-address) ``` use NksHub\NetteRuian\Response\ValidateResult; // Validate by address components $result = $this->ruianClient->validate([ 'municipalityName' => 'Praha', 'street' => 'Kaprova', 'cp' => '14', ]); if ($result->isMatch()) { echo "Exact match found!"; echo $result->place->getFormattedAddress(); } elseif ($result->isPossible()) { echo "Possible match with confidence: " . $result->place->confidence; } // Validate by RUIAN ID directly $result = $this->ruianClient->validateByRuianId(21692912); ``` ### Address Builder (Progressive Selection) [](#address-builder-progressive-selection) Build address step by step using cascading selectors: ``` // Step 1: Get all regions (kraje) $regions = $this->ruianClient->getRegions(); // Returns: Region[] with regionId, regionName // Step 2: Get municipalities in a region $municipalities = $this->ruianClient->getMunicipalities('CZ010'); // Returns: Municipality[] with municipalityId, municipalityName // Step 3: Get streets in a municipality $streets = $this->ruianClient->getStreets(554782); // Returns: Street[] with streetName or streetLessPartName // Step 4: Get address points on a street $places = $this->ruianClient->getPlaces(554782, 'Kaprova'); // Returns: Place[] with cp, co, ce, zip, placeId ``` ### Municipality Autocomplete (Typeahead) [](#municipality-autocomplete-typeahead) Search municipalities by name for autocomplete/typeahead functionality: ``` // Search municipalities starting with "Pra" $results = $this->ruianClient->searchMunicipalities('Pra', 10); // Returns: Municipality[] matching the query, max 10 results // Results prioritize: // 1. Names starting with query (Praha, Prachatice, ...) // 2. Names containing query (Nová Praha, ...) // Get all municipalities (cached for 7 days) $allMunicipalities = $this->ruianClient->getAllMunicipalities(); // Returns: Municipality[] - all ~6300 Czech municipalities ``` ### Combined Queries [](#combined-queries) Convenience methods for common use cases: ``` // Find address by components (simpler than validate()) $result = $this->ruianClient->findAddress( municipalityName: 'Praha', street: 'Kaprova', cp: '14', ); // Validate and get all places on the matched street $data = $this->ruianClient->validateWithPlaces([ 'municipalityName' => 'Praha', 'street' => 'Kaprova', ]); // Returns: ['result' => ValidateResult, 'places' => Place[]] // Get complete address hierarchy for a municipality $hierarchy = $this->ruianClient->getAddressHierarchy(554782); // Returns: ['region' => Region, 'municipality' => Municipality, 'streets' => Street[]] ``` ### Response DTOs [](#response-dtos) #### ValidateResult [](#validateresult) ``` $result->status; // 'MATCH', 'POSSIBLE', 'NOT_FOUND', 'ERROR' $result->message; // Error message (if any) $result->place; // ValidatedPlace object (if found) $result->isMatch(); // Exact match $result->isPossible(); // Fuzzy match $result->isFound(); // Match or possible $result->isNotFound(); // No match $result->isError(); // API error ``` #### ValidatedPlace [](#validatedplace) ``` $place->confidence; // Match confidence (0.0 - 1.0) $place->regionId; // Region code (e.g., 'CZ010') $place->regionName; // Region name $place->municipalityId; // Municipality RUIAN ID $place->municipalityName; // Municipality name $place->municipalityPartId; // Municipality part RUIAN ID $place->municipalityPartName; // Municipality part name $place->streetName; // Street name $place->cp; // Descriptive number (cislo popisne) $place->co; // Orientation number (cislo orientacni) $place->ce; // Evidence number (cislo evidencni) $place->zip; // Postal code $place->ruianId; // RUIAN address point ID $place->getFormattedAddress(); // Full formatted address $place->getFormattedNumber(); // Formatted house number (cp/co or ev.ce) ``` ### Validation Parameters [](#validation-parameters) ParameterDescription`municipalityName`Municipality name`municipalityId`RUIAN municipality ID`municipalityPartName`Municipality part name`municipalityPartId`RUIAN municipality part ID`zip`Postal code`street`Street or municipality part name`cp`Descriptive number (cislo popisne)`co`Orientation number (cislo orientacni)`ce`Evidence number (cislo evidencni)`ruianId`Direct RUIAN address ID lookup### Caching [](#caching) Caching is enabled by default to reduce API calls. Cache is stored using Nette's caching system. ``` // Clear cache manually $this->ruianClient->clearCache(); ``` To disable caching: ``` ruian: apiKey: 'your-api-key' cache: enabled: false ``` ### Exception Handling [](#exception-handling) ``` use NksHub\NetteRuian\Exception\RuianApiException; use NksHub\NetteRuian\Exception\RuianAuthException; use NksHub\NetteRuian\Exception\RuianRateLimitException; try { $result = $this->ruianClient->validate([...]); } catch (RuianAuthException $e) { // Invalid API key (HTTP 401) } catch (RuianRateLimitException $e) { // Rate limit exceeded (HTTP 429) } catch (RuianApiException $e) { // Other API errors } ``` API Rate Limits --------------- [](#api-rate-limits) - Free tier: 1000 requests/hour - No SLA guarantees Contributing ------------ [](#contributing) Contributions are welcome! For major changes, please open an issue first. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'feat: description'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request Support ------- [](#support) - 📧 **Email:** - 🐛 **Bug reports:** [GitHub Issues](https://github.com/nks-hub/nette-ruian/issues) - 📖 **RUIAN API:** [ruian.fnx.io](https://ruian.fnx.io/) License ------- [](#license) MIT License — see [LICENSE](LICENSE) for details. --- Made with ❤️ by [NKS Hub](https://github.com/nks-hub) ### Health Score 36 — LowBetter than 79% of packages Maintenance80 Actively maintained with recent releases Popularity1 Limited adoption so far Community6 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~63 days Total 2 Last Release 104d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/01e4841749ee2b4cf7211d784b093bf67523ed6489c6931401211b130df13884?d=identicon)[lukyrys](/maintainers/lukyrys) --- Top Contributors [![lukyrys](https://avatars.githubusercontent.com/u/2318346?v=4)](https://github.com/lukyrys "lukyrys (6 commits)") --- Tags address-validationapicomposerczechczech-republicgeocodingnette-extensionnette-frameworkphpruianapivalidationgeocodingaddressnetteczechruian ### Code Quality Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/nks-hub-nette-ruian/health.svg) ``` [![Health](https://phpackages.com/badges/nks-hub-nette-ruian/health.svg)](https://phpackages.com/packages/nks-hub-nette-ruian) ``` ### Alternatives [nette/forms 📝 Nette Forms: generating, validating and processing secure forms in PHP. Handy API, fully customizable, server & client side validation and mature design. 54413.6M513](/packages/nette-forms)[nette/web-project Nette: Standard Web Project 10993.3k](/packages/nette-web-project)[tomaj/nette-api Nette api 36273.2k8](/packages/tomaj-nette-api)[jcf/geocode Google Geocoding API for Laravel 50162.8k](/packages/jcf-geocode)[ondrs/hi Czech names and surnames greeting generator API PHP wrapper 4068.6k](/packages/ondrs-hi)[jackmartin/laravel-yandex-geocode Simply service laravel Yandex Geocoding 1117.6k](/packages/jackmartin-laravel-yandex-geocode) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)