nette-ruian

nette-ruian je rozšíření pro Nette, které ověřuje české adresy podle RÚIAN, u překlepu nabídne nejbližší skutečnou adresu a umí postupný výběr kraj, obec, ulice, číslo i našeptávač obcí.

nette-ruian: ověření adresy Kaprova 14 i s překlepem, výpis obcí, ulic a adresních míst, kraj a obec podle ID obce a české řazení obcí, vše z RÚIAN

nette-ruian je rozšíření pro Nette, které ověřuje a doplňuje české adresy podle RÚIAN, státního registru územní identifikace, adres a nemovitostí. Kurýr vrátí zásilku, protože v objednávce stálo „Kaprvoa 14, Praha“ bez PSČ a bez čísla orientačního. Formulář tu adresu přijal, protože pole „ulice“ bere jakýkoli text. S nette-ruian se adresa před uložením porovná s registrem: knihovna vrátí, jestli taková adresa existuje, a když ne, nabídne nejbližší skutečnou i s mírou shody. Na snímku nahoře z překlepu „Kaprvoa 14“ udělala „Kaprova 14/13, Praha, 11000“ se shodou 0,94.

Odkud data jdou

RÚIAN vede Český úřad zeměměřický a katastrální a jeho oficiální rozhraní je SOAP s rozsáhlou dokumentací. Knihovna proto volá RUIAN API od fnx.io, které nad volně stažitelnými daty RÚIAN nabízí jednoduché REST rozhraní s JSONem. Klíč je zdarma, přijde e-mailem a platí pro něj limit 1 000 požadavků za hodinu; provozovatel výslovně neslibuje dostupnost ani správnost dat. Pro běžný formulář s cache to stačí.

Adresu jde napsat, nebo naklikat

Ověření napsané adresy

validate() přijme to, co uživatel vyplnil: obec, část obce, ulici, PSČ, číslo popisné, orientační nebo evidenční, případně přímo ID adresy v RÚIAN. Vrátí ValidateResult se stavem MATCH (přesná shoda), POSSIBLE (shoda s odchylkou), NOT_FOUND nebo ERROR a s nalezeným místem, které nese ID kraje, obce, části obce, ulici, čísla, PSČ a ID adresního místa. getFormattedAddress() z něj složí řádek pro štítek. Do databáze se pak vyplatí uložit hlavně ID adresy: je stabilní a adresu z něj jde kdykoli znovu dohledat přes validateByRuianId().

Že je výsledek POSSIBLE i bez překlepu, je normální: dotaz „Kaprova 14, Praha“ bez čísla orientačního vrátil adresu 14/13 jako možnou shodu, ne jako přesnou. Aplikace se pak může uživatele zeptat, jestli myslel právě tuhle adresu.

Postupný výběr

Pro formuláře, kde má uživatel adresu vybrat místo psaní, slouží čtyři kroky: getRegions() vrátí kraje, getMunicipalities() obce v kraji, getStreets() ulice v obci (u obcí bez ulic části obce) a getPlaces() adresní místa v ulici s čísly a PSČ. Každý krok bere ID z předchozího. Ve Frýdlantu (ID obce 564028) vrátil třetí krok 118 ulic a čtvrtý 34 adresních míst v ulici Zámecká.

Když znáte jen ID obce, vrátí getAddressHierarchy() kraj, obec a ulice najednou. Kraj najde procházením seznamů obcí jednotlivých krajů, takže první volání je až 14 požadavků, další jdou z cache. Pro Frýdlant to na snímku dalo Liberecký kraj (CZ051) a 118 ulic. Pro ID, které žádný kraj neobsahuje, vrátí kraj i obec null.

Našeptávač obcí bez vlastní databáze

getAllMunicipalities() projde všechny kraje a složí seznam všech obcí. Při zkoušce 6. listopadu 2026 to bylo 6 256 obcí ze 14 krajů za necelou sekundu a seznam se uloží do cache na sedminásobek nastavené doby, ve výchozím stavu na týden. searchMunicipalities() nad ním hledá od dvou znaků: nejdřív obce, jejichž název dotazem začíná, pak ty, které ho obsahují uvnitř. Na našeptávač v poli „obec“ tedy není potřeba importovat číselník do vlastní databáze.

Seznam je řazený podle české abecedy: Č je za C, Ch za H, Ř za R, Š za S a Ž za Z. S rozšířením intl to obstará Collator, bez něj vestavěné přibližné řazení. Na snímku seznam začíná obcí Abertamy a končí obcemi Žumberk a Županovice.

Chyby, které jde od sebe poznat

Špatný klíč skončí výjimkou RuianAuthException, překročený limit RuianRateLimitException a chybějící parametry, chyba serveru nebo nečitelná odpověď RuianApiException. Všechny dědí z RuianException. Aplikace tak může při vyčerpaném limitu adresu přijmout bez ověření a označit ji ke kontrole, místo aby objednávku odmítla.

Cache a klíč

Každá odpověď se ukládá do Nette Caching, ve výchozím stavu na 24 hodin, a klíč cache se skládá z parametrů dotazu. Opakované ověření stejné adresy tedy limit nespotřebuje. Cache jde vypnout v konfiguraci nebo smazat metodou clearCache(). Klíč API je v konstruktoru označený #[SensitiveParameter], takže se nevypíše v trasování chyby. Posílá se ale v adrese požadavku, protože to tak fnx.io vyžaduje.

Stav projektu

Verze 1.0.0 vyšla 17. ledna 2026, verze 1.0.1 z 22. března 2026 změnila skládání klíče cache a verze 1.0.2 ze 6. listopadu 2026 je poslední. Knihovna běží na PHP 8.2 a novějším. Testy v Nette Tester pokrývají formátování čísel domu, adresní hierarchii, české řazení obcí a mapování chyb. HTTP vrstvu nahrazují připravenými odpověďmi, takže běží bez sítě; prošly na PHP 8.2 i 8.4. Volání živého API automaticky testovaná nejsou, ověřil je jen ruční běh ze 6. listopadu 2026, ze kterého je snímek.

Jak začít

composer require nks-hub/nette-ruian
extensions:
    ruian: NksHub\NetteRuian\DI\RuianExtension

ruian:
    apiKey: %env.RUIAN_API_KEY%
    cache:
        ttl: 86400

Klíč se vyžádá na stránce ruian.fnx.io. Potřeba je PHP 8.2 nebo novější a Nette 3.1 nebo novější; rozšíření intl je volitelné.

Zdrojový kód

Kód je na GitHubu v repozitáři nks-hub/nette-ruian pod licencí MIT, balíček na Packagistu jako nks-hub/nette-ruian. Firemní sídla podle IČO doplní nette-ares.

← Všechny reference