Basira reports measurements, not scores. Every number in every report is traceable to a stated formula and an open dataset. This page documents each metric: exactly how it is computed, where its data comes from and under which license, and where its accuracy honestly ends.
When you draw a polygon on the map, the analysis runs through four fixed steps:
1 — Query. Basira queries OpenStreetMap through the Overpass API for the polygon's bounding box. The box is expanded outward to a 0.01° grid (~1.1 km at the equator) so nearby requests share a cache entry; responses are cached on disk for one hour, with automatic failover across three public Overpass mirrors.
2 — Geometric clipping. Overpass returns everything inside the rectangle, but you drew an arbitrary polygon. Every feature in every layer is clipped by exact geometric intersection (Shapely), so only the parts genuinely inside your polygon survive.
3 — Metric recomputation. After clipping, each feature's length_m and area_m2 are recomputed from the clipped geometry itself — a road that crosses the boundary contributes only its inside portion. Boundary roads and land-use areas are never over-counted.
4 — Aggregation. All statistics below are computed from that clipped set, in metric units via a local UTM projection.
Cache lifetimes: OSM layers up to 1 hour, climate and population 24 hours, street network 30 minutes. A fresh OSM edit can therefore take up to an hour to appear in reports.
The polygon's coordinates are projected from WGS84 (EPSG:4326) into the local UTM zone before any measurement — computing areas directly in degrees distorts them with latitude. The zone is chosen from the polygon's own coordinates:
zone = ⌊(lon + 180) / 6⌋ mod 60 + 1
CRS = EPSG:326zz (northern hemisphere) | EPSG:327zz (southern)
area = planar area of the UTM-projected polygon → m², ha, km²
Method
Universal Transverse Mercator (UTM) projection — local planar measurement
Accuracy
Distortion well under 0.1% at typical urban scales
Honest limits
UTM distortion is negligible within a zone but grows for polygons spanning hundreds of kilometres or straddling a zone boundary.
The figure is a projected planar area, not a geodesic ellipsoidal area; at Basira's working scales the difference is immaterial.
Road length is the sum of road centerlines clipped to your polygon, measured in metres in the local UTM projection. Because clipping recomputes each feature's length from its clipped geometry, a road that crosses the polygon boundary contributes only the part inside — boundary roads are not over-counted.
Counted classes (OSM highway tag): motorway, trunk, primary, secondary, tertiary, residential, unclassified, service, living_street, pedestrian, busway, plus their *_link ramps. Footways and paths are not part of "road" length.
This measures centerline length, not carriageway width: a dual carriageway mapped in OSM as two separate ways counts twice — a standard convention, but it inflates figures relative to an intuitive "street" length.
OSM completeness varies sharply by region: near-complete in well-mapped European cities, notably weaker in rural MENA. The reported length is a floor on what is mapped, not ground truth.
Service roads and alleys are included, which can inflate density in industrial areas and compounds.
A raw indicator of mapping density — not of place quality: how many mapped OpenStreetMap features per square kilometre fall inside your polygon, across all four layers after clipping.
features_per_km2 = total clipped features (all 4 layers) / area_km²
Source
OpenStreetMap via the Overpass API
License
ODbL 1.0
Cadence
Live, cached up to 1 hour
Honest limits
This measures map completeness, not urbanity. Two physically identical neighbourhoods can score very differently if one sits in an active mapping community and the other does not.
Low values in rural MENA usually reflect under-mapping, not emptiness. Read every other OSM-derived metric with extra caution wherever coverage is low.
Building footprints (building=*) are fetched from OpenStreetMap via OSMnx, and both the footprints and your polygon are projected into the same local UTM zone before measurement. Only polygon geometries count (not building points).
Coverage is deliberately clamped at 100%: OSM footprints can overlap (multistorey roofs digitised twice, mis-tagged courtyards); without the clamp, coverage could exceed the ground it stands on.
The street-network graph inside your polygon is built with OSMnx (network_type='all'); the graph and polygon are projected to UTM, and statistics come from the standard basic_stats routine:
street_length_km = Σ edge lengths / 1000
street_density = street length (m) / area (m²), reported as km/km²
intersection_count = junction nodes (dead-ends excluded, per OSMnx)
intersections_per_km2 = intersection_count / area_km²
Intersection density is a standard proxy in the walkability literature: a finer street grain means more route choices and shorter trips.
Source
OpenStreetMap via OSMnx (basic_stats)
License
ODbL 1.0 (data) · OSMnx is MIT-licensed
Limits
Polygons up to 100 km²; result cached 30 minutes
Honest limits
This is a structural proxy for walkability: it says nothing about sidewalks, shade, safety, or crossing quality.
Only the largest connected component of the network is kept (retain_all=False); small isolated fragments are dropped.
"Intersection" follows OSMnx's standard definition (street-junction nodes excluding dead ends), which may differ from municipal definitions.
A climate summary from the ERA5 reanalysis (Copernicus Climate Change Service / ECMWF) through Open-Meteo's historical archive API, sampled at the polygon centroid, over a fixed five-full-year window: 2020-01-01 to 2024-12-31:
ERA5 reanalysis — Copernicus/ECMWF, via Open-Meteo
License
Open-Meteo under CC-BY 4.0 · ERA5 data is open (Copernicus)
Cadence
Fixed 2020–2024 window; responses cached 24 hours
Honest limits
ERA5 is a reanalysis model on a ~25–30 km grid: a regional signal, not a microclimate — it does not capture urban heat islands, narrow wadis, or a specific coastal breeze.
A five-year window is shorter than the standard 30-year climate normal, so it leans toward the warmer recent climate.
The value is sampled at one point (the centroid); for very large polygons the edges can differ from the centre.
The "hot days" threshold (35 °C) is a stated, debatable choice — not a unique physical standard.
PV yield estimates come from the PVGIS v5.2 model (European Commission Joint Research Centre) at the point or polygon centroid — Basira does not re-model irradiance itself; it relays the PVGIS calculation with stated inputs:
Static satellite irradiance databases (SARAH/ERA5 by region)
Honest limits
The model assumes an unshaded site with ideal orientation; it knows nothing about your roof, neighbours, or building geometry.
The assumed 14% system loss is a standard figure; dust and heat in MENA climates can cut real output further — panel soiling alone takes a noticeable share without regular cleaning.
Satellite-derived irradiance itself carries a few-percent typical uncertainty that varies by region.
Population inside your polygon is the sum of WorldPop 2020 grid cells (~100 m cells, dataset wpgppop) intersecting the polygon. The zonal sum runs server-side on WorldPop's own Stats API; density is then computed locally:
population = Σ WorldPop 2020 grid cells ∩ polygon (server-side zonal sum)
density = population / area_km² (UTM area)
Source
WorldPop Global Project — modelled 2020 population grid, via the WorldPop Stats API
License
CC-BY 4.0 — worldpop.org
Cadence
Fixed reference year: 2020; result cached 24 hours · polygons up to 1,000 km²
Honest limits — read this before citing the number
This is a modelled estimate, not a census. WorldPop disaggregates official census totals onto grid cells with a statistical model (dasymetric mapping with covariates); the error bands are real and meaningful, and grow where the underlying censuses are old or themselves estimates.
The reference year is fixed at 2020. Fast-growing areas, displacement, and new construction can differ substantially today.
Small polygons (a handful of grid cells) inherit large relative error; the smaller the polygon, the more the figure should be read as an order of magnitude, not a statistic.
Grid-cell boundaries do not match your polygon's edges exactly; the intersection at the fringe is approximate.
All terrain products derive from the Copernicus DEM GLO-30 (~30 m, 1 arc-second), read directly from the public cloud-optimised GeoTIFFs on AWS. Tiles crossing the area are merged, and any output larger than 1,024 px is bilinearly resampled before computation. Cell size in metres is cosine-corrected for latitude:
dx = pixel° × 111 320 × cos(lat) ; dy = pixel° × 111 320
slope = arctan√((gx/dx)² + (gy/dy)²) degrees — finite differences (Horn)
aspect = (arctan2(−gx/dx, gy/dy) + 360°) mod 360 clockwise from north; flat = −1
hillshade = cos(alt)·cos(slope) + sin(alt)·sin(slope)·cos(az − aspect)
standard (ESRI) formula; sun: azimuth 315°, altitude 45°
contours : default 10 m interval, auto-doubled until ≤200 levels
profile : 128 samples on the straight line; haversine distances; ascent/descent = Σ positive/negative deltas
Free to use with attribution (ESA Copernicus DEM licence)
Cadence
Static release (2021); no periodic updates
Honest limits
This is a surface model (DSM), not a terrain model: elevations include buildings and tree canopy, not bare ground — a "hill" inside a city may be a tower.
Nominal vertical accuracy is better than ~4 m (90% confidence) globally; it degrades on steep slopes and in dense urban fabric.
30 m cells smooth out narrow features (embankments, gullies, walls), and for large areas the DEM is downsampled before slope is computed, so steep slopes read flatter than they are.
"Bathtub" warning: reading flood risk off contours or profiles by assuming everything below a given elevation floods is misleading — it ignores hydrological connectivity, drainage, and barriers. Basira's terrain outputs are purely geometric, not flood models.
To divide any area into equal, comparable units, Basira uses the H3 hexagonal indexing system (from Uber). The default resolution is 9 — an average cell of roughly 0.105 km², small-neighbourhood scale — and resolutions 0–15 can be requested:
cells = H3.geo_to_cells(polygon, resolution) default: 9
hex_area_km2 = average cell area at that resolution (each finer step divides area by 7)
caps : polygon ≤ 200 km² · estimated cell count ≤ 50,000
Source
H3 library — a spatial indexing system, not a data source
License
Apache-2.0 (open-source software)
Honest limits
A cell belongs to the polygon if its centre point falls inside, so the grid's edge approximates your boundary rather than matching it exactly.
H3 cell areas are averages: they vary slightly across the globe by construction, and the global grid includes a small number of pentagons.