API kdo-vodi.si

kdo-vodi.si je register nosilcev javnih funkcij v Sloveniji: kdo zaseda katero javno funkcijo, v kateri organizaciji, od kdaj do kdaj in po katerem uradnem viru. Celoten register je dostopen prek javnega, samo bralnega REST API-ja.

Brezplačen in odprt. Uporaba API-ja je brezplačna, brez registracije in brez pogodbe.
Brez avtentikacije. Ni API ključev, ni žetonov, ni glave Authorization. Vsak zahtevek je navaden GET.
Omejitev števila zahtevkov: 60 zahtevkov na minuto na IP naslov. Ob prekoračitvi odgovori 429 Too Many Requests z glavo Retry-After.
CORS: odgovori nosijo Access-Control-Allow-Origin: *, zato lahko API kličete neposredno iz brskalnika s katere koli domene.
Samo branje. Podprta je izključno metoda GET. Vsi odgovori so application/json.
Vsak podatek ima vir. Zapisi nosijo polje sources z natančno spletno stranjo uradnega vira, iz katere je bil podatek prebran.
Licenca CC BY 4.0. Podatke lahko uporabite za karkoli, tudi komercialno, ob navedbi vira. Viri z nekomercialno licenco v te odgovore ne pridejo.

Osnove

Osnovni naslov (base URL) vseh končnih točk:

https://kdo-vodi.si/api/v1

Primer zahtevka:

curl -s "https://kdo-vodi.si/api/v1/office-holders?office=mayor&per_page=5"

Strojno berljiv opis celotnega API-ja je na voljo kot OpenAPI 3.0.3 dokument: https://kdo-vodi.si/api/v1/openapi.json. Interaktivni prikaz (Swagger UI) je na dnu te strani.

Ostranjevanje (paginacija)

Vsi seznami razen /sources so ostranjeni v standardni Laravel obliki. Parametra per_page (privzeto 50, najmanj 1, največ 200) in page (privzeto 1) veljata za vsak ostranjen seznam.

{
  "data": [ ... ],
  "links": { "first": "…?page=1", "last": "…?page=9", "prev": null, "next": "…?page=2" },
  "meta": { "current_page": 1, "last_page": 9, "per_page": 50, "total": 431 }
}

Napake

Neznan slug (ali neznan parent / organization v filtru) vrne 404, prekoračena omejitev zahtevkov 429. Telo je v obeh primerih JSON.

GET`/api/v1/organizations`

Seznam organizacij in organov (vlada, ministrstva, agencije, sodišča, občine, poslanske in svetniške skupine …), z vodjo vsake organizacije, kadar je znan.

Parameter	Tip	Pomen
`type`	string	Filter po vrsti organizacije (`root_type`): `government`, `ministry`, `government_service`, `body_within_ministry`, `administrative_unit`, `agency`, `public_fund`, `social_insurance_provider`, `court`, `constitutional_court`, `other_state_body`, `national_assembly`, `national_council`, `president`, `prime_minister`, `municipality`, `council_group`, `public_institute`, `local_community`.
`tier`	string	Upošteva se samo, kadar `type` ni podan. `primary` (privzeto) izpusti podrejeni sloj, `subordinate` vrne samo njega (`council_group`, `public_institute`, `local_community`), `all` vrne vse.
`parent`	string	Slug nadrejene organizacije; vrne njene neposredne podrejene organe.
`q`	string	Iskanje po imenu organizacije (delno ujemanje).
`per_page`	integer	Velikost strani; privzeto 50, največ 200.
`page`	integer	Številka strani; privzeto 1.

Primer: /api/v1/organizations?type=ministry&per_page=2

{
  "data": [
    {
      "slug": "ministrstvo-za-finance",
      "name": "Ministrstvo za finance",
      "type": "ministry",
      "type_label": "Ministrstvo",
      "body_type": null,
      "parent": { "slug": "vlada", "name": "Vlada Republike Slovenije", "type": "government" },
      "website": "https://www.gov.si/drzavni-organi/ministrstva/ministrstvo-za-finance/",
      "phone": "01 369 33 00",
      "address": "Župančičeva ulica 3, 1000 Ljubljana",
      "email": "gp.mf@gov.si",
      "leader": {
        "name": "Ime Priimek",
        "person_slug": "ime-priimek",
        "office": "minister",
        "office_code": "minister",
        "since": "2022-06-01"
      },
      "image": null,
      "sources": [
        { "authority": "Vlada Republike Slovenije", "url": "https://www.gov.si/drzavni-organi/ministrstva/ministrstvo-za-finance/" }
      ],
      "url": "https://kdo-vodi.si/organ/ministrstvo-za-finance",
      "api_url": "https://kdo-vodi.si/api/v1/organizations/ministrstvo-za-finance"
    }
  ],
  "links": { "first": "…", "last": "…", "prev": null, "next": "…" },
  "meta": { "current_page": 1, "last_page": 9, "per_page": 2, "total": 18 }
}

image je null ali objekt { "url", "attribution", "source", "hosted" }.

GET`/api/v1/organizations/{slug}`

Ena organizacija. Poleg polj iz seznama vrne še vse trenutne nosilce funkcij v tej organizaciji (vodjo in člane, npr. poslance poslanske skupine) ter njene neposredno podrejene organe.

Parameter	Tip	Pomen
`slug`	string, v poti, obvezen	Slug organizacije, npr. `vlada`.

Primer: /api/v1/organizations/vlada

{
  "data": { "slug": "vlada", "name": "Vlada Republike Slovenije", "type": "government", "…": "kot v seznamu" },
  "office_holders": [
    {
      "person": { "name": "Ime Priimek", "slug": "ime-priimek" },
      "office": "predsednik vlade",
      "office_code": "prime_minister",
      "role_detail": null,
      "organization": { "name": "Vlada Republike Slovenije", "slug": "vlada" },
      "since": "2022-06-01",
      "since_precision": "day",
      "until": null,
      "status": "serving",
      "current": true,
      "sources": [ { "authority": "Vlada Republike Slovenije", "url": "https://www.gov.si/…" } ]
    }
  ],
  "children": [
    { "slug": "ministrstvo-za-finance", "name": "Ministrstvo za finance", "type": "ministry", "body_type": null }
  ]
}

GET`/api/v1/office-holders`

Osrednja končna točka: seznam nosilcev funkcij — kdo, katero funkcijo, v kateri organizaciji, od kdaj do kdaj in po katerem viru. Privzeto vrne samo trenutne nosilce.

Parameter	Tip	Pomen
`office`	string	Šifra funkcije, npr. `mayor`, `mp`, `minister`, `prime_minister`, `deputy_pm`, `minister_no_portfolio`, `state_secretary`, `director`, `body_head`, `local_councillor`, `national_councillor`, `parliamentary_group_leader`, `parliamentary_group_member`, `council_group_leader`, `council_group_member`, `working_body_chair`.
`organization`	string	Slug organizacije.
`person`	string	Slug osebe.
`current`	boolean	Privzeto `true` — samo mandati brez končnega datuma. `current=0` vključi tudi pretekle.
`per_page`	integer	Velikost strani; privzeto 50, največ 200.
`page`	integer	Številka strani; privzeto 1.

Primer: /api/v1/office-holders?office=mayor&per_page=1

{
  "data": [
    {
      "person": { "name": "Ime Priimek", "slug": "ime-priimek" },
      "office": "župan",
      "office_code": "mayor",
      "role_detail": null,
      "organization": { "name": "Občina Kamnik", "slug": "obcina-kamnik" },
      "since": "2022-12-18",
      "since_precision": "day",
      "until": null,
      "status": "serving",
      "current": true,
      "sources": [ { "authority": "Državna volilna komisija", "url": "https://www.dvk-rs.si/…" } ]
    }
  ],
  "links": { "…": "…" },
  "meta": { "current_page": 1, "last_page": 212, "per_page": 1, "total": 212 }
}

status: elected, serving, acting, suspended, ended, contested. since_precision: day, month, year, inferred, at_least, unknown. role_detail nosi natančnejšo, s spletne strani prebrano vlogo (npr. resor državnega sekretarja), kadar je bolj specifična od splošne oznake funkcije.

GET`/api/v1/people`

Iskanje oseb po imenu. Vsak zadetek nosi celotno znano zgodovino njegovih funkcij.

Parameter	Tip	Pomen
`q`	string	Iskanje po imenu (delno ujemanje). Brez njega vrne vse osebe po abecedi.
`per_page`	integer	Velikost strani; privzeto 50, največ 200.
`page`	integer	Številka strani; privzeto 1.

Primer: /api/v1/people?q=novak

GET`/api/v1/people/{slug}`

Ena oseba z zgodovino funkcij. Mandati so razvrščeni tako, da so tekoči prvi, nato po najnovejšem začetku.

Parameter	Tip	Pomen
`slug`	string, v poti, obvezen	Slug osebe, npr. `ime-priimek`.

{
  "data": {
    "slug": "ime-priimek",
    "name": "Ime Priimek",
    "birth_year": 1971,
    "image": { "url": "https://kdo-vodi.si/media/12", "attribution": "Wikimedia Commons", "source": "https://commons.wikimedia.org/…", "hosted": true },
    "offices": [
      {
        "person": { "name": "Ime Priimek", "slug": "ime-priimek" },
        "office": "minister",
        "office_code": "minister",
        "role_detail": null,
        "organization": { "name": "Ministrstvo za finance", "slug": "ministrstvo-za-finance" },
        "since": "2022-06-01",
        "since_precision": "day",
        "until": null,
        "status": "serving",
        "current": true,
        "sources": [ { "authority": "Vlada Republike Slovenije", "url": "https://www.gov.si/…" } ]
      }
    ],
    "url": "https://kdo-vodi.si/oseba/ime-priimek",
    "api_url": "https://kdo-vodi.si/api/v1/people/ime-priimek"
  }
}

GET`/api/v1/sources`

Seznam uradnih virov, na katere so vezani podatki v registru. Brez parametrov in brez ostranjevanja.

{
  "data": [
    { "key": "dvk-mayors", "name": "DVK — župani", "authority": "Državna volilna komisija" },
    { "key": "govsi-ministries", "name": "GOV.SI — ministrstva", "authority": "Vlada Republike Slovenije" }
  ]
}

GET`/api/v1/openapi.json`

Celoten OpenAPI 3.0.3 opis API-ja (poti, parametri, sheme odgovorov) — primeren za generatorje odjemalcev in za strojno branje: https://kdo-vodi.si/api/v1/openapi.json.

Bulk prenosi (CSV)

Če potrebujete celoten register naenkrat, ga ne pridobivajte s prelistavanjem API-ja — uporabite pripravljene izvoze:

nosilci.csv — vsi nosilci funkcij z mandatnimi datumi in viri.
organizacije.csv — vse organizacije in organi.
viri.csv — seznam virov.

Izvozi so omejeni na 10 prenosov na minuto na IP naslov.

Več

Viri — iz katerih uradnih virov je register sestavljen.
Podatkovne vrzeli — česa register (še) nima in zakaj.
llms.txt — kratek strojni povzetek strani.

API kdo-vodi.si

Osnove

Ostranjevanje (paginacija)

Napake

Končne točke

GET/api/v1/organizations

GET/api/v1/organizations/{slug}

GET/api/v1/office-holders

GET/api/v1/people

GET/api/v1/people/{slug}

GET/api/v1/sources

GET/api/v1/openapi.json