Skip to Content

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/sdk

Wymagany 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 jako Authorization: Bearer <klucz>).
  • baseUrl — bazowy URL API (domyślnie https://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ą tylko 429, 5xx i 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 (rzuca TypeError z czytelnym komunikatem) zanim wyśle zapytanie.

Metody

MetodaEndpointOpis
evaluate(options)POST /evaluatePełna ewaluacja i scoring lokalizacji.
evaluateLim(options)POST /evaluate/limPełny raport B2B (MPZP, GUNB, demografia, gospodarka, ryzyka).
evaluateGreenery(options)POST /evaluate/greeneryWskaźnik zazielenienia terenu (Niski/Średni/Wysoki).
evaluateAVM(options)POST /evaluate/avmAutomatyczna wycena nieruchomości (AVM).
autocomplete(query)GET /prg/autocompleteAutouzupeł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 w snake_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, customWeights i radiusMeters są 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: evaluateLim domyślnie używa timeoutu 60 s (LIM łączy wiele źródeł danych: scoring, MPZP, GUNB, demografia, gospodarka, ryzyka). Możesz nadpisać go przez timeoutMs. Wskaźnik zieleni jest szybki (zwykle < 2 s) i pomija radiusMeters — 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 do maxRetries.
  • Liczbę prób regulujesz opcją maxRetries, a timeout per-zapytanie opcją timeoutMs (np. w evaluateLim).

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); // number

Następne kroki

LokalScore
System scoringu lokalizacji i wyceny nieruchomości w Polsce.
© 2026 LokalScore. Wszelkie prawa zastrzeżone.