@uxf/smart-address

Typed client helpers for the Czech Smart Address API — address/ZIP search, autocomplete option loaders, and address-detail lookups.

When to use

Reach for this package when you need to search Czech addresses (RÚIAN-style data), build address/ZIP autocomplete inputs, or resolve a picked suggestion to a full address record. It is a thin, dependency-free layer over the public https://www.smart-address.cz/api REST API using the global fetch.

It is not a UI package: it ships no React components or hooks. The loader factories return a (term) => Promise<Option[]> function shaped to feed an async select/combobox, but rendering is up to the consumer.

There are two versioned surfaces, mapping to the API's /v1 and /v2 endpoints:

• @uxf/smart-address/v2 — the current surface. Exposes individual named functions, returns a structured extended-detail response, and adds getBuildingAddresses and searchCityPart. Prefer it for new code.
• @uxf/smart-address/v1 — the legacy surface. Exposes a single SmartAddress namespace object and the individual administrative-unit lookups (getCity, getCityPart, getMomc, getMop, getStreet) that v2 does not have.

Installation

yarn add @uxf/smart-address

No peer dependencies and no runtime dependencies. It only needs a fetch-capable runtime (any browser, or Node 18+). No API key, token, or provider setup is required.

There is no root/default export — import from a versioned subpath (/v1, /v2) or the shared types (/common). A bare @uxf/smart-address import resolves to nothing.

Quick start

import { SmartAddress } from "@uxf/smart-address/v1";

// Street-level autocomplete: returns [{ id, label }] ready for a select
const options = await SmartAddress.loadAddressOptions({ term: "Sovova", level: 2 });

// Resolve a chosen option's id to the full address record
const chosen = options.at(0);
const address = chosen ? await SmartAddress.getAddress(chosen.id) : null;

The same functions exist on the v2 surface as individual named exports:

import { loadAddressOptions, getAddress } from "@uxf/smart-address/v2";

const options = await loadAddressOptions({ term: "Sovova", level: 2 });

API

Entry points

Import path	Exposes
@uxf/smart-address/v2	Individual named functions (below) + all type definitions
@uxf/smart-address/v1	The SmartAddress namespace object holding the same-named methods, plus type definitions
@uxf/smart-address/common	Shared type definitions only

Functions

Signatures below are the v2 named exports. On v1 the same names are accessed as SmartAddress.<name>; v1/v2 differences are noted in the last column.

Function	Signature	Notes
search	(props: { term: string; level: number; limit?: number; zip?: number; address?: string }) => Promise<Location[]>	limit defaults to 10. Empty term → [] (no request).
searchZip	(term: string, limit?: number) => Promise<Location[]>	Returns [] unless term is 1–5 digits.
searchCityPart	(term: string, limit?: number) => Promise<CityPart[]>	v2 only. Empty term → [].
loadAddressOptions	(params: { term: string; level: number; limit?: number; zip?: number; address?: string; getLabel?: (address: Location) => string }) => Promise<Option[]>	Maps search results to Options. Default label: `${ulice ?? ""}, ${obec ?? ""}`.
loadZipOptions	(params: { term: string; limit?: number; getLabel?: (address: Location) => string }) => Promise<Option[]>	Default label: the psc (ZIP).
createAddressLoader	(params: { level: number; limit?: number; zip?: number; address?: string; getLabel?: (address: Location) => string }) => (term: string) => Promise<Option[]>	Curried loadAddressOptions for async selects. v1 params omit address.
createZipLoader	(params: { limit?: number; getLabel?: (address: Location) => string }) => (term: string) => Promise<Option[]>	Curried loadZipOptions. v1 params omit limit.
getAddress	(id: number) => Promise<Location>	Single address by id.
getAddressExtended	(id: number) => Promise<AddressExtended>	Extended detail. v1 returns the flat LocationExtended instead.
getBuildingAddresses	(id: number) => Promise<Location[]>	v2 only. All addresses within a building.

v1-only lookups on SmartAddress, each (id: number) => Promise<Location>: getCity, getCityPart, getMomc, getMop, getStreet.

level reference

The level used by search / loadAddressOptions / createAddressLoader selects the granularity of the returned records (values are Czech RÚIAN terms):

level	Meaning
1	House number — číslo domovní (číslo orientační, znak čísla orientačního)
2	Street — ulice
3	Part of municipality — název části obce
4	Prague municipal district (MOP) — název MOP
5	Municipal district / city ward (MOMC) — název MOMC
6	Municipality — název obce
7	District — okres (future)
8	Region — kraj (future)

Value model (types)

All types are exported from @uxf/smart-address/common (and re-exported from /v1 and /v2). v1's index re-exports a subset; v2 re-exports the full set.

• Option — { id: number; label: string }. The result of the load*/create*Loader helpers, ready for a select.
• Location — the full address record. Key fields: id, obec/obecNazev, ulice/uliceNazev, castObceNazev, cisloDomovni, cisloOrientacni, psc (ZIP), okresNazev, krajNazev, level, and gps: Point | null. Most fields are nullable.
• Point — { latitude: number; longitude: number }.
• LocationExtended (v1 getAddressExtended) — a flat record adding building/energy details to an address (electricity & gas distributor, construction type, floor/unit counts, utility connections, elevator, heating, areas, object type, etc.).
• AddressExtended (v2 getAddressExtended) — the same information grouped into { zakladniAdresa, administrativniUdaje, udajeBudovy, udajeEnergii } (AddressExtendedBasicResponse / …AdministrativeResponse / …BuildingResponse / …EnergyResponse).
• CityPart (v2) — { id: number; name: string; obecKod: number; obecNazev: string; zips: string[] }.
• Detail sub-types used above: BuildingType, BuildingUsageType, ConstructionType, ElevatorType, GasConnectionType, HeatingType, SewerConnectionType, WaterConnectionType (all { id, nazev, popis, zkracenyNazev, zacatekPlatnosti, konecPlatnosti }), and ObjectType / ObjectTypeBasic ({ id, nazev }).

Gotchas

• No root export. Import from @uxf/smart-address/v1, .../v2, or .../common. There is no main/exports in package.json, so subpaths resolve to the built files by filesystem; a bare package import has no entry.
• Needs a fetch global. Every call uses fetch against https://www.smart-address.cz/api. No auth is sent.
• Czech data. All Location field names and level labels are Czech; the endpoints are specific to Czech addresses.
• Empty / invalid input short-circuits. search and load* return [] for an empty term without hitting the network; searchZip also rejects non-digit or >5-digit terms.
• No runtime validation. Responses are await response.json() cast to the declared type; malformed responses or non-2xx statuses are not checked or thrown here — handle errors at the call site.
• SmartAddress.getCity (v1) is broken. It concatenates the base URL twice, producing a malformed request URL. Avoid it; use the other lookups.

Links

• Smart Address — the underlying API service.