Changelog i wersjonowanie
Ta strona opisuje politykę wersjonowania API LokalScore oraz historię istotnych zmian w kontrakcie publicznym.
Polityka wersjonowania
Wszystkie publiczne endpointy są dostępne pod prefiksem wersji w ścieżce URL:
https://lokalscore.pl/api/v1/...Zasady
- Wersjonowanie w ścieżce — główny numer wersji (
v1) jest częścią URL, więc różne wersje mogą działać równolegle. - Semver dla kontraktu — zmiany w API są kategoryzowane jako:
- Breaking change (np. usunięcie parametru, zmiana typu pola) → wymaga nowej wersji (
v2). - Additive change (np. nowy endpoint, nowe opcjonalne pole w odpowiedzi) → może trafić do bieżącej wersji bez przełamywania kompatybilności.
- Breaking change (np. usunięcie parametru, zmiana typu pola) → wymaga nowej wersji (
- Nie zamykamy starych wersji natychmiast — po wydaniu
v2wersjav1pozostaje wspierana przez okres przejściowy, aby dać czas na migrację. - Zmiany niekompatybilne są ogłaszane z wyprzedzeniem w tym Changelogu oraz w Portalu.
Co to oznacza dla Ciebie
- Zawsze pisz integrację pod konkretną wersję (np.
v1) i trzymaj ją stałą. - Dodawaj nowe pola w odpowiedziach odpornie — nie zakładaj, że pole musi istnieć, jeśli jest opcjonalne.
- Subskrybuj zmiany — istotne zmiany kontraktu są odnotowywane tutaj, w sekcjach poniżej.
Historia zmian
2026-11 — Rozszerzenie odpowiedzi widgetu (/widget/score)
Additive change: Publiczny endpoint GET /api/v1/widget/score został rozszerzony o opcjonalny obiekt pillars zawierający zagregowane oceny 5 filarów lokalizacji (transit, convenience, environment, family, leisure w skali 0–100). Szczegółowe metryki POI, odległości oraz wycena AVM pozostają dostępne wyłącznie w pełnych raportach.
2026-08 — Wersja 1.1
Nowe: Publiczny endpoint GET /api/v1/pricing — aktualne plany API i subskrypcje B2B pobierane na żywo z bazy (bez hardcodu). Jest dostępny bez klucza API i udokumentowany w Swaggerze.
2026-08 — Wersja 1.0 (stabilna)
Pierwsza publiczna, stabilna wersja kontraktu. Obejmuje:
POST /api/v1/evaluate— pełna ewaluacja i scoring lokalizacji (5 filarów,0–100).POST /api/v1/evaluate/greenery— wskaźnik zazielenienia terenu (analiza H3).POST /api/v1/evaluate/avm— automatyczna wycena i benchmarking (AVM).POST /api/v1/evaluate/lim— zaawansowany model Location Intelligence Model (B2B).GET /api/v1/prg/autocomplete— autouzupełnianie adresów z koordynatami (PRG → TERYT fallback).GET /api/v1/teryt/autocomplete— autouzupełnianie adresów na podstawie TERYT.
Dodatkowe uwagi
- Endpointy wewnętrzne portalu (np.
/usage/metrics,/subscriptions/*) nie są częścią publicznego kontraktu — nie polegaj na nich w integracjach zewnętrznych. - Wszystkie publiczne endpointy są widoczne w interaktywnej dokumentacji API.