Linear Referencing
Linear referencing allows properties to apply to portions of a segment without splitting the geometry. This promotes shape stability and reduces versioning when only part of a road changes.
To avoid splitting road segments at any and every property change, linear referencing defines how properties that apply to portions of a segment can vary along that segment while it is generally understood to be the same "road." Segment splits are then reserved for more significant intersections so that we don't have to version the entire road any time any piece of the road changes.
Linear reference values
A linear reference is a normalized position from 0.0 (start of segment) to 1.0 (end of segment).
at vs between
| Property | Purpose | Example |
|---|---|---|
at | Single point location | at: 0.3 — 30% along segment |
between | Range along segment | between: [0.2, 0.7] — 20% to 70% |
When between is not provided (or is null), the attribute applies to the full segment.
Calculation method
Overture computes linear references using WGS84 geodetic distance in meters:
linear_ref = geodetic_distance_along_segment_from_start / total_geodetic_length
Both distances must be computed on the WGS84 ellipsoid, not planar distance on raw lon/lat coordinates. Other approaches exist (e.g., projected coordinates), but geodetic distance provides consistent accuracy globally.
Examples
Apache Sedona (SQL):
SELECT ST_LENGTHSPHEROID(ST_GEOMFROMWKB(geometry)) AS segment_length_m
FROM segments;
pyproj (Python):
from pyproj import Geod
from shapely import wkb
geod = Geod(ellps="WGS84")
line_geometry = wkb.loads(geometry) # geometry is WKB bytes
segment_length = geod.geometry_length(line_geometry) # meters
See the transportation-splitter for a complete implementation.
Functions like ST_LINELOCATEPOINT can produce incorrect results on geometries that cross over or near themselves in 2D (curved on-ramps, mountain switchbacks, cul-de-sacs). These functions may pick the wrong location when the line passes over or close to itself, even though the geometry is valid because crossings occur at different elevations or positions along the segment. Note that Overture disallows self-intersecting segments in its own data.
Why geodetic distance matters
Using planar distance (treating lon/lat as Cartesian x/y) can produce incorrect linear references, especially at high latitudes or for long segments. For a 10 km east-west segment at 60°N latitude, planar calculations can underestimate length by ~50%. Some map projections (e.g., EPSG:3857) yield reasonable results for short, straight segments, but accuracy degrades with segment length and curvature.
If a consumer calculates linear references differently than Overture, attribution or connector positions may be misaligned, potentially causing visual discrepancies on rendered maps or routing failures.
Edge cases
For very short segments (under 1 meter), floating-point precision may be limited. Treat at values near 0.0 or 1.0 as equivalent to endpoints. When a connector does not fall exactly on the geometry, the linear reference corresponds to the closest point on the segment.