Integracja GIS
LokalScore opiera się na siatce komórek Uber H3. Ten przewodnik pokazuje, jak pracować z indeksami H3, danymi GeoJSON oraz jak mapować wyniki za pomocą Leaflet i deck.gl.
Czym jest H3?
H3 to hierarchiczna, heksagonalna siatka geograficzna opracowana przez Uber. Każda komórka ma unikalny identyfikator (indeks H3) i jest reprezentowana jako ciąg znaków, np. 8a1e265b4c8ffff.
LokalScore używa różnych rozdzielczości H3 w zależności od celu:
| Rozdzielczość | Przybliżona powierzchnia | Zastosowanie w LokalScore |
|---|---|---|
| 8 | ~0.7 km² | Klucz cache i ogólna referencja lokalizacji |
| 9 | ~0.17 km² | Agregacja transakcji rynkowych (AVM) |
| 10 | ~0.04 km² | Indeks środkowej komórki analizy, zieleń |
Obliczanie indeksu H3
Python
import h3
# Współrzędne Wrocławia (EPSG:4326)
lat, lon = 51.1093, 17.0289
# Rozdzielczość 8 (klucz cache / referencja)
h3_8 = h3.latlng_to_cell(lat, lon, 8)
print(h3_8) # np. 8a1e265b4c8ffff
# Rozdzielczość 10 (środkowa komórka analizy)
h3_10 = h3.latlng_to_cell(lat, lon, 10)
print(h3_10)Node.js
npm install h3-jsimport { latLngToCell } from "h3-js";
const [lat, lon] = [51.1093, 17.0289];
// Rozdzielczość 8
const h3_8 = latLngToCell(lat, lon, 8);
console.log(h3_8);
// Rozdzielczość 10
const h3_10 = latLngToCell(lat, lon, 10);
console.log(h3_10);Pobieranie geometrii komórki H3 (GeoJSON)
Aby narysować komórkę H3 na mapie, pobierz jej geometrię jako GeoJSON Polygon.
Python
import h3
import json
h3_10 = h3.latlng_to_cell(51.1093, 17.0289, 10)
# Geometria komórki jako GeoJSON
geojson = h3.cell_to_boundary(h3_10, geo_json=True)
polygon = {
"type": "Polygon",
"coordinates": [[[lon, lat] for lat, lon in geojson]],
}
print(json.dumps(polygon))Node.js
import { latLngToCell, cellToBoundary } from "h3-js";
const h3_10 = latLngToCell(51.1093, 17.0289, 10);
const boundary = cellToBoundary(h3_10, true); // geoJson = true
const polygon = {
type: "Polygon",
coordinates: [boundary],
};
console.log(JSON.stringify(polygon));Mapowanie wyników w Leaflet
Poniższy przykład łączy wynik /evaluate z geometrią działki (parcel_geometry) i komórką H3, wyświetlając je na mapie Leaflet.
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
</head>
<body>
<div id="map" style="height: 600px;"></div>
<script>
const API_URL = "https://api.lokalscore.pl/api/v1";
const API_KEY = "ls_TWOJ_KLUCZ_API";
async function loadEvaluation() {
const response = await fetch(`${API_URL}/evaluate`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
address: "ul. Legnicka 12, Wrocław",
}),
});
return response.json();
}
loadEvaluation().then((data) => {
const { resolved_coordinates } = data.location;
const map = L.map("map").setView(
[resolved_coordinates.latitude, resolved_coordinates.longitude],
15
);
L.tileLayer("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", {
attribution: "© OpenStreetMap contributors",
}).addTo(map);
// Punkt analizy
L.marker([resolved_coordinates.latitude, resolved_coordinates.longitude])
.addTo(map)
.bindPopup(`LokalScore: ${data.global_score.toFixed(1)}/100`)
.openPopup();
// Geometria działki (jeśli dostępna)
if (data.location.parcel_geometry) {
L.geoJSON(data.location.parcel_geometry, {
style: { color: "#00E5FF", weight: 2, fillOpacity: 0.1 },
}).addTo(map);
}
});
</script>
</body>
</html>Mapowanie wyników w deck.gl
deck.gl pozwala renderować duże zestawy danych (np. siatkę H3 dla wielu lokalizacji) na GPU.
npm install deck.gl @deck.gl/geo-layers @deck.gl/layersimport { Deck } from "@deck.gl/core";
import { H3HexagonLayer } from "@deck.gl/geo-layers";
import { ScatterplotLayer } from "@deck.gl/layers";
// Przykładowe wyniki dla wielu lokalizacji
const results = [
{ h3: "8a1e265b4c8ffff", score: 82.4, lat: 51.1093, lon: 17.0289 },
{ h3: "8a1e265b4c9ffff", score: 74.1, lat: 51.1100, lon: 17.0300 },
// ... więcej wyników
];
const deck = new Deck({
initialViewState: {
longitude: 17.0289,
latitude: 51.1093,
zoom: 12,
},
controller: true,
layers: [
// Siatka H3 kolorowana wg wyniku
new H3HexagonLayer({
id: "h3-grid",
data: results,
getHexagon: (d) => d.h3,
getFillColor: (d) => {
// Gradient: czerwony (niski) -> zielony (wysoki)
const t = d.score / 100;
return [
Math.round(255 * (1 - t)),
Math.round(255 * t),
0,
120,
];
},
pickable: true,
onHover: ({ object }) => {
if (object) console.log(`Score: ${object.score}`);
},
}),
// Punkty analizy
new ScatterplotLayer({
id: "points",
data: results,
getPosition: (d) => [d.lon, d.lat],
getRadius: 100,
getFillColor: [0, 229, 255],
}),
],
});GeoJSON — format odpowiedzi
Endpoint /evaluate zwraca geometrię działki w formacie GeoJSON (EPSG:4326) w polu location.parcel_geometry:
{
"location": {
"resolved_coordinates": {
"latitude": 51.1093,
"longitude": 17.0289
},
"h3_index": "8a1e265b4c8ffff",
"parcel_id": "026401_1.0022.AR_11.54/2",
"parcel_area_m2": 412.5,
"parcel_geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[17.0289, 51.1093],
[17.0291, 51.1094],
[17.0292, 51.1092],
[17.0289, 51.1093]
]
]
]
}
}
}Praktyczne wskazówki
- Rozdzielczość 10 jest optymalna do wizualizacji pojedynczej lokalizacji (mała komórka).
- Rozdzielczość 8 dobrze nadaje się do map cieplnych (heatmap) dla całego miasta.
- Używaj
k-ringH3 do analizy sąsiedztwa (np.h3.grid_disk(cell, 2)). - Wyniki
/evaluatesą cache’owane przez 1 godzinę — nie ma potrzeby ponownego wywoływania dla tej samej lokalizacji.
Następne kroki
- SDK Python — klient Python z obsługą błędów.
- SDK Node.js — klient Node.js.
- Model scoringu — zrozumienie 5 filarów i wag.