Wskaźnik zazielenienia terenu (Greenery)
Endpoint /evaluate/greenery to lekki, dedykowany wskaźnik zazielenienia lokalizacji. Oblicza stosunek powierzchni biologicznie czynnej i terenów zielonych (lasy, parki, skwery, tereny zieleni urządzonej) w otoczeniu wybranego punktu, korzystając z analizy sąsiedztwa w siatce Uber H3 o rozdzielczości 10.
W przeciwieństwie do pełnego /evaluate — który podaje zieleń jako jeden z pięciu filarów scoringu (environment_comfort) — ten endpoint zwraca jeden, samodzielny wskaźnik w formie klasyfikacji (Niski / Średni / Wysoki). To szybkie i tanie narzędzie do porównywania wielu działek pod kątem zieleni bez uruchamiania pełnego raportu.
Endpoint jest dostępny pod adresem POST /api/v1/evaluate/greenery i wymaga klucza API (Bearer).
Kiedy używać Greenery?
| Scenariusz | Czego dostarcza |
|---|---|
| Porównanie kilku działek budowlanych | Która działka ma najwyższy udział zieleni w otoczeniu? |
| Screening ofert mieszkaniowych | Czy okolica jest zielona (park, las, skwer) czy zurbanizowana? |
| Filtr wstępny przed LIM | Szybkie odsianie lokalizacji o bardzo niskiej zieleni przed kosztowniejszą analizą. |
| Walidacja „zielonej” narracji deweloperskiej | Obiektywny, liczbowy wskaźnik pokrycia zielenią zamiast subiektywnych opisów. |
Wskazówka: Wskaźnik zieleni jest też częścią filaru
environment_comfortw odpowiedzi/evaluatei LIM (polegreenery_coverage_pct). Ten endpoint udostępnia go osobno, w bardziej rozbudowanej formie (klasyfikacja + liczba przebadanych komórek).
Parametry żądania
Endpoint przyjmuje ten sam schemat EvaluationRequest, co /evaluate. W praktyce istotna jest lokalizacja — pozostałe pola (radius_meters, custom_weights, scoring_preset) nie mają wpływu na wynik analizy zieleni.
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
latitude / longitude | float | tak* | Współrzędne w EPSG:4326 (latitude -90..90, longitude -180..180). |
address | string | tak* | Adres tekstowy w Polsce do geokodowania, np. ul. Legnicka 12, Wrocław. |
parcel_id | string | tak* | Pełny identyfikator działki TERYT, np. 026401_1.0022.AR_11.54/2. |
* Wymagane jest dokładnie jedno z: (współrzędne) albo address albo parcel_id.
Przykłady wywołań
curl -X 'POST' \
'https://api.lokalscore.pl/api/v1/evaluate/greenery' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ls_TWOJ_KLUCZ_API' \
-H 'Content-Type: application/json' \
-d '{
"latitude": 51.1093,
"longitude": 17.0289
}'Struktura odpowiedzi
Odpowiedź jest kompaktowa — jedno obiektowe żądanie, jeden mały obiekt odpowiedzi:
| Pole | Typ | Opis |
|---|---|---|
center_cell | string | Identyfikator środkowej komórki Uber H3 (rozdzielczość 10) odpowiadającej analizowanemu punktowi. |
sampled_cells_count | int | Liczba wszystkich przebadanych komórek H3 w buforze (k-ring = 2, łącznie 19 komórek). |
green_cells_count | int | Liczba komórek sklasyfikowanych jako zielone w bazie danych. |
coverage_ratio | float | Stosunek pokrycia terenami zielonymi (0.0–1.0, zaokrąglony do 4 miejsc). |
classification | string | Klasyfikacja pokrycia: Wysoki, Średni lub Niski. |
Przykład odpowiedzi
{
"center_cell": "8f2637c5303c000",
"sampled_cells_count": 19,
"green_cells_count": 11,
"coverage_ratio": 0.5789,
"classification": "Wysoki"
}Interpretacja klasyfikacji
Klasyfikacja wynika wprost z coverage_ratio:
coverage_ratio | classification | Znaczenie |
|---|---|---|
≥ 0.50 | Wysoki | Ponad połowa bufora (k-ring = 2) to tereny zielone — park, las, skwer lub zieleń urządzona. |
0.20 – 0.49 | Średni | Znaczna część otoczenia to zieleń, ale dominuje zabudowa / tereny utwardzone. |
< 0.20 | Niski | Teren silnie zurbanizowany, z minimalnym udziałem zieleni. |
Jak czytać wynik: Wskaźnik odnosi się do bezpośredniego otoczenia punktu (bufor o k-ring = 2 w siatce H3 L10, ~2–3 sąsiednie komórki w każdą stronę).
coverage_ratioto udział zielonych komórek wśród wszystkich przebadanych, a nie odległość do najbliższego parku. Wysoki wynik oznacza, że zieleń jest wokół punktu, niekoniecznie na działce.
Obsługa błędów
- 401/403 — brak lub nieprawidłowy klucz API (Bearer).
- 422 — błędne parametry (np. brak lokalizacji,
latitude/longitudepoza zakresem). - 429 — przekroczony limit zapytań (rate limit lub limit miesięczny).
- 504 — przekroczony limit czasu. Endpoint jest szybki (zwykle < 2 s), ale geokodowanie adresu może wydłużyć odpowiedź.
Następne kroki
- Location Intelligence Model (LIM) — pełny raport B2B, którego odpowiedź zawiera
greenery_coverage_pctw filarze środowiska. - Automatyczna wycena (AVM) — benchmark ceny ofertowej względem rynku transakcyjnego RCN.
- Dokumentacja API — interaktywna konsola Swagger UI ze schematem
GreeneryResponse. - Integracja GIS — praca z indeksami H3 (analiza zieleni używa rozdzielczości 10).
- Uwierzytelnianie — klucze Bearer, limity i obsługa błędów.