SDK Python
Oficjalny klient Python dla API LokalScore — pakiet lokalscore oparty na httpx i pydantic v2. Obejmuje obsługę błędów, timeoutów, retry z wykładniczym backoffem oraz w pełni typowane modele request/response.
Instalacja
pip install lokalscoreWymagany jest Python 3.9+.
Szybki start
from lokalscore import LokalScoreClient
client = LokalScoreClient(api_key="ls_TWOJ_KLUCZ_API")
result = client.evaluate(latitude=51.1093, longitude=17.0289)
print(f"LokalScore: {result.global_score:.1f}/100")
print(f"Transport: {result.categories.transit.score:.1f}/100")
client.close()Możesz też użyć kontekstu menedżera — sesja httpx zostanie zamknięta automatycznie:
from lokalscore import LokalScoreClient
with LokalScoreClient(api_key="ls_TWOJ_KLUCZ_API") as client:
result = client.evaluate(latitude=51.1093, longitude=17.0289)
print(f"LokalScore: {result.global_score:.1f}/100")Konstruktor
LokalScoreClient(
api_key="ls_TWOJ_KLUCZ_API",
base_url="https://api.lokalscore.pl/api/v1", # domyślny URL API
timeout=30.0, # domyślny timeout zapytania (s)
max_retries=3, # liczba prób dla 429/5xx/timeout
)api_key— klucz API LokalScore (wysyłany jakoAuthorization: Bearer <klucz>).base_url— bazowy URL API (domyślniehttps://api.lokalscore.pl/api/v1).timeout— domyślny timeout zapytania w sekundach; można nadpisać per-zapytanie argumentemtimeout=....max_retries— 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ę:
result = client.evaluate(
latitude=51.1093,
longitude=17.0289,
radius_meters=1500,
)Walidacja lokalna: musi być podane co najmniej jedno z
(latitude + longitude)/address/parcel_id. SDK waliduje to lokalnie (szybki fail z czytelnym błędem) zanim wyśle zapytanie.
Metody
| Metoda | Endpoint | Opis |
|---|---|---|
evaluate(...) | POST /evaluate | Pełna ewaluacja i scoring lokalizacji. |
evaluate_lim(...) | POST /evaluate/lim | Pełny raport B2B (MPZP, GUNB, demografia, gospodarka, ryzyka). |
evaluate_greenery(...) | POST /evaluate/greenery | Wskaźnik zazielenienia terenu (Niski/Średni/Wysoki). |
evaluate_avm(...) | POST /evaluate/avm | Automatyczna wycena nieruchomości (AVM). |
autocomplete(query) | GET /prg/autocomplete | Autouzupełnianie adresów z koordynatami. |
evaluate
result = client.evaluate(
latitude=51.1093,
longitude=17.0289,
radius_meters=1000, # int, 100..5000, domyślnie 1000
custom_weights=None, # dict[str, float] — wagi 5 filarów
scoring_preset=None, # str — np. "rodzina", "student", "premium"
)evaluate_avm
Automatyczna wycena wymaga dodatkowych parametrów nieruchomości:
valuation = client.evaluate_avm(
latitude=51.1093,
longitude=17.0289,
property_type="apartment", # "apartment" | "house" | "land"
area_m2=55.0, # metraż (m²), > 0
listing_price=420000.0, # cena ofertowa (PLN), > 0
)
print(f"Szacowana wartość: {valuation.estimated_price} PLN")
print(f"Przedział: {valuation.price_low} - {valuation.price_high} PLN")autocomplete
suggestions = client.autocomplete("Legnicka Wroc")
for item in suggestions[:5]:
print(item.city, item.street, item.house_number, item.latitude, item.longitude)Własne wagi (custom_weights)
Domyślne wagi pięciu filarów możesz nadpisać przez custom_weights:
from lokalscore import LokalScoreClient
client = LokalScoreClient(api_key="ls_TWOJ_KLUCZ_API")
result = client.evaluate(
latitude=51.1093,
longitude=17.0289,
custom_weights={
"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ę do 1.0, a każda musi być w przedziale 0..1 — SDK waliduje to lokalnie.
Uwaga: gdy podasz
scoring_preset,custom_weightsiradius_meterssą 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
report = client.evaluate_lim(
latitude=51.1093,
longitude=17.0289,
radius_meters=1000,
)
print(f"LokalScore (LIM): {report.global_score:.1f}/100")
print(f"MPZP: {report.zoning_mpzp['has_plan']}")
print(f"Zalety: {', '.join(report.insights.pros[:3])}")
print(f"Wady: {', '.join(report.insights.cons[:3])}")Wskazówka:
evaluate_limdomyślnie używa timeoutu 60 s (LIM łączy wiele źródeł danych: scoring, MPZP, GUNB, demografia, gospodarka, ryzyka). Wskaźnik zieleni jest szybki (zwykle < 2 s) i pomijaradius_meters— analizuje bufor H3 L10 o stałym k-ring = 2.
Obsługa błędów
SDK mapuje kody statusu HTTP na typowane wyjątki:
from lokalscore import (
LokalScoreClient,
AuthenticationError,
RateLimitError,
NotFoundError,
ValidationError,
ServerError,
TimeoutError,
)
client = LokalScoreClient(api_key="ls_TWOJ_KLUCZ_API")
try:
result = client.evaluate(latitude=51.1093, longitude=17.0289)
except AuthenticationError:
print("Nieprawidłowy lub wygasły klucz API (401/403)")
except RateLimitError as exc:
print(f"Przekroczono limit zapytań (429); spróbuj ponownie za {exc.retry_after}s")
except ValidationError:
print("Nieprawidłowe dane wejściowe (422)")
except NotFoundError:
print("Zasób nie istnieje (404)")
except ServerError:
print("Błąd serwera (5xx)")
except TimeoutError:
print("Timeout zapytania")Hierarchia wyjątków:
LokalScoreError
├── AuthenticationError (401, 403)
├── RateLimitError (429) — z atrybutem .retry_after
├── ValidationError (422)
├── NotFoundError (404)
├── ServerError (5xx)
└── TimeoutError (timeout zapytania)Wszystkie wyjątki dziedziczą z LokalScoreError i niosą opcjonalne atrybuty status_code 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 (httpx) są również ponawiane do
max_retries. - Liczbę prób regulujesz konstruktorem (
max_retries), a timeout per-zapytanie argumentemtimeout=...w każdej metodzie.
Pełny przykład z zapisem do pliku
import json
from lokalscore import LokalScoreClient
with LokalScoreClient("ls_TWOJ_KLUCZ_API") as client:
locations = [
{"latitude": 51.1093, "longitude": 17.0289, "name": "Wrocław - Śródmieście"},
{"latitude": 52.2297, "longitude": 21.0122, "name": "Warszawa - Centrum"},
{"latitude": 50.0647, "longitude": 19.9450, "name": "Kraków - Stare Miasto"},
]
results = []
for loc in locations:
data = client.evaluate(loc["latitude"], loc["longitude"])
results.append({
"name": loc["name"],
"global_score": data.global_score,
"categories": data.categories.model_dump(),
})
with open("lokalscore_results.json", "w", encoding="utf-8") as f:
json.dump(results, f, ensure_ascii=False, indent=2)Następne kroki
- SDK Node.js — odpowiednik klienta w JavaScript/TypeScript.
- Integracja GIS — H3, GeoJSON i mapowanie wyników.
- Model scoringu — zrozumienie 5 filarów i wag.