SDK Node.js
Oficjalny klient JavaScript/TypeScript dla API LokalScore — pakiet @lokalscore/sdk oparty na natywnym fetch (Node.js 18+, zero zależności). Obejmuje obsługę błędów, timeoutów, retry z wykładniczym backoffem oraz w pełni typowane typy request/response.
Instalacja
npm install @lokalscore/sdkWymagany jest Node.js 18+ (wbudowany fetch).
Szybki start
import { LokalScoreClient } from "@lokalscore/sdk";
const client = new LokalScoreClient("ls_TWOJ_KLUCZ_API");
const result = await client.evaluate({
latitude: 51.1093,
longitude: 17.0289,
});
console.log(`LokalScore: ${result.global_score.toFixed(1)}/100`);
console.log(`Transport: ${result.categories.transit.score.toFixed(1)}/100`);Konstruktor
const client = new LokalScoreClient("ls_TWOJ_KLUCZ_API", {
baseUrl: "https://api.lokalscore.pl/api/v1", // domyślny URL API
timeoutMs: 30_000, // domyślny timeout zapytania (ms)
maxRetries: 3, // liczba prób dla 429/5xx/timeout
});apiKey— klucz API LokalScore (wysyłany jakoAuthorization: Bearer <klucz>).baseUrl— bazowy URL API (domyślniehttps://api.lokalscore.pl/api/v1).timeoutMs— domyślny timeout zapytania w milisekundach; można nadpisać per-zapytanie (np.evaluateLim({ timeoutMs: ... })).maxRetries— maksymalna liczba prób (1 = brak ponowień). Ponawiane są tylko429,5xxi timeouty.
Obsługa lokalizacji
Możesz przekazać lokalizację na trzy sposoby — współrzędne, adres lub działkę:
const result = await client.evaluate({
latitude: 51.1093,
longitude: 17.0289,
radiusMeters: 1500,
});Walidacja lokalna: musi być podane co najmniej jedno z
(latitude + longitude)/address/parcelId. SDK waliduje to lokalnie (rzucaTypeErrorz czytelnym komunikatem) zanim wyśle zapytanie.
Metody
| Metoda | Endpoint | Opis |
|---|---|---|
evaluate(options) | POST /evaluate | Pełna ewaluacja i scoring lokalizacji. |
evaluateLim(options) | POST /evaluate/lim | Pełny raport B2B (MPZP, GUNB, demografia, gospodarka, ryzyka). |
evaluateGreenery(options) | POST /evaluate/greenery | Wskaźnik zazielenienia terenu (Niski/Średni/Wysoki). |
evaluateAVM(options) | POST /evaluate/avm | Automatyczna wycena nieruchomości (AVM). |
autocomplete(query) | GET /prg/autocomplete | Autouzupełnianie adresów z koordynatami. |
Konwencja: metody używają opcji w notacji camelCase (
radiusMeters,customWeights,scoringPreset,parcelId), które SDK automatycznie mapuje na kontrakt API wsnake_case.
evaluate
const result = await client.evaluate({
latitude: 51.1093,
longitude: 17.0289,
radiusMeters: 1000, // int, 100..5000, domyślnie 1000
customWeights: undefined, // Partial<Record<PillarKey, number>>
scoringPreset: undefined, // np. "rodzina", "student", "premium"
});evaluateAVM
Automatyczna wycena wymaga dodatkowych parametrów nieruchomości:
const valuation = await client.evaluateAVM({
latitude: 51.1093,
longitude: 17.0289,
propertyType: "apartment", // "apartment" | "house" | "land"
areaM2: 55.0, // metraż (m²), > 0
listingPrice: 420000.0, // cena ofertowa (PLN), > 0
});
console.log(`Szacowana wartość: ${valuation.estimated_price} PLN`);
console.log(`Przedział: ${valuation.price_low} - ${valuation.price_high} PLN`);autocomplete
const suggestions = await client.autocomplete("Legnicka Wroc");
for (const item of suggestions.slice(0, 5)) {
console.log(item.city, item.street, item.house_number, item.latitude, item.longitude);
}Własne wagi (customWeights)
Domyślne wagi pięciu filarów możesz nadpisać przez customWeights:
const result = await client.evaluate({
latitude: 51.1093,
longitude: 17.0289,
customWeights: {
transit: 0.30, // transport
convenience_retail: 0.25, // usługi i handel
environment_comfort: 0.20, // środowisko i komfort
family_education: 0.15, // rodzina i edukacja
leisure_culture: 0.10, // kultura i rekreacja
},
});Dostępne klucze to: transit, convenience_retail, environment_comfort, family_education, leisure_culture. Wagi muszą sumować się w przybliżeniu do 1.0, a każda musi być w przedziale 0..1 — SDK waliduje to lokalnie.
Uwaga: gdy podasz
scoringPreset,customWeightsiradiusMeterssą ignorowane (zgodnie z walidacją serwera). SDK automatycznie je usuwa z payloadu.
LIM i wskaźnik zazielenienia
Klient udostępnia również metody dla raportów B2B — LIM (Location Intelligence Model) i wskaźnik zazielenienia:
// Pełny raport B2B — MPZP, konkurencja (GUNB), demografia,
// gospodarka i ryzyka środowiskowe
const report = await client.evaluateLim({
latitude: 51.1093,
longitude: 17.0289,
radiusMeters: 1000,
});
console.log(`LokalScore (LIM): ${report.global_score.toFixed(1)}/100`);
console.log(`MPZP: ${report.zoning_mpzp.has_plan}`);
console.log(`Zalety: ${report.insights.pros.slice(0, 3).join(", ")}`);
console.log(`Wady: ${report.insights.cons.slice(0, 3).join(", ")}`);Wskazówka:
evaluateLimdomyślnie używa timeoutu 60 s (LIM łączy wiele źródeł danych: scoring, MPZP, GUNB, demografia, gospodarka, ryzyka). Możesz nadpisać go przeztimeoutMs. Wskaźnik zieleni jest szybki (zwykle < 2 s) i pomijaradiusMeters— analizuje bufor H3 L10 o stałym k-ring = 2.
Obsługa błędów
SDK mapuje kody statusu HTTP na typowane wyjątki:
import {
LokalScoreClient,
AuthenticationError,
RateLimitError,
NotFoundError,
ValidationError,
ServerError,
TimeoutError,
} from "@lokalscore/sdk";
const client = new LokalScoreClient("ls_TWOJ_KLUCZ_API");
try {
const result = await client.evaluate({
latitude: 51.1093,
longitude: 17.0289,
});
} catch (err) {
if (err instanceof AuthenticationError) {
console.error("Nieprawidłowy lub wygasły klucz API (401/403)");
} else if (err instanceof RateLimitError) {
console.error(`Przekroczono limit zapytań (429); spróbuj ponownie za ${err.retryAfter}s`);
} else if (err instanceof ValidationError) {
console.error("Nieprawidłowe dane wejściowe (422)");
} else if (err instanceof NotFoundError) {
console.error("Zasób nie istnieje (404)");
} else if (err instanceof ServerError) {
console.error("Błąd serwera (5xx)");
} else if (err instanceof TimeoutError) {
console.error("Timeout zapytania");
}
}Hierarchia wyjątków:
LokalScoreError
├── AuthenticationError (401, 403)
├── RateLimitError (429) — z atrybutem .retryAfter
├── ValidationError (422)
├── NotFoundError (404)
├── ServerError (5xx)
└── TimeoutError (timeout zapytania)Wszystkie wyjątki dziedziczą z LokalScoreError i niosą opcjonalne atrybuty statusCode oraz body.
Retry i timeouty
- 429 i 5xx są ponawiane automatycznie z wykładniczym backoffem
2 ** próba(0s, 2s, 4s, …). - Dla 429 SDK honoruje nagłówek
Retry-After, jeśli jest obecny. - Timeouty (przez
AbortController) są również ponawiane domaxRetries. - Liczbę prób regulujesz opcją
maxRetries, a timeout per-zapytanie opcjątimeoutMs(np. wevaluateLim).
Typy TypeScript
Wszystkie typy request/response są eksportowane z pakietu:
import type {
EvaluationResponse,
LIMResponse,
GreeneryResponse,
AVMResponse,
AutocompleteSuggestion,
EvaluateOptions,
EvaluateAvmOptions,
} from "@lokalscore/sdk";
const result: EvaluationResponse = await client.evaluate({
latitude: 51.1093,
longitude: 17.0289,
});
console.log(result.global_score); // numberNastępne kroki
- SDK Python — odpowiednik klienta w Pythonie.
- Integracja GIS — H3, GeoJSON i mapowanie wyników.
- Model scoringu — zrozumienie 5 filarów i wag.