Skip to Content
Przewodniki integracjiSDK Python

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 lokalscore

Wymagany 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 jako Authorization: Bearer <klucz>).
  • base_url — bazowy URL API (domyślnie https://api.lokalscore.pl/api/v1).
  • timeout — domyślny timeout zapytania w sekundach; można nadpisać per-zapytanie argumentem timeout=....
  • max_retries — 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ę:

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

MetodaEndpointOpis
evaluate(...)POST /evaluatePełna ewaluacja i scoring lokalizacji.
evaluate_lim(...)POST /evaluate/limPełny raport B2B (MPZP, GUNB, demografia, gospodarka, ryzyka).
evaluate_greenery(...)POST /evaluate/greeneryWskaźnik zazielenienia terenu (Niski/Średni/Wysoki).
evaluate_avm(...)POST /evaluate/avmAutomatyczna wycena nieruchomości (AVM).
autocomplete(query)GET /prg/autocompleteAutouzupeł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_weights i radius_meters 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
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_lim domyś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 pomija radius_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 argumentem timeout=... 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

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