Edit

Share via

geo_closest_point_on_polygon()

Applies to: ✅ Microsoft Fabric ✅ Azure Data Explorer ✅ Azure Monitor ✅ Microsoft Sentinel

Calculates a point on a polygon or a multipolygon, which is closest to a given point on Earth.

Syntax

geo_closest_point_on_polygon(longitude,latitude,polygon)

Learn more about syntax conventions.

Parameters

Name Type Required Description
longitude real ✔️ Geospatial coordinate, longitude value in degrees. Valid value is a real number and in the range [-180, +180].
latitude real ✔️ Geospatial coordinate, latitude value in degrees. Valid value is a real number and in the range [-90, +90].
polygon dynamic ✔️ Polygon or multipolygon in the GeoJSON format.

Returns

A point in GeoJSON Format and of a dynamic data type on a polygon or multipolygon which is the closest to a given point on Earth. If polygon contains input point, the result with be the same point. If the coordinates or polygons are invalid, the query produces a null result.

Note

  • The geospatial coordinates are interpreted as represented by the WGS-84 coordinate reference system.
  • The geodetic datum used for measurements on Earth is a sphere. Polygon edges are geodesics on the sphere.
  • If input polygon edges are straight cartesian lines, consider using geo_polygon_densify() to convert planar edges to geodesics.
  • In order to calculate a distance between the closest point on a polygon or multipolygon to a given point, use geo_distance_point_to_polygon()

Polygon definition and constraints

dynamic({"type": "Polygon","coordinates": [LinearRingShell, LinearRingHole_1, ..., LinearRingHole_N]})

dynamic({"type": "MultiPolygon","coordinates": [[LinearRingShell, LinearRingHole_1,..., LinearRingHole_N],..., [LinearRingShell, LinearRingHole_1,..., LinearRingHole_M]]})

  • LinearRingShell is required and defined as a counterclockwise ordered array of coordinates [[lng_1,lat_1],...,[lng_i,lat_i],...,[lng_j,lat_j],...,[lng_1,lat_1]]. There can be only one shell.
  • LinearRingHole is optional and defined as a clockwise ordered array of coordinates [[lng_1,lat_1],...,[lng_i,lat_i],...,[lng_j,lat_j],...,[lng_1,lat_1]]. There can be any number of interior rings and holes.
  • LinearRing vertices must be distinct with at least three coordinates. The first coordinate must be equal to the last. At least four entries are required.
  • Coordinates [longitude, latitude] must be valid. Longitude must be a real number in the range [-180, +180] and latitude must be a real number in the range [-90, +90].
  • LinearRingShell encloses at most half of the sphere. LinearRing divides the sphere into two regions. The smaller of the two regions will be chosen.
  • LinearRing edge length must be less than 180 degrees. The shortest edge between the two vertices will be chosen.
  • LinearRings must not cross and must not share edges. LinearRings may share vertices.
  • Polygon doesn't necessarily contain its vertices.

Tip

  • Using literal polygons may result in better performance.

Examples

The following example calculates a ___location in Central Park which is the closest to a given point.

Run the query

let central_park = dynamic({"type":"Polygon","coordinates":[[[-73.9495,40.7969],[-73.95807266235352,40.80068603561921],[-73.98201942443848,40.76825672305777],[-73.97317886352539,40.76455136505513],[-73.9495,40.7969]]]});
print geo_closest_point_on_polygon(-73.9839, 40.7705, central_park)

Output

print_0
{"type": "Point","coordinates": [-73.981205580153926, 40.769359452843211] }

The following example returns a null result because of the invalid coordinate input.

Run the query

print result = isnull(geo_closest_point_on_polygon(500,1,dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,1],[0,0]]]})))

Output

result
true

The following example returns a null result because of the invalid polygon input.

Run the query

print result = isnull(geo_closest_point_on_polygon(1,1,dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,10],[0,0]]]})))

Output

result
true