Skip to Content
Przewodniki integracjiPubliczny widget

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>.

ParametrWymaganyOpis
data-addresstak*Adres tekstowy do geokodowania, np. ul. Przykładowa 1, Warszawa.
data-lattak*Szerokość geograficzna (wymaga data-lon).
data-lontak*Długość geograficzna (wymaga data-lat).
data-parcel-idtak*Identyfikator działki ewidencyjnej TERYT.
data-themeniedark (domyślnie) lub light.
data-titlenieWł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-danych na 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):

ParametrOpis
lat+lonWspółrzędne geograficzne.
addressAdres tekstowy do geokodowania.
parcel_idIdentyfikator 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-sources lub podstrona /zrodla-danych na 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) i light.
LokalScore
System scoringu lokalizacji i wyceny nieruchomości w Polsce.
© 2026 LokalScore. Wszelkie prawa zastrzeżone.