Publiczny widget LokalScore
Publiczny, bezkluczowy widget do osadzania na zewnętrznych stronach — portalach ogłoszeniowych, stronach deweloperów, agencji nieruchomości czy blogach. Zwraca globalny punktowy LokalScore (0–100) oraz zagregowane oceny 5 filarów. Szczegółowe metryki POI, odległości, wycena AVM, insights i analiza planistyczna LIM pozostają w pełnym raporcie (model freemium).
Widget nie wymaga klucza API, licencji ani wykupionych raportów.
Szybki start
Wstaw poniższy fragment w miejscu, w którym ma pojawić się widget:
<script
src="https://lokalscore.pl/widget/lokalscore-widget.js"
data-address="ul. Przykładowa 1, Warszawa"
data-theme="dark"
></script>Loader automatycznie utworzy <iframe> z widgetem. CSS/JS widgetu jest w pełni
izolowany od stylów strony hosta.
Parametry
Parametry przekazuje się jako atrybuty data-* na tagu <script>.
| Parametr | Wymagany | Opis |
|---|---|---|
data-address | tak* | Adres tekstowy do geokodowania, np. ul. Przykładowa 1, Warszawa. |
data-lat | tak* | Szerokość geograficzna (wymaga data-lon). |
data-lon | tak* | Długość geograficzna (wymaga data-lat). |
data-parcel-id | tak* | Identyfikator działki ewidencyjnej TERYT. |
data-theme | nie | dark (domyślnie) lub light. |
data-title | nie | Własny nagłówek (domyślnie Ocena lokalizacji). |
* Wymagany jest dokładnie jeden sposób identyfikacji lokalizacji:
(data-lat + data-lon), data-address lub data-parcel-id.
Przykłady
Współrzędne geograficzne:
<script
src="https://lokalscore.pl/widget/lokalscore-widget.js"
data-lat="51.1084"
data-lon="17.0396"
data-theme="light"
></script>Działka ewidencyjna:
<script
src="https://lokalscore.pl/widget/lokalscore-widget.js"
data-parcel-id="026401_1.0001.1234"
></script>Struktura i treść widgetu
Widget ma jeden rozmiar full (zawsze ze stopką atrybucji):
- Nagłówek: „Ocena lokalizacji” (konfigurowalny przez
data-title). - Plakietka: globalny score (0–100) + etykieta:
≥ 80— „Doskonała lokalizacja” (zielony),≥ 50— „Średnia lokalizacja” (bursztynowy),< 50— „Niska lokalizacja” (czerwony).
- CTA: „Kup pełny raport” → prowadzi na landing page (
https://lokalscore.pl). Przycisk jest stały (niekonfigurowalny). - Stopka atrybucji: „Zobacz źródła danych na LokalScore.pl” — obowiązkowa
(wymóg licencyjny OSM/ODbL i DOC-1), nieukrywalna. Link prowadzi do podstrony
/zrodla-danychna landing page; sama marka „LokalScore.pl” jest drukowana.
Motywy
data-theme="dark"(domyślny) — ciemne tło, spójne z portalem.data-theme="light"— jasne tło, te same kolory akcentów score.
Przykłady wg poziomu oceny
Widget pokazuje trzy poziomy globalnego score (kolory spójne z portalem). Poniżej lokalizacje testowe demonstrujące każdy poziom:
1. Doskonała lokalizacja (score ≥ 80, zielony) — adres, motyw dark:
<script
src="https://lokalscore.pl/widget/lokalscore-widget.js"
data-address="Marszałkowska 1, Warszawa"
data-theme="dark"
></script>2. Średnia lokalizacja (score 50–79, bursztynowy) — współrzędne, motyw light:
<script
src="https://lokalscore.pl/widget/lokalscore-widget.js"
data-lat="51.1084"
data-lon="17.0396"
data-theme="light"
></script>3. Niska lokalizacja (score < 50, czerwony) — działka ewidencyjna + własny tytuł:
<script
src="https://lokalscore.pl/widget/lokalscore-widget.js"
data-parcel-id="160404_5.0066.32/36"
data-title="Ocena dla działki"
></script>Oczekiwane wyniki dla tych lokalizacji: odpowiednio 90.6, 70.3 i 22.2.
Jak to działa (architektura)
Strona klienta
│ wkleja <script>
▼
lokalscore-widget.js (loader)
│ tworzy <iframe src="/widget/embed.html?address=...&theme=...">
▼
/widget/embed.html + render.js
│ fetch GET /api/v1/widget/score
▼
FastAPI — publiczny endpoint (bez klucza)
│ EvaluationService + cache Redis (H3, TTL 24h)
▼
render.js — plakietka score + CTA + stopka
│ klik CTA
▼
Landing page (konwersja)Publiczny endpoint API
GET /api/v1/widget/score — bezkluczowy, publiczny.
Parametry zapytania (GET):
| Parametr | Opis |
|---|---|
lat+lon | Współrzędne geograficzne. |
address | Adres tekstowy do geokodowania. |
parcel_id | Identyfikator działki ewidencyjnej TERYT. |
Wymagany dokładnie jeden sposób identyfikacji. Odpowiedź:
{
"global_score": 78.4,
"pillars": {
"transit": 82.0,
"convenience": 78.0,
"environment": 85.0,
"family": 70.0,
"leisure": 80.0
},
"location": {
"resolved_coordinates": { "latitude": 51.1084, "longitude": 17.0396 },
"h3_index": "881e20408bfffff",
"administrative": { "voivodeship": "dolnośląskie", "county": "powiat Wrocław", "municipality": "Wrocław" },
"resolution_metadata": { "source": "coordinates" },
"parcel_id": null,
"parcel_area_m2": null,
"parcel_geometry": null
}
}- Nagłówki:
Access-Control-Allow-Origin: *,Cache-Control: public, max-age=600. - Cache Redis: po komórce H3 (rozdzielczość 8), klucz
widget:v2:h3:..., TTL 24h. - Rate limiting: 10 req/s na IP (strefa nginx
widget_limit).
Atrybucja i licencje
- Stopka „Zobacz źródła danych na LokalScore.pl” jest obowiązkowa i
nieukrywalna — link do podstrony
/zrodla-danych. - Dane LokalScore pochodzą m.in. z OpenStreetMap (licencja ODbL) — wymagana
atrybucja. Pełna lista źródeł:
GET /api/v1/data-sourceslub podstrona/zrodla-danychna landing page. - Endpoint zwraca ogólny LokalScore oraz zagregowane oceny 5 filarów. Szczegółowe metryki POI, odległości, wycena AVM oraz moduł planistyczny LIM pozostają w płatnym raporcie.
Ograniczenia
- Renderer widgetu osadzanego skupia się na identyfikatorze scoringowym — szczegółowe dane POI, wyceny AVM, analiza MPZP i eksport PDF wymagają pełnego raportu.
- CTA jest stałe (zawsze → landing page), niekonfigurowalne.
- Stopka atrybucji jest obowiązkowa.
- Motywy:
dark(domyślny) ilight.