PHP code example of nks-hub / nette-ruian

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

nks-hub / nette-ruian example snippets

use NksHub\NetteRuian\Client\RuianClient;

class AddressPresenter extends Nette\Application\UI\Presenter
{
    public function __construct(
        private RuianClient $ruianClient,
    ) {
        parent::__construct();
    }
}

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);

// 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

// 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

// 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[]]

$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

$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)

// Clear cache manually
$this->ruianClient->clearCache();

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
}