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_APIKlucze 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
| Kod | Znaczenie | Co zrobić |
|---|---|---|
200 | Sukces | Przetwórz odpowiedź. |
400 | Błędne żądanie | Sprawdź poprawność parametrów (np. latitude poza zakresem, brak lokalizacji). |
401 | Brak / niepoprawny / unieważniony klucz | Sprawdź nagłówek Authorization i ważność klucza. |
404 | Zasób nie istnieje | Sprawdź URL endpointu. |
422 | Błąd walidacji | Sprawdź typy i wymagane pola w treści żądania. |
429 | Przekroczono limit | Wdróż backoff / poczekaj na reset okna czasowego. |
500 | Błąd serwera | Spróbuj ponownie później; skontaktuj się z supportem. |
504 | Przekroczono 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
429i5xx(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.