geo_line_locate_point()

Switch services using the Version drop-down list. Learn more about navigation.
Applies to: ✅ Azure Data Explorer ✅ Azure Monitor ✅ Microsoft Sentinel

Calculates fraction value as a ratio of a line length from line start till a point on a line which is closest to a given point and a whole line length on Earth.

Syntax

geo_line_locate_point(lineString, longitude,latitude,[ use_spheroid ])

Learn more about syntax conventions.

Parameters

Name	Type	Required	Description
lineString	`dynamic`	✔️	A line in the GeoJSON format.
longitude	`real`	✔️	The geospatial coordinate longitude value in degrees. A valid value is in the range [-180, +180].
latitude	`real`	✔️	The geospatial coordinate latitude value in degrees. A valid value is in the range [-90, +90].
use_spheroid	`bool`		If `false` will use a sphere as geodetic datum for measuring distance. If `true` will measure distance using spheroid. If unspecified, the default value `false` is used.

Returns

Line fraction value between 0 and 1 (0 - 100%) as a ratio of a line from start till a point on a line which is closest to a given point and a whole line on Earth. If the line or coordinate value is invalid, the query produces a null result.

Note

The geospatial coordinates are interpreted as represented by the WGS-84 coordinate reference system.
Line segments are geodesics on the sphere, if 'use_spheroid' = false. If 'use_spheroid' = true, line segments will be geodesics on spheroid. Most applications should measure distance using sphere which is more performant
If input line edges are straight cartesian lines, consider using geo_line_densify() in order to convert planar edges to geodesics.
The input shouldn't contain more than a single line string.
If the input line string has more than single point on the line at equal distances from the input point, it isn't guaranteed which one is selected.
In order to calculate a point at fraction on a line use geo_line_interpolate_point()

LineString definition and constraints

dynamic({"type": "LineString","coordinates": [[lng_1,lat_1], [lng_2,lat_2], ..., [lng_N,lat_N]]})

LineString coordinates array must contain at least two entries.
Coordinates [longitude, latitude] must be valid where longitude is a real number in the range [-180, +180] and latitude is a real number in the range [-90, +90].
Edge length must be less than 180 degrees. The shortest edge between the two vertices is chosen.

Examples

The following example calculates a fraction value.

Run the query

let line = dynamic({"type":"LineString","coordinates":[[-73.95796, 40.80042], [-73.97317, 40.764486]]});
print fraction = geo_line_locate_point(line, -73.965, 40.792);

Output

fraction
0.25560135100307552

The following example returns true because of the invalid line.