> ## Documentation Index
> Fetch the complete documentation index at: https://slovakapi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Codelists

> Controlled vocabularies used to classify accounting units and resolve coded fields.

***

## What are codelists?

Categorical fields like legal form, ownership type, and region return a coded value rather than a plain string. Each coded value has the same shape:

```json theme={null}
{
  "kod": "112",
  "nazov": {
    "sk": "Spoločnosť s ručením obmedzeným",
    "en": "Limited liability company"
  }
}
```

* `kod` — stable entry key. Use for storing, filtering, and comparing.
* `nazov.sk` — Slovak label. Use for display in Slovak interfaces.
* `nazov.en` — English label. Use for display in English interfaces.

<Note>
  All codelists are sourced from the Statistical Office of the Slovak Republic (ŠÚSR) and returned in full with no parameters required.
</Note>

***

## Why codes matter

Codes are stable keys that never change — the human-readable label can. A field value might get a wording update, a typo fix, or a punctuation change in the source data. The code behind it won't.

Two situations where this matters:

* **Storing or comparing data.** Always store the code, not the label. Matching on a label that could silently change will eventually break.
* **Building in another language.** Use the code as a key into your own translation table instead of parsing Slovak strings.

***

## Codelist reference

| Endpoint                    | Description               | Resolves field       |
| --------------------------- | ------------------------- | -------------------- |
| `/api/pravne-formy`         | Legal form                | `pravnaForma`        |
| `/api/sk-nace`              | SK NACE economic activity | `skNace`             |
| `/api/druhy-vlastnictva`    | Ownership type            | `druhVlastnictva`    |
| `/api/velkosti-organizacie` | Organisation size         | `velkostOrganizacie` |
| `/api/kraje`                | Region                    | `kraj`               |
| `/api/okresy`               | District                  | `okres`              |
| `/api/sidla`                | Municipality              | `sidlo`              |

Location entries (`kraje`, `okresy`, `sidla`) also include a `nadradenaLokacia` field — the parent location code for districts and municipalities.

***

## Resolving a code

```js theme={null}
// 1. Fetch the legal forms codelist
const { klasifikacie } = await fetch(`/api/pravne-formy`).then(r => r.json());

// 2. Resolve a legal form code from an accounting unit
const form = klasifikacie.find(f => f.kod === unit.pravnaForma);
console.log(form?.nazov?.sk); // "Spoločnosť s ručením obmedzeným"
```

The same pattern works for all codelists — just swap the endpoint and field name.

***

## Caching codelists

Codelist data changes rarely. Fetch all codelists once at startup and keep them in memory rather than making repeated requests.

```js theme={null}
// Fetch and cache all codelists at startup
const codelists = {
  legalForms: await fetch(`/api/pravne-formy`).then(r => r.json()).then(d => d.klasifikacie),
  skNace: await fetch(`/api/sk-nace`).then(r => r.json()).then(d => d.klasifikacie),
  ownershipTypes: await fetch(`/api/druhy-vlastnictva`).then(r => r.json()).then(d => d.klasifikacie),
  orgSizes: await fetch(`/api/velkosti-organizacie`).then(r => r.json()).then(d => d.klasifikacie),
  regions: await fetch(`/api/kraje`).then(r => r.json()).then(d => d.lokacie),
  districts: await fetch(`/api/okresy`).then(r => r.json()).then(d => d.lokacie),
  municipalities: await fetch(`/api/sidla`).then(r => r.json()).then(d => d.lokacie),
};

// Resolve any code against the cached codelists
function resolve(codelist, kod) {
  return codelist.find(e => e.kod === kod)?.nazov?.sk ?? kod;
}

// Usage
console.log(resolve(codelists.legalForms, unit.pravnaForma));
console.log(resolve(codelists.regions, unit.kraj));
```

***

## Data sources

The `zdrojDat` field on each entity indicates which source system the record originates from.

| Code   | Description                                     | Resolves field |
| ------ | ----------------------------------------------- | -------------- |
| `SUSR` | Statistical Office of the Slovak Republic       | `zdrojDat`     |
| `SP`   | State Treasury System                           | `zdrojDat`     |
| `DC`   | DataCentrum                                     | `zdrojDat`     |
| `FRSR` | Financial Administration of the Slovak Republic | `zdrojDat`     |
| `JUS`  | Unified State Accounting                        | `zdrojDat`     |
| `OVSR` | Commercial Bulletin of the Slovak Republic      | `zdrojDat`     |
| `CKS`  | Central Consolidation System                    | `zdrojDat`     |
| `SAM`  | Budget Information System for Municipalities    | `zdrojDat`     |