API dla firm (beta)

Autoryzacja

Każde zapytanie wymaga nagłówka Authorization z kluczem w schemacie Bearer. Klucz ma prefiks sk_slt_ i jest pokazywany tylko raz — w momencie wydania. Zapisz go bezpiecznie; nie da się go odczytać ponownie.

Authorization: Bearer sk_slt_...

Limity

Limity są dzienne i naliczane per klucz. Domyślnie: 50 raportów/dzień oraz 500 screenów/dzień. Każda odpowiedź zawiera nagłówki z aktualnym stanem limitu:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49

Po wyczerpaniu limitu zapytanie zwraca HTTP 429 z ciałem:

{"ok":false,"error":"rate_limited"}

POST /api/v1/report

Pełny raport lokalizacji. W ciele podaj identyfikator działki (TERYT) albo współrzędne. Zapytanie odpytuje na żywo kilkanaście rejestrów, więc czas odpowiedzi to zwykle 10–30 s.

Ciało zapytania (JSON) — jedna z dwóch form:

{"parcel":"281410_2.0023.715/41"}
{"lat":53.6989,"lon":20.6983}

Odpowiedź 200:

{
  "ok": true,
  "profile": { /* LocationProfile z redakcjami RODO — bez cen pojedynczych transakcji */ },
  "score": {
    "band": "green",          // green | yellow | red
    "overall": 72,
    "dimensions": [ /* … */ ],
    "topDrivers": [ /* … */ ]
  }
}

profile to obiekt LocationProfile z redakcjami RODO — nie zawiera cen pojedynczych transakcji. score.band przyjmuje wartości green, yellow lub red.

Kody błędów:

• 400 — bad_request / outside_poland
• 401 — invalid_key
• 404 — parcel_not_found
• 429 — rate_limited
• 503 — storage_unavailable

Przykład (curl):

curl -X POST https://solertio.pl/api/v1/report \
  -H "Authorization: Bearer sk_slt_..." \
  -H "Content-Type: application/json" \
  -d '{"parcel":"281410_2.0023.715/41"}'

# alternatywnie po współrzędnych:
curl -X POST https://solertio.pl/api/v1/report \
  -H "Authorization: Bearer sk_slt_..." \
  -H "Content-Type: application/json" \
  -d '{"lat":53.6989,"lon":20.6983}'

POST /api/v1/screen

Szybki przesiew (2 zapytania) — do masowego triage. Przyjmuje wyłącznie współrzędne i zwraca skrócony status planistyczny i powodziowy wraz z rankingiem.

Ciało zapytania (JSON):

{"lat":53.6989,"lon":20.6983}

Odpowiedź 200:

{
  "ok": true,
  "screen": {
    "zoningStatus": "vector",           // vector | none_found | raster_fallback
    "designation": "MN",                 // symbol przeznaczenia lub null
    "floodHit": false,                   // true | false | null
    "minReturnPeriodYears": 100          // 10 | 100 | 500 | null
  },
  "rank": {
    "score": 78,                         // 0–100
    "band": "green",
    "reasons": [ "…" ]
  }
}

zoningStatus: vector / none_found / raster_fallback. designation to symbol przeznaczenia lub null. floodHit to true / false / null, a minReturnPeriodYears — 10 / 100 / 500 / null. rank.score mieści się w zakresie 0–100.

Przykład (curl):

curl -X POST https://solertio.pl/api/v1/screen \
  -H "Authorization: Bearer sk_slt_..." \
  -H "Content-Type: application/json" \
  -d '{"lat":53.6989,"lon":20.6983}'

Uczciwość i podstawa prawna

Dane przesiewowe pochodzą z usług rządowych (GUGiK / Geoportal) i mogą być niekompletne lub nieaktualne — brak trafienia nie oznacza braku ryzyka.

Zwracany score to sygnał przesiewowy, a NIE wycena ani porada. Nie zastępuje operatu szacunkowego rzeczoznawcy majątkowego (UGN) ani wypisu i wyrysu z planu miejscowego.

RODO: dane o cenach udostępniamy wyłącznie jako agregaty z RCN obejmujące co najmniej 5 transakcji — bez cen pojedynczych transakcji.

Atrybucja: dane GUGiK / Geoportal udostępniane na zasadach danych otwartych. Zachowaj atrybucję źródeł przy dalszym wykorzystaniu (tak jak w stopce serwisu).

Wersjonowanie

Aktualna ścieżka to /api/v1. Zmiany łamiące zgodność (breaking changes) będą publikowane pod nową wersją ścieżki — istniejąca wersja pozostaje stabilna.