Skip to Content
Uwierzytelnianie

Uwierzytelnianie

Wszystkie endpointy publiczne API LokalScore wymagają uwierzytelnienia za pomocą klucza API przekazywanego jako token Bearer w nagłówku Authorization.


Nagłówek Authorization

Każde zapytanie musi zawierać nagłówek:

Authorization: Bearer ls_TWOJ_KLUCZ_API

Klucze mają prefiks ls_ i są generowane w Portalu. Klucz jest hashowany (SHA-256) po stronie serwera — nigdy nie jest przechowywany w postaci jawnej.

curl -X 'POST' \
'https://api.lokalscore.pl/api/v1/evaluate' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ls_TWOJ_KLUCZ_API' \
-H 'Content-Type: application/json' \
-d '{
"latitude": 51.1093,
"longitude": 17.0289
}'

Bezpieczeństwo klucza

  • Nigdy nie umieszczaj klucza w kodzie frontendu ani w publicznym repozytorium.
  • Przechowuj klucz w zmiennych środowiskowych lub menedżerze sekretów.
  • W przypadku wycieku unieważnij klucz w Portalu i wygeneruj nowy.
  • Klucz jest pokazywany tylko raz przy generowaniu.

Limity zapytań

Limit na sekundę (rate limiting)

Każdy klucz ma limit zapytań na sekundę (sliding window). Po przekroczeniu limitu otrzymasz odpowiedź 429.

Limit miesięczny

Każdy plan subskrypcyjny ma miesięczny limit zapytań. Plan jest przypisywany do klucza w momencie jego tworzenia w Portalu (sekcja Klucze API) — limity i ceny planów pochodzą z bazy danych (portal.api_plans) i są automatycznie synchronizowane na klucz. Po wyczerpaniu limitu:

  • Jeśli plan ma włączone overage (dopłata za dodatkowe zapytania), zapytania są nadal obsługiwane i rozliczane indywidualnie.
  • W przeciwnym razie otrzymasz odpowiedź 429. Dotyczy to również kluczy bez przypisanego planu — takie klucze działają z limitami domyślnymi, a po ich wyczerpaniu zawsze zwracają 429 (nigdy błąd serwera).

Bieżące zużycie możesz sprawdzić w Portalu klienta w sekcji Metryki zużycia.

Obsługa błędów

KodZnaczenieCo zrobić
200SukcesPrzetwórz odpowiedź.
400Błędne żądanieSprawdź poprawność parametrów (np. latitude poza zakresem, brak lokalizacji).
401Brak / niepoprawny / unieważniony kluczSprawdź nagłówek Authorization i ważność klucza.
404Zasób nie istniejeSprawdź URL endpointu.
422Błąd walidacjiSprawdź typy i wymagane pola w treści żądania.
429Przekroczono limitWdróż backoff / poczekaj na reset okna czasowego.
500Błąd serweraSpróbuj ponownie później; skontaktuj się z supportem.
504Przekroczono czas obliczeńZmniejsz radius_meters i spróbuj ponownie.

Przykładowe odpowiedzi błędów

401 — brak klucza:

{ "detail": "Brak klucza API w nagłówku Authorization (Format: Bearer <klucz>)" }

429 — przekroczono limit na sekundę:

{ "detail": "Przekroczono limit zapytań (Dopuszczalny limit: 10 req/sec)" }

400 — brak lokalizacji:

{ "detail": "Must provide either (latitude and longitude), or address, or parcel_id." }

Rekomendacje dla produkcji

  • Retry z backoffem dla błędów 429 i 5xx (np. wykładniczy backoff z jitterem).
  • Timeout na każde zapytanie (rekomendowane 30 s dla /evaluate).
  • Cache wyników po stronie klienta — wyniki dla tej samej lokalizacji są stabilne w krótkim okresie.
  • Monitoruj bieżące zużycie w Portalu klienta, aby uniknąć niespodziewanych kosztów overage.
LokalScore
System scoringu lokalizacji i wyceny nieruchomości w Polsce.
© 2026 LokalScore. Wszelkie prawa zastrzeżone.