Dokumentacja API Portalu Otwartych Danych

1. Informacje ogólne

Portal Otwartych Danych Miasta Przemyśla udostępnia dane publiczne za pośrednictwem otwartego interfejsu programistycznego API (Application Programming Interface), opartego o platformę WordPress oraz wtyczkę Studio Otwartych Danych (SOD).  API umożliwia maszynowy, zautomatyzowany dostęp do danych oraz metadanych publikowanych w portalu, zgodnie z europejskimi standardami otwartych danych, w szczególności DCAT-AP i DCAT-AP-PL.

2. Przeznaczenie interfejsu API

API przeznaczone jest dla:

  • programistów i integratorów systemów,

  • analityków danych,

  • aplikacji zewnętrznych,

  • systemów agregujących dane (harvestery),

  • krajowych i europejskich katalogów otwartych danych.

Bazowy adres API:
				
					 https://dane.przemysl.eu/wp-json/sod/v1

Każdy endpoint zwraca dane w formacie maszynowym (JSON, CSV, GeoJSON, RDF), zgodnie z jego przeznaczeniem.

Architektura API – model logiczny

API portalu oparte jest o następujące pojęcia:

  • Zbiór danych (Dataset) Logiczna kolekcja danych opisująca określony obszar tematyczny.
  • Zasób danych (Resource / Distribution) Konkretny zasób udostępniający dane (np. tabela, plik, zbiór rekordów).
  • Usługa danych (DataService) Opis punktu dostępu do danych (API), zgodny z DCAT.
  • Endpoint danych Techniczny adres URL umożliwiający pobranie danych lub metadanych.

Relacja między elementami:

				
					Dataset → Resource → Endpoint danych
Dataset → DataService → Endpoint API

Katalog zbiorów danych (Datasets)

Lista zbiorów danych
				
					GET /datasets

Zwraca listę wszystkich opublikowanych zbiorów danych wraz z metadanymi.

Parametry zapytania:
				
					limit (integer) – maksymalna liczba wyników
offset (integer) – paginacja
status (string) – active | deprecated | archived | draft | all
include_archived (boolean) – uwzględnienie zbiorów archiwalnych
Szczegóły zbioru danych
				
					GET /datasets/{id}

Zwraca pełne metadane zbioru danych, w tym:

  • opis,
  • dostawcę danych,
  • częstotliwość aktualizacji,
  • powiązane zasoby danych,
  • przypisane usługi danych (DataService).
Formaty
  • Json
  • CSV
  • GeoJson
  • JSON-LD
  • TTL

Zasoby danych (Resources)

Dane zasobu (endpoint kluczowy)

Lista wszystkich zasobów

				
					GET /resources

Zwraca listę wszystkich zasobów danych dostępnych w portalu.

Parametry zapytania:
				
					dataset_id (integer) – filtr po zbiorze danych
limit (integer)
offset (integer)
format (string) – csv | json | geojson

Zasoby konkretnego zbioru

				
					GET /resources?dataset_id={ID_ZBIORU}

Zwraca wyłącznie zasoby należące do wskazanego zbioru danych.
Jest to rekomendowany endpoint do integracji na poziomie zbioru danych.

Szczegóły zasobu

				
					GET /resources/{id}

Zwraca metadane zasobu danych, w tym:

  • format danych,

  • relację do zbioru danych,

  • informacje o dostawcy,

  • link do endpointu danych zasobu.

Dane zasobu (endpoint kluczowy)

Parametry zapytania:
				
					GET /resources/{id}/data

Endpoint umożliwia pobranie danych konkretnego zasobu.

Obsługiwane formaty danych:
  • Json
  • CSV
  • GeoJson
Parametry zapytania:
				
					format (string) – json | csv | geojson
limit (integer) – liczba rekordów
offset (integer) – paginacja
fields (string) – lista pól, np. name,lat,lon
bbox (string) – zakres przestrzenny (dla GeoJSON)

Usługi danych (DataService)

Lista usług danych

				
					GET /dataservices

Zwraca listę usług danych zdefiniowanych w portalu, zgodnych z DCAT.

Szczegóły usługi danych

				
					GET /dataservices/{id}

Zwraca pełne metadane usługi danych, w tym:

  • endpoint URL,

  • opis usługi,

  • format,

  • parametry,

  • relacje do zbiorów danych.

Przykłady użycia

				
					GET https://dane.przemysl.eu/wp-json/sod/v1/datasets?status=active&limit=20&offset=0
GET https://dane.przemysl.eu/wp-json/sod/v1/resources?limit=20&offset=0
GET https://dane.przemysl.eu/wp-json/sod/v1/datasets/123

Pola jakościowe (quality)

Odpowiedzi mogą zawierać pole quality, które opisuje jakość danych (np. kompletność metadanych, aktualność, spójność relacji zbiór–zasoby). To ułatwia budowę narzędzi oceny jakości i monitoringu katalogu.

2. Wskaźniki miejskie (City Metrics): API + eksport CSV/XLSX

Zestaw endpointów „City Metrics” udostępnia dane modułu wskaźników per boks (kafelek/sekcja) oraz umożliwia eksport CSV/XLSX. Endpointy są publiczne i tylko do odczytu.

Endpointy City Metrics

				
					GET /city-metrics/boxes – lista boksów + metadane (np. wersja schematu, generated_at, years_by_scope)
GET /city-metrics/box/{box_id}?year=YYYY&schema=1|2 – dane jednego boksu (JSON)
GET /city-metrics/box/{box_id}/export/csv?year=YYYY&schema=1|2 – eksport CSV
GET /city-metrics/box/{box_id}/export/xlsx?year=YYYY&schema=1|2 – eksport XLSX

Parametry

  • year – rocznik (np. 2024). Jeśli brak lub niedozwolony, API może zastosować rocznik domyślny (per kategoria).
  • schema – 1 (kompatybilny opisowy) lub 2 (rekomendowany tabelaryczny)
  • refresh=1 – omija cache transient (przydatne w testach/diagnostyce)
  • include_fields=1 – jeśli dostępne, zwraca pełne meta.fields (w przeciwnym razie zwraca skrót fields_summary)

Schema=1 vs schema=2 (eksport)

  • schema=1 – format opisowy (bardziej „ludzki”, kompatybilny wstecz)
  • schema=2 – „czysta tabela” (idealna do Excela/PowerBI/ETL): stałe nagłówki kolumn + wiersze danych

Przykłady (copy-paste)

				
					GET https://dane.przemysl.eu/wp-json/sod/v1/city-metrics/boxes
GET https://dane.przemysl.eu/wp-json/sod/v1/city-metrics/box/general_kpis?year=2024&schema=2
GET https://dane.przemysl.eu/wp-json/sod/v1/city-metrics/box/general_kpis/export/csv?year=2024&schema=2
GET https://dane.przemysl.eu/wp-json/sod/v1/city-metrics/box/general_kpis/export/xlsx?year=2024&schema=2

3. Pakiety danych (Bulk Export)

Pakiet danych to zestaw wielu boksów pobieranych naraz, dla wspólnego rocznika (year) i schematu (schema). To najszybsza metoda na pobieranie „dashboardu” jednym requestem.

				
					GET /city-metrics/packages – lista pakietów (metadane)
GET /city-metrics/package/{package_id}?year=YYYY&schema=1|2 – JSON: meta pakietu + dane
GET /city-metrics/package/{package_id}/export/csv?year=YYYY&schema=1|2 – eksport CSV
GET /city-metrics/package/{package_id}/export/xlsx?year=YYYY&schema=1|2 – eksport XLSX
				
			
				
					GET https://dane.przemysl.eu/wp-json/sod/v1/city-metrics/packages
GET https://dane.przemysl.eu/wp-json/sod/v1/city-metrics/package/dashboard?year=2024&schema=2
GET https://dane.przemysl.eu/wp-json/sod/v1/city-metrics/package/dashboard/export/csv?year=2024&schema=2
GET https://dane.przemysl.eu/wp-json/sod/v1/city-metrics/package/dashboard/export/xlsx?year=2024&schema=2

4. OpenAPI / schematy

Specyfikacja OpenAPI umożliwia automatyczne generowanie klientów, import do Postmana lub Swagger UI.

  • GET /openapi – OpenAPI 3.x (JSON)
  • GET /schema/city-metrics-box – JSON Schema (box)
  • GET /schema/city-metrics-package – JSON Schema (package)

Postman: Import → Link/Raw text → wklej URL /openapi
Swagger UI: w polu „Explore” wklej URL /openapi

5. Cache, ETag i odpowiedź 304 Not Modified

# Pobranie z nagłówkami

Endpointy City Metrics (box/package i eksporty) wspierają ETag i Last-Modified. Integrator może cyklicznie odpytywać API bez pobierania tych samych danych.

  • refresh=1 – omija cache po stronie serwera (testy/diagnostyka)
  • ETag + If-None-Match – jeśli bez zmian, API zwróci 304 bez body
  • Last-Modified + If-Modified-Since – alternatywna kontrola (fallback)
				
					curl -i "https://dane.przemysl.eu/wp-json/sod/v1/city-metrics/box/general_kpis?year=2024&schema=2"
# Jeśli masz ETag, użyj If-None-Match – dostaniesz 304, gdy dane bez zmian:
				
					curl -i -H "If-None-Match: W/"..."" \
"https://dane.przemysl.eu/wp-json/sod/v1/city-metrics/box/general_kpis?year=2024&schema=2"

6. Błędy i kody odpowiedzi

  • 200 – OK
  • 304 – Not Modified (ETag/Last-Modified)
  • 400 – błędne parametry (np. year poza zakresem)
  • 404 – nieznany zasób/box/package
  • 500 – błąd serwera (API zwraca strukturę błędu)

7. Rekomendacje dla integratorów

  • Do integracji BI/ETL preferuj schema=2 (czysta tabela).
  • Odpytywanie cykliczne realizuj z ETag/304 (mniej transferu i obciążenia).
  • Do pobierania wielu boksów naraz używaj pakietów (Bulk Export).
  • W testach używaj refresh=1, a w produkcji unikaj go (żeby nie omijać cache).

Jeśli potrzebujesz rozszerzeń (CORS, rate-limit policy, klucze aplikacyjne, webhooki), skontaktuj się z administratorem portalu danych.