Obce v Kostce — Dokumentace API

Rychlý start

Typický postup pro stažení dat indikátorů:

Zavolejte get_all_indikatory pro procházení celého katalogu a nalezení potřebných hodnot indikator_id.
Volitelně zavolejte get_all_obce pro získání hodnot obce_id, pokud chcete filtrovat podle konkrétních obcí.
Zavolejte get_indikator s vybranými ID pro stažení časových řad ve formátu .csv

Formát odpovědi

Všechny endpointy při úspěchu vrátí CSV soubor ke stažení (text/csv). Při chybě je vrácen JSON objekt s klíčem error.

Endpoints

GET /api/v0/get_all_indikatory

Stáhněte kompletní katalog indikátorů. Slouží k procházení dostupných hodnot indikator_id a jejich metadat před stažením dat.

Parametry

Žádné.

Sloupce odpovědi

indikator_id nazev kategorie zdroj jednotka agregatni_funkce popis vzorec naposledy_updatovany

Ukázka výstupu

indikator_id,indikator_nazev,zdroj,kategorie,jednotka,agregatni_funkce,naposledy_updatovany,popis,vzorec
POCET-OBYVATEL,Střední stav obyvatel,ČSÚ,demografie,osob,sum,2024-01-15,Střední stav obyvatel obce (odhad k 1. 7.).,
CZSO-3103-0,Počet dokončených bytů celkem,ČSÚ,bydlení,bytů,sum,2024-01-15,Počet dokončených bytů na území obce v daném roce.,
MSP-schvaleny-rozpocet-1111,Příjem z daně z příjmů FO placené plátci,Monitor státní pokladny,finance,Kč,sum,2024-03-01,,

curl

curl "https://obcevkostce.ceskepriority.cz/api/v0/get_all_indikatory"

Python

import requests

r = requests.get("https://obcevkostce.ceskepriority.cz/api/v0/get_all_indikatory")
with open("indikatory.csv", "wb") as f:
    f.write(r.content)

GET /api/v0/get_all_obce

Stáhněte kompletní rejstřík obcí (všech 6 254 českých obcí). Slouží k nalezení hodnot obce_id pro filtrování v get_indikator.

Parametry

Žádné.

Sloupce odpovědi

obce_id obce_nazev obce_orp

Ukázka výstupu

obce_id,obce_nazev,obce_orp
554782,Praha,Praha
582786,Brno,Brno
500054,Ostrava,Ostrava
536148,Plzeň,Plzeň
592005,Znojmo,Znojmo

curl

curl "https://obcevkostce.ceskepriority.cz/api/v0/get_all_obce"

Python

import requests

r = requests.get("https://obcevkostce.ceskepriority.cz/api/v0/get_all_obce")
with open("obce.csv", "wb") as f:
    f.write(r.content)

GET /api/v0/get_indikator

Stáhněte časové řady pro jeden nebo více indikátorů. Volitelně filtrujte podle obce, rozsahu let a přidejte sloupce s metadaty.

Parametry

Parametr	Typ	Povinnost	Popis
indikatory	string	povinný	Jedno nebo více ID indikátorů. Pro více hodnot parametr opakujte.
obce	string	volitelný	Filtrování na konkrétní obce. Pro více obcí parametr opakujte. Bez parametru jsou zahrnuty všechny obce.
rok_min	integer	volitelný	Nejstarší rok zahrnutý do výsledků (včetně).
rok_max	integer	volitelný	Nejnovější rok zahrnutý do výsledků (včetně).
extras	boolean	volitelný	Výchozí výstup obsahuje pouze IDs a hodnoty. Při nastavení na `true` je každý řádek doplněn o název a okres obce a název, jednotku, zdroj a popis indikátoru — vhodné pro přímou analýzu bez nutnosti join operací.

Sloupce odpovědi — výchozí

indikator_id obce_id rok hodnota

Ukázka výstupu

indikator_id,obce_id,rok,hodnota
POCET-OBYVATEL,554782,2020,1275520.0
POCET-OBYVATEL,554782,2021,1281345.0
POCET-OBYVATEL,582786,2020,381346.0
POCET-OBYVATEL,582786,2021,382405.0

Sloupce odpovědi — s extras=true

obce_id obce_nazev obce_orp indikator_id nazev kategorie zdroj jednotka agregatni_funkce popis vzorec naposledy_updatovany rok hodnota

Ukázka výstupu — s extras=true

obce_id,obce_nazev,obce_orp,indikator_id,indikator_nazev,jednotka,zdroj,...,rok,hodnota
554782,Praha,Praha,POCET-OBYVATEL,Střední stav obyvatel,osob,ČSÚ,...,2020,1275520.0
554782,Praha,Praha,POCET-OBYVATEL,Střední stav obyvatel,osob,ČSÚ,...,2021,1281345.0
582786,Brno,Brno,POCET-OBYVATEL,Střední stav obyvatel,osob,ČSÚ,...,2020,381346.0

Skutečný výstup také obsahuje sloupce kategorie, agregatni_funkce, popis, vzorec a naposledy_updatovany.

curl — jeden indikátor

curl -G "https://obcevkostce.ceskepriority.cz/api/v0/get_indikator" \
  --data-urlencode "indikatory=POCET-OBYVATEL"

curl — více indikátorů, filtr let, extras

curl -G "https://obcevkostce.ceskepriority.cz/api/v0/get_indikator" \
  --data-urlencode "indikatory=POCET-OBYVATEL" \
  --data-urlencode "indikatory=CZSO-3103-0" \
  -d "rok_min=2010" \
  -d "rok_max=2023" \
  -d "extras=true"

curl — filtr na konkrétní obce

curl -G "https://obcevkostce.ceskepriority.cz/api/v0/get_indikator" \
  --data-urlencode "indikatory=POCET-OBYVATEL" \
  --data-urlencode "obce=554782" \
  --data-urlencode "obce=500054"

Python

import requests

params = {
    "indikatory": ["POCET-OBYVATEL", "CZSO-3103-0"],
    "obce": ["554782"],          # volitelné: filtr na obec
    "rok_min": 2010,             # volitelné: rozsah let
    "rok_max": 2023,
    "extras": "true",            # volitelné: zahrnutí sloupců s metadaty
}

r = requests.get(
    "https://obcevkostce.ceskepriority.cz/api/v0/get_indikator",
    params=params
)
with open("data.csv", "wb") as f:
    f.write(r.content)

Chyba (HTTP 400) — vrácena, pokud nejsou zadány žádné hodnoty indikatory:
{"error": "You must provide at least one indikator_id!"}

Chyba (HTTP 400) — vrácena, pokud některé hodnoty indikatory nebo obce nejsou v databázi. Všechny chyby jsou hlášeny najednou:
{"errors": ["Unknown indikator_id: CZSO-999", "Unknown obce_id: 999999, 123456"]}