Geospatial

• 1: geo_angle()
• 2: geo_azimuth()
• 3: geo_distance_2points()
• 4: geo_distance_point_to_line()
• 5: geo_distance_point_to_polygon()
• 6: geo_geohash_neighbors()
• 7: geo_geohash_to_central_point()
• 8: geo_geohash_to_polygon()
• 9: geo_h3cell_children()
• 10: geo_h3cell_level()
• 11: geo_h3cell_neighbors()
• 12: geo_h3cell_parent()
• 13: geo_h3cell_rings()
• 14: geo_h3cell_to_central_point()
• 15: geo_h3cell_to_polygon()
• 16: geo_intersection_2lines()
• 17: geo_intersection_2polygons()
• 18: geo_intersection_line_with_polygon()
• 19: geo_intersects_2lines()
• 20: geo_intersects_2polygons()
• 21: geo_intersects_line_with_polygon()
• 22: geo_line_buffer()
• 23: geo_line_centroid()
• 24: geo_line_densify()
• 25: geo_line_length()
• 26: geo_line_simplify()
• 27: geo_line_to_s2cells()
• 28: geo_point_buffer()
• 29: geo_point_in_circle()
• 30: geo_point_in_polygon()
• 31: geo_point_to_geohash()
• 32: geo_point_to_h3cell()
• 33: geo_point_to_s2cell()
• 34: geo_polygon_area()
• 35: geo_polygon_buffer()
• 36: geo_polygon_centroid()
• 37: geo_polygon_densify()
• 38: geo_polygon_perimeter()
• 39: geo_polygon_simplify()
• 40: geo_polygon_to_h3cells()
• 41: geo_polygon_to_s2cells()
• 42: geo_s2cell_neighbors()
• 43: geo_s2cell_to_central_point()
• 44: geo_s2cell_to_polygon()
• 45: geo_simplify_polygons_array()
• 46: geo_union_lines_array()
• 47: geo_union_polygons_array()
• 48: Geospatial data visualizations
• 49: Geospatial grid system

1 - geo_angle()

Calculates clockwise angle in radians between two lines on Earth. The first line is [point1, point2] and the second line is [point2, point3].

Syntax

geo_angle(p1_longitude,p1_latitude,p2_longitude,p2_latitude,p3_longitude,p3_latitude)

Parameters

Returns

An angle in radians in range [0, 2pi) between two lines [p1, p2] and [p2, p3]. The angle is measured CW from the first line to the Second line.

Examples

The following example calculates the angle in radians.

print angle_in_radians = geo_angle(0, 10, 0,5, 3,-10)

Output

The following example calculates the angle in degrees.

let angle_in_radians = geo_angle(0, 10, 0,5, 3,-10);
print angle_in_degrees = degrees(angle_in_radians)

Output

The following example returns null because 1st point equals to 2nd point.

print is_null = isnull(geo_angle(0, 10, 0, 10, 3, -10))

Output

2 - geo_azimuth()

Calculates clockwise angle in radians between the line from point1 to true north and a line from point1 to point2 on Earth.

Syntax

geo_azimuth(p1_longitude,p1_latitude,p2_longitude,p2_latitude)

Parameters

Returns

An angle in radians between the line from point p1 to true north and line [p1, p2]. The angle is measured clockwise.

Examples

The following example calculates azimuth in radians.

print azimuth_in_radians = geo_azimuth(5, 10, 10, -40)

Output

The following example calculates azimuth in degrees.

let azimuth_in_radians = geo_azimuth(5, 10, 10, -40);
print azimuth_in_degrees = degrees(azimuth_in_radians);

Output

The following example considers a truck that emits telemetry of its location while it travels and looks for its travel direction.

let get_direction = (azimuth:real)
{
    let pi = pi();
    iff(azimuth < pi/2,   "North-East",
    iff(azimuth < pi,     "South-East",
    iff(azimuth < 3*pi/2, "South-West",
                          "North-West")));
};
datatable(timestamp:datetime, lng:real, lat:real)
[
    datetime(2024-01-01T00:01:53.048506Z), -115.4036607693417, 36.40551631046261,
    datetime(2024-01-01T00:02:53.048506Z), -115.3256807623232, 36.34102142760111,
    datetime(2024-01-01T00:03:53.048506Z), -115.2732290602112, 36.28458914829917,
    datetime(2024-01-01T00:04:53.048506Z), -115.2513186233914, 36.27622394664352,
    datetime(2024-01-01T00:05:53.048506Z), -115.2352055633212, 36.27545547038515,
    datetime(2024-01-01T00:06:53.048506Z), -115.1894341934856, 36.28266934431671,
    datetime(2024-01-01T00:07:53.048506Z), -115.1054318118468, 36.28957085435267,
    datetime(2024-01-01T00:08:53.048506Z), -115.0648614339413, 36.28110743285072,
    datetime(2024-01-01T00:09:53.048506Z), -114.9858032867736, 36.29780696509714,
    datetime(2024-01-01T00:10:53.048506Z), -114.9016966527561, 36.36556196813566,
]
| sort by timestamp asc 
| extend prev_lng = prev(lng), prev_lat = prev(lat)
| where isnotnull(prev_lng) and isnotnull(prev_lat)
| extend direction = get_direction(geo_azimuth(prev_lng, prev_lat, lng, lat))
| project direction, lng, lat
| render scatterchart with (kind = map)

Output

The following example returns true because the first point equals the second point.

print is_null = isnull(geo_azimuth(5, 10, 5, 10))

Output

3 - geo_distance_2points()

Calculates the shortest distance in meters between two geospatial coordinates on Earth.

Syntax

geo_distance_2points(p1_longitude,p1_latitude,p2_longitude,p2_latitude)

Parameters

Returns

The shortest distance, in meters, between two geographic locations on Earth. If the coordinates are invalid, the query produces a null result.

Examples

The following example finds the shortest distance between Seattle and Los Angeles.

print distance_in_meters = geo_distance_2points(-122.407628, 47.578557, -118.275287, 34.019056)

Output

The following example finds an approximation of the shortest path from Seattle to London. The line consists of coordinates along the LineString and within 500 meters from it.

range i from 1 to 1000000 step 1
| project lng = rand() * real(-122), lat = rand() * 90
| where lng between(real(-122) .. 0) and lat between(47 .. 90)
| where geo_distance_point_to_line(lng,lat,dynamic({"type":"LineString","coordinates":[[-122,47],[0,51]]})) < 500
| render scatterchart with (kind=map)

Output

The following example finds all rows in which the shortest distance between two coordinates is between one meter and 11 meters.

StormEvents
| extend distance_1_to_11m = geo_distance_2points(BeginLon, BeginLat, EndLon, EndLat)
| where distance_1_to_11m between (1 .. 11)
| project distance_1_to_11m

Output

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

print distance = geo_distance_2points(300,1,1,1)

Output

4 - geo_distance_point_to_line()

Calculates the shortest distance in meters between a coordinate and a line or multiline on Earth.

Syntax

geo_distance_point_to_line(longitude,latitude,lineString)

Parameters

Returns

The shortest distance, in meters, between a coordinate and a line or multiline on Earth. If the coordinate or lineString are invalid, the query produces a null result.

LineString definition and constraints

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2],…, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2, …, line_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

Shortest distance to airport

The following example finds the shortest distance between North Las Vegas Airport and a nearby road.

print distance_in_meters = geo_distance_point_to_line(-115.199625, 36.210419, dynamic({ "type":"LineString","coordinates":[[-115.115385,36.229195],[-115.136995,36.200366],[-115.140252,36.192470],[-115.143558,36.188523],[-115.144076,36.181954],[-115.154662,36.174483],[-115.166431,36.176388],[-115.183289,36.175007],[-115.192612,36.176736],[-115.202485,36.173439],[-115.225355,36.174365]]}))

Output

Storm events across the south coast

The following example finds storm events along the US south coast filtered by a maximum distance of 5 km from the defined shore line.

let southCoast = dynamic({"type":"LineString","coordinates":[[-97.18505859374999,25.997549919572112],[-97.58056640625,26.96124577052697],[-97.119140625,27.955591004642553],[-94.04296874999999,29.726222319395504],[-92.98828125,29.82158272057499],[-89.18701171875,29.11377539511439],[-89.384765625,30.315987718557867],[-87.5830078125,30.221101852485987],[-86.484375,30.4297295750316],[-85.1220703125,29.6880527498568],[-84.00146484374999,30.14512718337613],[-82.6611328125,28.806173508854776],[-82.81494140625,28.033197847676377],[-82.177734375,26.52956523826758],[-80.9912109375,25.20494115356912]]});
StormEvents
| project BeginLon, BeginLat, EventType
| where geo_distance_point_to_line(BeginLon, BeginLat, southCoast) < 5000
| render scatterchart with (kind=map)

Output

New York taxi pickups

The following example finds New York taxi pickups filtered by a maximum distance of 0.1 meters from the defined multiline.

let MadisonAve = dynamic({"type":"MultiLineString","coordinates":[[[-73.9879823,40.7408625],[-73.9876492,40.7413345],[-73.9874982,40.7415046],[-73.9870343,40.7421446],[-73.9865812,40.7427655],[-73.9861292,40.7433756],[-73.9856813,40.7439956],[-73.9854932,40.7442606],[-73.9852232,40.7446216],[-73.9847903,40.7452305],[-73.9846232,40.7454536],[-73.9844803,40.7456606],[-73.9843413,40.7458585],[-73.9839533,40.7463955],[-73.9839002,40.7464696],[-73.9837683,40.7466566],[-73.9834342,40.7471015],[-73.9833833,40.7471746],[-73.9829712,40.7477686],[-73.9824752,40.7484255],[-73.9820262,40.7490436],[-73.9815623,40.7496566],[-73.9811212,40.7502796],[-73.9809762,40.7504976],[-73.9806982,40.7509255],[-73.9802752,40.7515216],[-73.9798033,40.7521795],[-73.9795863,40.7524656],[-73.9793082,40.7528316],[-73.9787872,40.7534725],[-73.9783433,40.7540976],[-73.9778912,40.7547256],[-73.9774213,40.7553365],[-73.9769402,40.7559816],[-73.9764622,40.7565766],[-73.9760073,40.7572036],[-73.9755592,40.7578366],[-73.9751013,40.7584665],[-73.9746532,40.7590866],[-73.9741902,40.7597326],[-73.9737632,40.7603566],[-73.9733032,40.7609866],[-73.9728472,40.7616205],[-73.9723422,40.7622826],[-73.9718672,40.7629556],[-73.9714042,40.7635726],[-73.9709362,40.7642185],[-73.9705282,40.7647636],[-73.9704903,40.7648196],[-73.9703342,40.7650355],[-73.9701562,40.7652826],[-73.9700322,40.7654535],[-73.9695742,40.7660886],[-73.9691232,40.7667166],[-73.9686672,40.7673375],[-73.9682142,40.7679605],[-73.9677482,40.7685786],[-73.9672883,40.7692076],[-73.9668412,40.7698296],[-73.9663882,40.7704605],[-73.9659222,40.7710936],[-73.9654262,40.7717756],[-73.9649292,40.7724595],[-73.9644662,40.7730955],[-73.9640012,40.7737285],[-73.9635382,40.7743615],[-73.9630692,40.7749936],[-73.9626122,40.7756275],[-73.9621172,40.7763106],[-73.9616111,40.7769896],[-73.9611552,40.7776245],[-73.9606891,40.7782625],[-73.9602212,40.7788866],[-73.9597532,40.7795236],[-73.9595842,40.7797445],[-73.9592942,40.7801635],[-73.9591122,40.7804105],[-73.9587982,40.7808305],[-73.9582992,40.7815116],[-73.9578452,40.7821455],[-73.9573802,40.7827706],[-73.9569262,40.7833965],[-73.9564802,40.7840315],[-73.9560102,40.7846486],[-73.9555601,40.7852755],[-73.9551221,40.7859005],[-73.9546752,40.7865426],[-73.9542571,40.7871505],[-73.9541771,40.7872335],[-73.9540892,40.7873366],[-73.9536971,40.7879115],[-73.9532792,40.7884706],[-73.9532142,40.7885205],[-73.9531522,40.7885826],[-73.9527382,40.7891785],[-73.9523081,40.7897545],[-73.9518332,40.7904115],[-73.9513721,40.7910435],[-73.9509082,40.7916695],[-73.9504602,40.7922995],[-73.9499882,40.7929195],[-73.9495051,40.7936045],[-73.9490071,40.7942835],[-73.9485542,40.7949065],[-73.9480832,40.7955345],[-73.9476372,40.7961425],[-73.9471772,40.7967915],[-73.9466841,40.7974475],[-73.9453432,40.7992905],[-73.9448332,40.7999835],[-73.9443442,40.8006565],[-73.9438862,40.8012945],[-73.9434262,40.8019196],[-73.9431412,40.8023325],[-73.9429842,40.8025585],[-73.9425691,40.8031855],[-73.9424401,40.8033609],[-73.9422987,40.8035533],[-73.9422013,40.8036857],[-73.9421022,40.8038205],[-73.9420024,40.8039552],[-73.9416372,40.8044485],[-73.9411562,40.8050725],[-73.9406471,40.8057176],[-73.9401481,40.8064135],[-73.9397022,40.8070255],[-73.9394081,40.8074155],[-73.9392351,40.8076495],[-73.9387842,40.8082715],[-73.9384681,40.8087086],[-73.9383211,40.8089025],[-73.9378792,40.8095215],[-73.9374011,40.8101795],[-73.936405,40.8115707],[-73.9362328,40.8118098]],[[-73.9362328,40.8118098],[-73.9362432,40.8118567],[-73.9361239,40.8120222],[-73.9360302,40.8120805]],[[-73.9362328,40.8118098],[-73.9361571,40.8118294],[-73.9360443,40.8119993],[-73.9360302,40.8120805]],[[-73.9360302,40.8120805],[-73.9359423,40.8121378],[-73.9358551,40.8122385],[-73.9352181,40.8130815],[-73.9348702,40.8135515],[-73.9347541,40.8137145],[-73.9346332,40.8138615],[-73.9345542,40.8139595],[-73.9344981,40.8139945],[-73.9344571,40.8140165],[-73.9343962,40.8140445],[-73.9343642,40.8140585],[-73.9343081,40.8140725],[-73.9341971,40.8140895],[-73.9341041,40.8141005],[-73.9340022,40.8140965],[-73.9338442,40.8141005],[-73.9333712,40.8140895],[-73.9325541,40.8140755],[-73.9324561,40.8140705],[-73.9324022,40.8140695]],[[-73.9360302,40.8120805],[-73.93605,40.8121667],[-73.9359632,40.8122805],[-73.9353631,40.8130795],[-73.9351482,40.8133625],[-73.9350072,40.8135415],[-73.9347441,40.8139168],[-73.9346611,40.8140125],[-73.9346101,40.8140515],[-73.9345401,40.8140965],[-73.9344381,40.8141385],[-73.9343451,40.8141555],[-73.9342991,40.8141675],[-73.9341552,40.8141985],[-73.9338601,40.8141885],[-73.9333991,40.8141815],[-73.9323981,40.8141665]]]});
nyc_taxi
| project pickup_longitude, pickup_latitude
| where geo_distance_point_to_line(pickup_longitude, pickup_latitude, MadisonAve) <= 0.1
| take 100
| render scatterchart with (kind=map)

Output

The following example folds many lines into one multiline and queries this multiline. The query finds all taxi pickups that happened 10 km away from all roads in Manhattan.

let ManhattanRoads =
    datatable(features:dynamic)
    [
        dynamic({"type":"Feature","properties":{"Label":"145thStreetBrg"},"geometry":{"type":"MultiLineString","coordinates":[[[-73.9322259,40.8194635],[-73.9323259,40.8194743],[-73.9323973,40.8194779]]]}}),
        dynamic({"type":"Feature","properties":{"Label":"W120thSt"},"geometry":{"type":"MultiLineString","coordinates":[[[-73.9619541,40.8104844],[-73.9621542,40.8105725],[-73.9630542,40.8109455],[-73.9635902,40.8111714],[-73.9639492,40.8113174],[-73.9640502,40.8113705]]]}}),
        dynamic({"type":"Feature","properties":{"Label":"1stAve"},"geometry":{"type":"MultiLineString","coordinates":[[[-73.9704124,40.748033],[-73.9702043,40.7480906],[-73.9696892,40.7487346],[-73.9695012,40.7491976],[-73.9694522,40.7493196]],[[-73.9699932,40.7488636],[-73.9694522,40.7493196]],[[-73.9694522,40.7493196],[-73.9693113,40.7494946],[-73.9688832,40.7501056],[-73.9686562,40.7504196],[-73.9684231,40.7507476],[-73.9679832,40.7513586],[-73.9678702,40.7514986]],[[-73.9676833,40.7520426],[-73.9675462,40.7522286],[-73.9673532,40.7524976],[-73.9672892,40.7525906],[-73.9672122,40.7526806]]]}})
        // ... more roads ...
    ];
let allRoads=toscalar(
    ManhattanRoads
    | project road_coordinates=features.geometry.coordinates
    | summarize make_list(road_coordinates)
    | project multiline = bag_pack("type","MultiLineString", "coordinates", list_road_coordinates));
nyc_taxi
| project pickup_longitude, pickup_latitude
| where pickup_longitude != 0 and pickup_latitude != 0
| where geo_distance_point_to_line(pickup_longitude, pickup_latitude, parse_json(allRoads)) > 10000
| take 10
| render scatterchart with (kind=map)

Output

Invalid LineString

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

print distance_in_meters = geo_distance_point_to_line(1,1, dynamic({ "type":"LineString"}))

Output

Invalid coordinate

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

print distance_in_meters = geo_distance_point_to_line(300, 3, dynamic({ "type":"LineString","coordinates":[[1,1],[2,2]]}))

Output

5 - geo_distance_point_to_polygon()

Calculates the shortest distance between a coordinate and a polygon or a multipolygon on Earth.

Syntax

geo_distance_point_to_polygon(longitude,latitude,polygon)

Parameters

Returns

The shortest distance, in meters, between a coordinate and a polygon or a multipolygon on Earth. If polygon contains point, the distance will be 0. If the coordinates or polygons are invalid, the query will produce a null result.

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.

Examples

The following example calculates shortest distance in meters from some location in NYC to Central Park.

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_distance_point_to_polygon(-73.9839, 40.7705, central_park)

Output

The following example enriches the data with distance.

let multipolygon = dynamic({"type":"MultiPolygon","coordinates":[[[[-73.991460000000131,40.731738000000206],[-73.992854491775518,40.730082566051351],[-73.996772,40.725432000000154],[-73.997634685522883,40.725786309886963],[-74.002855946639244,40.728346630056791],[-74.001413,40.731065000000207],[-73.996796995070824,40.73736378205173],[-73.991724524037934,40.735245208931886],[-73.990703782359589,40.734781896080477],[-73.991460000000131,40.731738000000206]]],[[[-73.958357552055688,40.800369095633819],[-73.98143901556422,40.768762584141953],[-73.981548752788598,40.7685590292784],[-73.981565335901905,40.768307084720796],[-73.981754418060945,40.768399727738668],[-73.982038573548124,40.768387823012056],[-73.982268248204349,40.768298621883247],[-73.982384797518051,40.768097213086911],[-73.982320919746599,40.767894461792181],[-73.982155532845766,40.767756204474757],[-73.98238873834039,40.767411004834273],[-73.993650353659021,40.772145571634361],[-73.99415893763998,40.772493009137818],[-73.993831082030937,40.772931787850908],[-73.993891252437052,40.772955194876722],[-73.993962585514595,40.772944653908901],[-73.99401262480508,40.772882846631894],[-73.994122058082397,40.77292405902601],[-73.994136652588594,40.772901870174394],[-73.994301342391154,40.772970028663913],[-73.994281535134448,40.77299380206933],[-73.994376552751078,40.77303955110149],[-73.994294029824005,40.773156243992048],[-73.995023275860802,40.773481196576356],[-73.99508939189289,40.773388475039134],[-73.995013963716758,40.773358035426909],[-73.995050284699261,40.773297153189958],[-73.996240651898916,40.773789791397689],[-73.996195837470992,40.773852356184044],[-73.996098807369748,40.773951805299085],[-73.996179459973888,40.773986954351571],[-73.996095245226442,40.774086186437756],[-73.995572265161172,40.773870731394297],[-73.994017424135961,40.77321375261053],[-73.993935876811335,40.773179512586211],[-73.993861942928888,40.773269531698837],[-73.993822393527211,40.773381758622882],[-73.993767019318497,40.773483981224835],[-73.993698463744295,40.773562141052594],[-73.993358326468751,40.773926888327956],[-73.992622663865575,40.774974056037109],[-73.992577842766124,40.774956016359418],[-73.992527743951555,40.775002110439829],[-73.992469745815342,40.775024159551755],[-73.992403837191887,40.775018140390664],[-73.99226708903538,40.775116033858794],[-73.99217809026365,40.775279293897171],[-73.992059084937338,40.775497598192516],[-73.992125372394938,40.775509075053385],[-73.992226867797001,40.775482211026116],[-73.992329346608813,40.775468900958522],[-73.992361756801131,40.775501899766638],[-73.992386042960277,40.775557180424634],[-73.992087684712729,40.775983970821372],[-73.990927174149746,40.777566878763238],[-73.99039616003671,40.777585065679204],[-73.989461267506471,40.778875124584417],[-73.989175778438053,40.779287524015778],[-73.988868617400072,40.779692922911607],[-73.988871874499793,40.779713738253008],[-73.989219022880576,40.779697895209402],[-73.98927785904425,40.779723439271038],[-73.989409054180143,40.779737706471963],[-73.989498614927044,40.779725044389757],[-73.989596493388234,40.779698146683387],[-73.989679812902509,40.779677568658038],[-73.989752702937935,40.779671244211556],[-73.989842247806507,40.779680752670664],[-73.990040102120489,40.779707677698219],[-73.990137977524839,40.779699769704784],[-73.99033584033225,40.779661794394983],[-73.990430598697046,40.779664973055503],[-73.990622199396725,40.779676064914298],[-73.990745069505479,40.779671328184051],[-73.990872114282197,40.779646007643876],[-73.990961672224358,40.779639683751753],[-73.991057472829539,40.779652352625774],[-73.991157429497036,40.779669775606465],[-73.991242817404469,40.779671367084504],[-73.991255318289745,40.779650782516491],[-73.991294887120119,40.779630209208889],[-73.991321967649895,40.779631796041372],[-73.991359455569423,40.779585883337383],[-73.991551059227476,40.779574821437407],[-73.99141982585985,40.779755280287233],[-73.988886144117032,40.779878898532999],[-73.988939656706265,40.779956178440393],[-73.988926103530844,40.780059292013632],[-73.988911680264692,40.780096037146606],[-73.988919261468567,40.780226094343945],[-73.988381050202634,40.780981074045783],[-73.988232413846987,40.781233144215555],[-73.988210420831663,40.781225482542055],[-73.988140000000143,40.781409000000224],[-73.988041288067166,40.781585961353777],[-73.98810029382463,40.781602878305286],[-73.988076449145055,40.781650935001608],[-73.988018059972219,40.781634188810422],[-73.987960792842145,40.781770987031535],[-73.985465811970457,40.785360700575431],[-73.986172704965611,40.786068452258647],[-73.986455862401996,40.785919219081421],[-73.987072345615601,40.785189638820121],[-73.98711901394276,40.785210319004058],[-73.986497781023601,40.785951202887254],[-73.986164628806279,40.786121882448327],[-73.986128422486075,40.786239001331111],[-73.986071135219746,40.786240706026611],[-73.986027274789123,40.786228964236727],[-73.986097637849426,40.78605822569795],[-73.985429321269592,40.785413942184597],[-73.985081137732209,40.785921935110366],[-73.985198833254501,40.785966552197777],[-73.985170502389906,40.78601333415817],[-73.985216218673656,40.786030501816427],[-73.98525509797993,40.785976205511588],[-73.98524273937646,40.785972572653328],[-73.98524962933017,40.785963139855845],[-73.985281779186749,40.785978620950075],[-73.985240032884533,40.786035858136792],[-73.985683885242182,40.786222123919686],[-73.985717529004575,40.786175994668795],[-73.985765660297687,40.786196274858618],[-73.985682871922691,40.786309786213067],[-73.985636270930442,40.786290150649279],[-73.985670722564691,40.786242911993817],[-73.98520511880038,40.786047669212785],[-73.985211035607492,40.786039554883686],[-73.985162639946992,40.786020999769754],[-73.985131636312062,40.786060297019972],[-73.985016964065125,40.78601423719563],[-73.984655078830457,40.786534741807841],[-73.985743787901043,40.786570082854738],[-73.98589227228328,40.786426529019593],[-73.985942854994988,40.786452847880334],[-73.985949561556794,40.78648711396653],[-73.985812373526713,40.786616865357047],[-73.985135209703174,40.78658761889551],[-73.984619428584324,40.786586016349787],[-73.981952458164173,40.790393724337193],[-73.972823037363767,40.803428052816756],[-73.971036786332192,40.805918478839672],[-73.966701,40.804169000000186],[-73.959647,40.801156000000113],[-73.958508540159471,40.800682279767472],[-73.95853274080838,40.800491362464697],[-73.958357552055688,40.800369095633819]]],[[[-73.943592454622546,40.782747908206574],[-73.943648235390199,40.782656161333449],[-73.943870759887162,40.781273026571704],[-73.94345932494096,40.780048275653243],[-73.943213862652243,40.779317588660199],[-73.943004239504688,40.779639495474292],[-73.942716005450905,40.779544169476175],[-73.942712374762181,40.779214856940001],[-73.942535563208608,40.779090956062532],[-73.942893408188027,40.778614093246276],[-73.942438481745029,40.777315235766039],[-73.942244919522594,40.777104088947254],[-73.942074188038887,40.776917846977142],[-73.942002667222781,40.776185317382648],[-73.942620205199006,40.775180871576474],[-73.94285645694552,40.774796600349191],[-73.94293043781397,40.774676268036011],[-73.945870899588215,40.771692257932997],[-73.946618690150586,40.77093339256956],[-73.948664164778933,40.768857624399587],[-73.950069793030679,40.767025088383498],[-73.954418260786071,40.762184104951245],[-73.95650786241211,40.760285256574043],[-73.958787773424007,40.758213471309809],[-73.973015157270069,40.764278692864671],[-73.955760332998182,40.787906554459667],[-73.944023,40.782960000000301],[-73.943592454622546,40.782747908206574]]]]});
let coordinates = 
    datatable(longitude:real, latitude:real, description:string)
    [
        real(-73.9741), 40.7914, 'Upper West Side',
        real(-73.9950), 40.7340, 'Greenwich Village',
        real(-73.8743), 40.7773, 'LaGuardia Airport',
    ];
coordinates
| extend distance = geo_distance_point_to_polygon(longitude, latitude, multipolygon)

Output

The following example finds all states that are within 200-km distance, excluding state that contains the point.

US_States
| project name = features.properties.NAME, polygon = features.geometry
| project name, distance = ceiling(geo_distance_point_to_polygon(-111.905, 40.634, polygon) / 1000)
| where distance < 200 and distance > 0

Output

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

print distance = geo_distance_point_to_polygon(500,1,dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,1],[0,0]]]}))

Output

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

print distance = geo_distance_point_to_polygon(1,1,dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,10],[0,0]]]}))

Output

6 - geo_geohash_neighbors()

Calculates Geohash neighbors.

Read more about geohash.

Syntax

geo_geohash_neighbors(geohash)

Parameters

Returns

An array of Geohash neighbors. If the Geohash is invalid, the query produces a null result.

Examples

The following example calculates Geohash neighbors.

print neighbors = geo_geohash_neighbors('sunny')

Output

The following example calculates an array of input Geohash with its neighbors.

let geohash = 'sunny';
print cells = array_concat(pack_array(geohash), geo_geohash_neighbors(geohash))

Output

The following example calculates Geohash polygons GeoJSON geometry collection.

let geohash = 'sunny';
print cells = array_concat(pack_array(geohash), geo_geohash_neighbors(geohash))
| mv-expand cells to typeof(string)
| project polygons = geo_geohash_to_polygon(cells)
| summarize arr = make_list(polygons)
| project geojson = bag_pack("type", "Feature","geometry", bag_pack("type", "GeometryCollection", "geometries", arr), "properties", bag_pack("name", "polygons"))

Output

The following example calculates polygon unions that represent Geohash and its neighbors.

let h3cell = 'sunny';
print cells = array_concat(pack_array(h3cell), geo_geohash_neighbors(h3cell))
| mv-expand cells to typeof(string)
| project polygons = geo_geohash_to_polygon(cells)
| summarize arr = make_list(polygons)
| project polygon = geo_union_polygons_array(arr)

Output

The following example returns true because of the invalid Geohash token input.

print invalid = isnull(geo_geohash_neighbors('a'))

Output

7 - geo_geohash_to_central_point()

Calculates the geospatial coordinates that represent the center of a geohash rectangular area.

Read more about geohash.

Syntax

geo_geohash_to_central_point(geohash)

Parameters

Returns

The geospatial coordinate values in GeoJSON Format and of a dynamic data type. If the geohash is invalid, the query will produce a null result.

Examples

print point = geo_geohash_to_central_point("sunny")
| extend coordinates = point.coordinates
| extend longitude = coordinates[0], latitude = coordinates[1]

Output

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

print geohash = geo_geohash_to_central_point("a")

Output

Creating location deep-links for Bing Maps

You can use the geohash value to create a deep-link URL to Bing Maps by pointing to the geohash center point:

// Use string concatenation to create Bing Map deep-link URL from a geo-point
let point_to_map_url = (_point:dynamic, _title:string) 
{
    strcat('https://www.bing.com/maps?sp=point.', _point.coordinates[1] ,'_', _point.coordinates[0], '_', url_encode(_title)) 
};
// Convert geohash to center point, and then use 'point_to_map_url' to create Bing Map deep-link
let geohash_to_map_url = (_geohash:string, _title:string)
{
    point_to_map_url(geo_geohash_to_central_point(_geohash), _title)
};
print geohash = 'sv8wzvy7'
| extend url = geohash_to_map_url(geohash, "You are here")

Output

8 - geo_geohash_to_polygon()

Calculates the polygon that represents the geohash rectangular area.

Read more about geohash.

Syntax

geo_geohash_to_polygon(geohash)

Parameters

Returns

Polygon in GeoJSON Format and of a dynamic data type. If the geohash is invalid, the query will produce a null result.

Examples

print GeohashPolygon = geo_geohash_to_polygon("dr5ru");

Output

The following example assembles GeoJSON geometry collection of geohash polygons.

// Geohash GeoJSON collection
datatable(lng:real, lat:real)
[
    -73.975212, 40.789608,
    -73.916869, 40.818314,
    -73.989148, 40.743273,
]
| project geohash = geo_point_to_geohash(lng, lat, 5)
| project geohash_polygon = geo_geohash_to_polygon(geohash)
| summarize geohash_polygon_lst = make_list(geohash_polygon)
| project bag_pack(
    "type", "Feature",
    "geometry", bag_pack("type", "GeometryCollection", "geometries", geohash_polygon_lst),
    "properties", bag_pack("name", "Geohash polygons collection"))

Output

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

print GeohashPolygon = geo_geohash_to_polygon("a");

Output

9 - geo_h3cell_children()

Calculates the H3 cell children.

Read more about H3 Cell.

Syntax

geo_h3cell_children(h3cell,resolution)

Parameters

Returns

Array of H3 Cell children tokens. If the H3 Cell is invalid or child resolution is lower than given cell, the query will produce a null result.

Examples

print children = geo_h3cell_children('862a1072fffffff')

Output

The following example counts children 3 levels below a given cell.

let h3_cell = '862a1072fffffff'; 
print children_count = array_length(geo_h3cell_children(h3_cell, geo_h3cell_level(h3_cell) + 3))

Output

The following example assembles GeoJSON geometry collection of H3 Cell children polygons.

print children = geo_h3cell_children('862a1072fffffff')
| mv-expand children to typeof(string)
| project child = geo_h3cell_to_polygon(children)
| summarize h3_hash_polygon_lst = make_list(child)
| project geojson = bag_pack(
    "type", "Feature",
    "geometry", bag_pack("type", "GeometryCollection", "geometries", h3_hash_polygon_lst),
    "properties", bag_pack("name", "H3 polygons collection"))

Output

The following example returns true because of the invalid cell.

print is_null = isnull(geo_h3cell_children('abc'))

Output

The following example returns true because the level difference between cell and its children is more than 5.

print is_null = isnull(geo_h3cell_children(geo_point_to_h3cell(1, 1, 9), 15))

Output

10 - geo_h3cell_level()

Calculates the H3 cell resolution.

Read more about H3 Cell.

Syntax

geo_h3cell_level(h3cell)

Parameters

Returns

An integer that represents H3 Cell level. Valid level is in range [0, 15]. If the H3 Cell is invalid, the query will produce a null result.

Examples

print cell_res = geo_h3cell_level('862a1072fffffff')

Output

print cell_res = geo_h3cell_level(geo_point_to_h3cell(1,1,10))

Output

The following example returns true because of the invalid H3 Cell token input.

print invalid_res = isnull(geo_h3cell_level('abc'))

Output

11 - geo_h3cell_neighbors()

Calculates the H3 cell neighbors.

Read more about H3 Cell.

Syntax

geo_h3cell_neighbors(h3cell)

Parameters

Returns

An array of H3 cell neighbors. If the H3 Cell is invalid, the query will produce a null result.

Examples

The following example calculates H3 cell neighbors.

print neighbors = geo_h3cell_neighbors('862a1072fffffff')

Output

The following example calculates an array of input H3 cell with its neighbors.

let h3cell = '862a1072fffffff';
print cells = array_concat(pack_array(h3cell), geo_h3cell_neighbors(h3cell))

Output

The following example calculates H3 cells polygons GeoJSON geometry collection.

let h3cell = '862a1072fffffff';
print cells = array_concat(pack_array(h3cell), geo_h3cell_neighbors(h3cell))
| mv-expand cells to typeof(string)
| project polygons = geo_h3cell_to_polygon(cells)
| summarize arr = make_list(polygons)
| project geojson = bag_pack("type", "Feature","geometry", bag_pack("type", "GeometryCollection", "geometries", arr), "properties", bag_pack("name", "polygons"))

Output

The following example calculates polygon unions that represent H3 cell and its neighbors.

let h3cell = '862a1072fffffff';
print cells = array_concat(pack_array(h3cell), geo_h3cell_neighbors(h3cell))
| mv-expand cells to typeof(string)
| project polygons = geo_h3cell_to_polygon(cells)
| summarize arr = make_list(polygons)
| project polygon = geo_union_polygons_array(arr)

Output

The following example returns true because of the invalid H3 Cell token input.

print invalid = isnull(geo_h3cell_neighbors('abc'))

Output

12 - geo_h3cell_parent()

Calculates the H3 cell parent.

Read more about H3 Cell.

Syntax

geo_h3cell_parent(h3cell,resolution)

Parameters

Returns

H3 Cell parent token string. If the H3 Cell is invalid or parent resolution is higher than given cell, the query will produce an empty result.

Examples

print parent_cell = geo_h3cell_parent('862a1072fffffff')

Output

The following example calculates cell parent at level 1.

print parent_cell = geo_h3cell_parent('862a1072fffffff', 1)

Output

print parent_res = geo_h3cell_level(geo_h3cell_parent((geo_point_to_h3cell(1,1,10))))

Output

print parent_res = geo_h3cell_level(geo_h3cell_parent(geo_point_to_h3cell(1,1,10), 3))

Output

The following example produces an empty result because of the invalid cell input.

print invalid = isempty(geo_h3cell_parent('123'))

Output

The following example produces an empty result because of the invalid parent resolution.

print invalid = isempty(geo_h3cell_parent('862a1072fffffff', 100))

Output

The following example produces an empty result because parent can’t be of a higher resolution than child.

print invalid = isempty(geo_h3cell_parent('862a1072fffffff', 15))

Output

13 - geo_h3cell_rings()

Calculates the H3 cell Rings.

Read more about H3 Cell.

Syntax

geo_h3cell_rings(h3cell,distance)

Parameters

Returns

An ordered array of ring arrays where first ring contains the original cell, second ring contains neighboring cells, and so on. If either the H3 Cell or distance is invalid, the query produces a null result.

Examples

The following example produces rings up to distance 2.

print rings = geo_h3cell_rings('861f8894fffffff', 2)

Output

The following example produces all cells at level 1 (all neighbors).

print neighbors = geo_h3cell_rings('861f8894fffffff', 1)[1]

Output

The following example produces list of cells from all rings.

print rings = geo_h3cell_rings('861f8894fffffff', 1)
| mv-apply rings on 
(
  summarize cells = make_list(rings)
)

Output

The following example assembles GeoJSON geometry collection of all cells.

print rings = geo_h3cell_rings('861f8894fffffff', 1)
| mv-apply rings on 
(
  summarize make_list(rings)
)
| mv-expand list_rings to typeof(string)
| project polygon = geo_h3cell_to_polygon(list_rings)
| summarize polygon_lst = make_list(polygon)
| project geojson = bag_pack(
    "type", "Feature",
    "geometry", bag_pack("type", "GeometryCollection", "geometries", polygon_lst),
    "properties", bag_pack("name", "H3 polygons collection"))

Output

The following example returns true because of the invalid cell.

print is_null = isnull(geo_h3cell_rings('abc', 3))

Output

The following example returns true because of the invalid distance.

print is_null = isnull(geo_h3cell_rings('861f8894fffffff', 150))

Output

14 - geo_h3cell_to_central_point()

Calculates the geospatial coordinates that represent the center of an H3 Cell.

Read more about H3 Cell.

Syntax

geo_h3cell_to_central_point(h3cell)

Parameters

Returns

The geospatial coordinate values in GeoJSON Format and of a dynamic data type. If the H3 cell token is invalid, the query will produce a null result.

Examples

print h3cell = geo_h3cell_to_central_point("862a1072fffffff")

Output

The following example returns the longitude of the H3 Cell center point:

print longitude = geo_h3cell_to_central_point("862a1072fffffff").coordinates[0]

Output

The following example returns a null result because of the invalid H3 cell token input.

print h3cell = geo_h3cell_to_central_point("1")

Output

15 - geo_h3cell_to_polygon()

Calculates the polygon that represents the H3 Cell rectangular area.

Read more about H3 Cell.

Syntax

geo_h3cell_to_polygon(h3cell)

Parameters

Returns

Polygon in GeoJSON Format and of a dynamic data type. If the H3 Cell is invalid, the query will produce a null result.

Examples

print geo_h3cell_to_polygon("862a1072fffffff")

Output

The following example assembles GeoJSON geometry collection of H3 Cell polygons.

// H3 cell GeoJSON collection
datatable(lng:real, lat:real)
[
    -73.956683, 40.807907,
    -73.916869, 40.818314,
    -73.989148, 40.743273,
]
| project h3_hash = geo_point_to_h3cell(lng, lat, 6)
| project h3_hash_polygon = geo_h3cell_to_polygon(h3_hash)
| summarize h3_hash_polygon_lst = make_list(h3_hash_polygon)
| project bag_pack(
    "type", "Feature",
    "geometry", bag_pack("type", "GeometryCollection", "geometries", h3_hash_polygon_lst),
    "properties", bag_pack("name", "H3 polygons collection"))

Output

The following example returns a null result because of the invalid H3 Cell token input.

print geo_h3cell_to_polygon("@")

Output

16 - geo_intersection_2lines()

Calculates the intersection of two lines or multilines.

Syntax

geo_intersection_2lines(lineString1,lineString2)

Parameters

Returns

Intersection in GeoJSON Format and of a dynamic data type. If LineString or a MultiLineString are invalid, the query will produce a null result.

LineString definition and constraints

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2],…, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2,…, line_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 will be chosen.

Examples

The following example calculates intersection between two lines. In this case, the result is a point.

let lineString1 = dynamic({"type":"LineString","coordinates":[[-73.978929,40.785155],[-73.980903,40.782621]]});
let lineString2 = dynamic({"type":"LineString","coordinates":[[-73.985195,40.788275],[-73.974552,40.779761]]});
print intersection = geo_intersection_2lines(lineString1, lineString2)

Output

The following example calculates intersection between two lines. In this case, the result is a line.

let line = dynamic({"type":"LineString","coordinates":[[-73.978929,40.785155],[-73.980903,40.782621]]});
print intersection = geo_intersection_2lines(line, line)

Output

The following two lines don’t intersect.

let lineString1 = dynamic({"type":"LineString","coordinates":[[1, 1],[2, 2]]});
let lineString2 = dynamic({"type":"LineString","coordinates":[[3, 3],[4, 4]]});
print intersection = geo_intersection_2lines(lineString1, lineString2)

Output

The following example will return a null result because one of lines is invalid.

let lineString1 = dynamic({"type":"LineString","coordinates":[[1, 1],[2, 2]]});
let lineString2 = dynamic({"type":"LineString","coordinates":[[3, 3]]});
print invalid = isnull(geo_intersection_2lines(lineString1, lineString2))

Output

17 - geo_intersection_2polygons()

Calculates the intersection of two polygons or multipolygons.

Syntax

geo_intersection_2polygons(polygon1,polygon1)

Parameters

Returns

Intersection in GeoJSON Format and of a dynamic data type. If Polygon or a MultiPolygon are invalid, the query will produce a null result.

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 contains its vertices.

Examples

The following example calculates intersection between two polygons. In this case, the result is a polygon.

let polygon1 = dynamic({"type":"Polygon","coordinates":[[[-73.9630937576294,40.77498840732385],[-73.963565826416,40.774383111780914],[-73.96205306053162,40.773745311181585],[-73.96160781383514,40.7743912365898],[-73.9630937576294,40.77498840732385]]]});
let polygon2 = dynamic({"type":"Polygon","coordinates":[[[-73.96213352680206,40.775045280447145],[-73.9631313085556,40.774578106920345],[-73.96207988262177,40.77416780398293],[-73.96213352680206,40.775045280447145]]]});
print intersection = geo_intersection_2polygons(polygon1, polygon2)

Output

The following example calculates intersection between two polygons. In this case, the result is a point.

let polygon1 = dynamic({"type":"Polygon","coordinates":[[[2,45],[0,45],[1,44],[2,45]]]});
let polygon2 = dynamic({"type":"Polygon","coordinates":[[[3,44],[2,45],[2,43],[3,44]]]});
print intersection = geo_intersection_2polygons(polygon1, polygon2)

Output

The following two polygons intersection is a collection.

let polygon1 = dynamic({"type":"Polygon","coordinates":[[[2,45],[0,45],[1,44],[2,45]]]});
let polygon2 = dynamic({"type":"MultiPolygon","coordinates":[[[[3,44],[2,45],[2,43],[3,44]]],[[[1.192,45.265],[1.005,44.943],[1.356,44.937],[1.192,45.265]]]]});
print intersection = geo_intersection_2polygons(polygon1, polygon2)

Output

The following two polygons don’t intersect.

let polygon1 = dynamic({"type":"Polygon","coordinates":[[[2,45],[0,45],[1,44],[2,45]]]});
let polygon2 = dynamic({"type":"Polygon","coordinates":[[[3,44],[3,45],[2,43],[3,44]]]});
print intersection = geo_intersection_2polygons(polygon1, polygon2)

Output

The following example finds all counties in USA that intersect with area of interest polygon.

let area_of_interest = dynamic({"type":"Polygon","coordinates":[[[-73.96213352680206,40.775045280447145],[-73.9631313085556,40.774578106920345],[-73.96207988262177,40.77416780398293],[-73.96213352680206,40.775045280447145]]]});
US_Counties
| project name = features.properties.NAME, county = features.geometry
| project name, intersection = geo_intersection_2polygons(county, area_of_interest)
| where array_length(intersection.geometries) != 0

Output

The following example will return a null result because one of the polygons is invalid.

let central_park_polygon = dynamic({"type":"Polygon","coordinates":[[[-73.9495,40.7969],[-73.95807266235352,40.80068603561921],[-73.98201942443848,40.76825672305777],[-73.97317886352539,40.76455136505513],[-73.9495,40.7969]]]});
let invalid_polygon = dynamic({"type":"Polygon"});
print isnull(geo_intersection_2polygons(invalid_polygon, central_park_polygon))

Output

18 - geo_intersection_line_with_polygon()

Calculates the intersection of a line or a multiline with a polygon or a multipolygon.

Syntax

geo_intersection_line_with_polygon(lineString,polygon)

Parameters

Returns

Intersection in GeoJSON Format and of a dynamic data type. If lineString or a multiLineString or a polygon or a multipolygon are invalid, the query will produce a null result.

LineString definition and constraints

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2], …, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2, …, line_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 will be chosen.

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 contains its vertices.

Examples

The following example calculates intersection between line and polygon. In this case, the result is a line.

let lineString = dynamic({"type":"LineString","coordinates":[[-73.985195,40.788275],[-73.974552,40.779761]]});
let polygon = dynamic({"type":"Polygon","coordinates":[[[-73.9712905883789,40.78580561168767],[-73.98004531860352,40.775276834803655],[-73.97000312805176,40.77852663535664],[-73.9712905883789,40.78580561168767]]]});
print intersection = geo_intersection_line_with_polygon(lineString, polygon)

Output

The following example calculates intersection between line and polygon. In this case, the result is a multiline.

let lineString = dynamic({"type":"LineString","coordinates":[[-110.522, 39.198],[-91.428, 40.880]]});
let polygon = dynamic({"type":"Polygon","coordinates":[[[-90.263,36.738],[-102.041,45.274],[-109.335,36.527],[-90.263,36.738]],[[-100.393,41.705],[-103.139,38.925],[-97.558,39.113],[-100.393,41.705]]]});
print intersection = geo_intersection_line_with_polygon(lineString, polygon)

Output

The following line and polygon don’t intersect.

let lineString = dynamic({"type":"LineString","coordinates":[[1, 1],[2, 2]]});
let polygon = dynamic({"type":"Polygon","coordinates":[[[-73.9712905883789,40.78580561168767],[-73.98004531860352,40.775276834803655],[-73.97000312805176,40.77852663535664],[-73.9712905883789,40.78580561168767]]]});
print intersection = geo_intersection_line_with_polygon(lineString, polygon)

Output

The following example finds all roads in the NYC GeoJSON roads table that intersects with the area of interest literal polygon.

let area_of_interest = dynamic({"type":"Polygon","coordinates":[[[-73.95768642425537,40.80065354924362],[-73.9582872390747,40.80089719667298],[-73.95869493484497,40.80050736035672],[-73.9580512046814,40.80019873831593],[-73.95768642425537,40.80065354924362]]]});
NY_Manhattan_Roads
| project name = features.properties.Label, road = features.geometry
| project name, intersection = geo_intersection_line_with_polygon(road, area_of_interest)
| where array_length(intersection.geometries) != 0

Output

The following example finds all counties in the USA that intersect with area of interest literal LineString.

let area_of_interest = dynamic({"type":"LineString","coordinates":[[-73.97159099578857,40.794513338780895],[-73.96738529205322,40.792758888618756],[-73.96978855133057,40.789769718601505]]});
US_Counties
| project name = features.properties.NAME, county = features.geometry
| project name, intersection = geo_intersection_line_with_polygon(area_of_interest, county)
| where array_length(intersection.geometries) != 0

Output

The following example will return a null result because the LineString is invalid.

let lineString = dynamic({"type":"LineString","coordinates":[[-73.985195,40.788275]]});
let polygon = dynamic({"type":"Polygon","coordinates":[[[-73.95768642425537,40.80065354924362],[-73.9582872390747,40.80089719667298],[-73.95869493484497,40.80050736035672],[-73.9580512046814,40.80019873831593],[-73.95768642425537,40.80065354924362]]]});
print is_invalid = isnull(geo_intersection_2lines(lineString, polygon))

Output

The following example will return a null result because the polygon is invalid.

let lineString = dynamic({"type":"LineString","coordinates":[[-73.97159099578857,40.794513338780895],[-73.96738529205322,40.792758888618756],[-73.96978855133057,40.789769718601505]]});
let polygon = dynamic({"type":"Polygon","coordinates":[]});
print is_invalid = isnull(geo_intersection_2lines(lineString, polygon))

Output

19 - geo_intersects_2lines()

Calculates whether two lines or multilines intersect.

Syntax

geo_intersects_2lines(lineString1,lineString2)

Parameters

Returns

Indicates whether two lines or multilines intersect. If lineString or a multiLineString are invalid, the query will produce a null result.

LineString definition and constraints

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2], …, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2, …, line_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 will be chosen.

Examples

The following example checks whether some two literal lines intersects.

let lineString1 = dynamic({"type":"LineString","coordinates":[[-73.978929,40.785155],[-73.980903,40.782621]]});
let lineString2 = dynamic({"type":"LineString","coordinates":[[-73.985195,40.788275],[-73.974552,40.779761]]});
print intersects = geo_intersects_2lines(lineString1, lineString2)

Output

The following example finds all roads in the NYC GeoJSON roads table that intersects with some lines of interest.

let my_road = dynamic({"type":"LineString","coordinates":[[-73.97892951965332,40.78515573551921],[-73.98090362548828,40.78262115769851]]});
NY_Manhattan_Roads
| project name = features.properties.Label, road = features.geometry
| where geo_intersects_2lines(road, my_road)
| project name

Output

The following example will return a null result because one of lines is invalid.

let lineString1 = dynamic({"type":"LineString","coordinates":[[-73.978929,40.785155],[-73.980903,40.782621]]});
let lineString2 = dynamic({"type":"LineString","coordinates":[[-73.985195,40.788275]]});
print isnull(geo_intersects_2lines(lineString1, lineString2))

Output

20 - geo_intersects_2polygons()

Calculates whether two polygons or multipolygons intersect.

Syntax

geo_intersects_2polygons(polygon1,polygon1)

Parameters

Returns

Indicates whether two polygons or multipolygons intersect. If the Polygon or the MultiPolygon are invalid, the query will produce a null result.

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 contains its vertices.

Examples

The following example checks whether some two literal polygons intersects.

let polygon1 = dynamic({"type":"Polygon","coordinates":[[[-73.9630937576294,40.77498840732385],[-73.963565826416,40.774383111780914],[-73.96205306053162,40.773745311181585],[-73.96160781383514,40.7743912365898],[-73.9630937576294,40.77498840732385]]]});
let polygon2 = dynamic({"type":"Polygon","coordinates":[[[-73.96213352680206,40.775045280447145],[-73.9631313085556,40.774578106920345],[-73.96207988262177,40.77416780398293],[-73.96213352680206,40.775045280447145]]]});
print geo_intersects_2polygons(polygon1, polygon2)

Output

The following example finds all counties in the USA that intersect with area of interest literal polygon.

let area_of_interest = dynamic({"type":"Polygon","coordinates":[[[-73.96213352680206,40.775045280447145],[-73.9631313085556,40.774578106920345],[-73.96207988262177,40.77416780398293],[-73.96213352680206,40.775045280447145]]]});
US_Counties
| project name = features.properties.NAME, county = features.geometry
| where geo_intersects_2polygons(county, area_of_interest)
| project name

Output

The following example will return a null result because one of the polygons is invalid.

let central_park_polygon = dynamic({"type":"Polygon","coordinates":[[[-73.9495,40.7969],[-73.95807266235352,40.80068603561921],[-73.98201942443848,40.76825672305777],[-73.97317886352539,40.76455136505513],[-73.9495,40.7969]]]});
let invalid_polygon = dynamic({"type":"Polygon"});
print isnull(geo_intersects_2polygons(invalid_polygon, central_park_polygon))

Output

21 - geo_intersects_line_with_polygon()

Calculates whether a line or multiline intersect with a polygon or a multipolygon.

Syntax

geo_intersects_line_with_polygon(lineString,polygon)

Parameters

Returns

Indicates whether the line or multiline intersects with polygon or a multipolygon. If lineString or a multiLineString or a polygon or a multipolygon are invalid, the query will produce a null result.

LineString definition and constraints

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2], …, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2, …, line_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 will be chosen.

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.

Examples

The following example checks whether a literal LineString intersects with a Polygon.

let lineString = dynamic({"type":"LineString","coordinates":[[-73.985195,40.788275],[-73.974552,40.779761]]});
let polygon = dynamic({"type":"Polygon","coordinates":[[[-73.9712905883789,40.78580561168767],[-73.98004531860352,40.775276834803655],[-73.97000312805176,40.77852663535664],[-73.9712905883789,40.78580561168767]]]});
print intersects = geo_intersects_line_with_polygon(lineString, polygon)

Output

The following example finds all roads in the NYC GeoJSON roads table that intersect with area of interest literal polygon.

let area_of_interest = dynamic({"type":"Polygon","coordinates":[[[-73.95768642425537,40.80065354924362],[-73.9582872390747,40.80089719667298],[-73.95869493484497,40.80050736035672],[-73.9580512046814,40.80019873831593],[-73.95768642425537,40.80065354924362]]]});
NY_Manhattan_Roads
| project name = features.properties.Label, road = features.geometry
| where geo_intersects_line_with_polygon(road, area_of_interest)
| project name

Output

The following example finds all counties in the USA that intersect with area of interest literal LineString.

let area_of_interest = dynamic({"type":"LineString","coordinates":[[-73.97159099578857,40.794513338780895],[-73.96738529205322,40.792758888618756],[-73.96978855133057,40.789769718601505]]});
US_Counties
| project name = features.properties.NAME, county = features.geometry
| where geo_intersects_line_with_polygon(area_of_interest, county)
| project name

Output

The following example will return a null result because the LineString is invalid.

let lineString = dynamic({"type":"LineString","coordinates":[[-73.985195,40.788275]]});
let polygon = dynamic({"type":"Polygon","coordinates":[[[-73.95768642425537,40.80065354924362],[-73.9582872390747,40.80089719667298],[-73.95869493484497,40.80050736035672],[-73.9580512046814,40.80019873831593],[-73.95768642425537,40.80065354924362]]]});
print isnull(geo_intersects_2lines(lineString, polygon))

Output

The following example will return a null result because the polygon is invalid.

let lineString = dynamic({"type":"LineString","coordinates":[[-73.97159099578857,40.794513338780895],[-73.96738529205322,40.792758888618756],[-73.96978855133057,40.789769718601505]]});
let polygon = dynamic({"type":"Polygon","coordinates":[]});
print isnull(geo_intersects_2lines(lineString, polygon))

Output

22 - geo_line_buffer()

Calculates polygon or multipolygon that contains all points within the given radius of the input line or multiline on Earth.

Syntax

geo_line_buffer(lineString, radius, tolerance)

Parameters

Returns

Polygon or MultiPolygon around the input LineString or MultiLineString. If the coordinates or radius or tolerance is invalid, the query produces a null result.

LineString definition and constraints

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2], …, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2, …, line_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 will be chosen.

Examples

The following query calculates polygon around line, with radius of 4 meters and 0.1 meter tolerance

let line = dynamic({"type":"LineString","coordinates":[[-80.66634997047466,24.894526340592122],[-80.67373241820246,24.890808090321286]]});
print buffer = geo_line_buffer(line, 4, 0.1)

The following query calculates buffer around each line and unifies result

datatable(line:dynamic)
[
    dynamic({"type":"LineString","coordinates":[[14.429214068940496,50.10043066548272],[14.431184174126173,50.10046525983731]]}),
    dynamic({"type":"LineString","coordinates":[[14.43030222687753,50.100780677801936],[14.4303847111523,50.10020274910934]]})
]
| project buffer = geo_line_buffer(line, 2, 0.1)
| summarize polygons = make_list(buffer)
| project result = geo_union_polygons_array(polygons)

The following example will return true, due to invalid line.

print buffer = isnull(geo_line_buffer(dynamic({"type":"LineString"}), 5))

The following example will return true, due to invalid radius.

print buffer = isnull(geo_line_buffer(dynamic({"type":"LineString","coordinates":[[0,0],[1,1]]}), 0))

23 - geo_line_centroid()

Calculates the centroid of a line or a multiline on Earth.

Syntax

geo_line_centroid(lineString)

Parameters

Returns

The centroid coordinate values in GeoJSON Format and of a dynamic data type. If the line or the multiline is invalid, the query produces a null result.

LineString definition and constraints

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2], …, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2, …, line_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 line centroid.

let line = dynamic({"type":"LineString","coordinates":[[-73.95796, 40.80042], [-73.97317, 40.764486]]});
print centroid = geo_line_centroid(line);

Output

The following example calculates line centroid longitude.

let line = dynamic({"type":"LineString","coordinates":[[-73.95807266235352,40.800426144169315],[-73.94966125488281,40.79691751000055],[-73.97317886352539,40.764486356930334],[-73.98210525512695,40.76786669510221],[-73.96004676818848,40.7980870753293]]});
print centroid = geo_line_centroid(line)
| project lng = centroid.coordinates[0]

Output

The following example visualizes line centroid on a map.

let line = dynamic({"type":"MultiLineString","coordinates":[[[-73.95798683166502,40.800556090021466],[-73.98193359375,40.76819171855746]],[[-73.94940376281738,40.79691751000055],[-73.97317886352539,40.76435634049001]]]});
print centroid = geo_line_centroid(line)
| render scatterchart with (kind = map)

The following example returns true because of the invalid line.

print is_bad_line = isnull(geo_line_centroid(dynamic({"type":"LineString","coordinates":[[1, 1]]})))

Output

24 - geo_line_densify()

Converts planar lines or multiline edges to geodesics by adding intermediate points.

Syntax

geo_line_densify(lineString, tolerance, [ preserve_crossing ])

Parameters

Returns

Densified line in the GeoJSON format and of a dynamic data type. If either the line or tolerance is invalid, the query will produce a null result.

LineString definition

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2], …, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2, …, line_N]]})

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

Constraints

• The maximum number of points in the densified line is limited to 10485760.
• Storing lines in dynamic format has size limits.

Motivation

• GeoJSON format defines an edge between two points as a straight cartesian line while geo_line_densify() uses geodesic.
• The decision to use geodesic or planar edges might depend on the dataset and is especially relevant in long edges.

Examples

The following example densifies a road in Manhattan island. The edge is short and the distance between the planar edge and its geodesic counterpart is less than the distance specified by tolerance. As such, the result remains unchanged.

print densified_line = tostring(geo_line_densify(dynamic({"type":"LineString","coordinates":[[-73.949247, 40.796860],[-73.973017, 40.764323]]})))

Output

The following example densifies an edge of ~130-km length

print densified_line = tostring(geo_line_densify(dynamic({"type":"LineString","coordinates":[[50, 50], [51, 51]]})))

Output

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

print densified_line = geo_line_densify(dynamic({"type":"LineString","coordinates":[[300,1],[1,1]]}))

Output

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

print densified_line = geo_line_densify(dynamic({"type":"LineString","coordinates":[[1,1],[2,2]]}), 0)

Output

25 - geo_line_length()

Calculates the total length of a line or a multiline on Earth.

Syntax

geo_line_length(lineString)

Parameters

Returns

The total length of a line or a multiline, in meters, on Earth. If the line or multiline is invalid, the query will produce a null result.

LineString definition and constraints

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2], …, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2, …, line_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 will be chosen.

Examples

The following example calculates the total line length, in meters.

let line = dynamic({"type":"LineString","coordinates":[[-73.95807266235352,40.800426144169315],[-73.94966125488281,40.79691751000055],[-73.97317886352539,40.764486356930334]]});
print length = geo_line_length(line)

Output

The following example calculates total multiline length, in meters.

let line = dynamic({"type":"MultiLineString","coordinates":[[[-73.95798683166502,40.800556090021466],[-73.98193359375,40.76819171855746]],[[-73.94940376281738,40.79691751000055],[-73.97317886352539,40.76435634049001]]]});
print length = geo_line_length(line)

Output

The following example returns True because of the invalid line.

print is_bad_line = isnull(geo_line_length(dynamic({"type":"LineString","coordinates":[[1, 1]]})))

Output

26 - geo_line_simplify()

Simplifies a line or a multiline by replacing nearly straight chains of short edges with a single long edge on Earth.

Syntax

geo_line_simplify(lineString, tolerance)

Parameters

Returns

Simplified line or a multiline in the GeoJSON format and of a dynamic data type, with no two vertices with distance less than tolerance. If either the line or tolerance is invalid, the query will produce a null result.

LineString definition and constraints

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2], …, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2, …, line_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 will be chosen.

Examples

The following example simplifies the line by removing vertices that are within a 10-meter distance from each other.

let line = dynamic({"type":"LineString","coordinates":[[-73.97033169865608,40.789063020152824],[-73.97039607167244,40.78897975920816],[-73.9704617857933,40.78888837512432],[-73.97052884101868,40.7887949601531],[-73.9706052839756,40.788698498903564],[-73.97065222263336,40.78862640672032],[-73.97072866559029,40.78852791445617],[-73.97079303860664,40.788434498977836]]});
print simplified = geo_line_simplify(line, 10)

Output

The following example simplifies lines and combines results into GeoJSON geometry collection.

NY_Manhattan_Roads
| project road = features.geometry
| project road_simplified = geo_line_simplify(road, 100)
| summarize roads_lst = make_list(road_simplified)
| project geojson = bag_pack("type", "Feature","geometry", bag_pack("type", "GeometryCollection", "geometries", roads_lst), "properties", bag_pack("name", "roads"))

Output

The following example simplifies lines and unifies result

NY_Manhattan_Roads
| project road = features.geometry
| project road_simplified = geo_line_simplify(road, 100)
| summarize roads_lst = make_list(road_simplified)
| project roads = geo_union_lines_array(roads_lst)

Output

The following example returns True because of the invalid line.

print is_invalid_line = isnull(geo_line_simplify(dynamic({"type":"LineString","coordinates":[[1, 1]]})))

Output

The following example returns True because of the invalid tolerance.

print is_invalid_line = isnull(geo_line_simplify(dynamic({"type":"LineString","coordinates":[[1, 1],[2,2]]}), -1))

Output

The following example returns True because high tolerance causes small line to disappear.

print is_invalid_line = isnull(geo_line_simplify(dynamic({"type":"LineString","coordinates":[[1.1, 1.1],[1.2,1.2]]}), 100000))

Output

27 - geo_line_to_s2cells()

Calculates S2 cell tokens that cover a line or multiline on Earth. This function is a useful geospatial join tool.

Read more about S2 cell hierarchy.

Syntax

geo_line_to_s2cells(lineString [, level[ , radius]])

Parameters

Returns

Array of S2 cell token strings that cover a line or a multiline. If the radius is set to a positive value, then the covering will be of both input shape and all points within the radius of the input geometry.

If any of the following: line, level, radius is invalid, or the cell count exceeds the limit, the query will produce a null result.

Choosing the S2 cell level

• Ideally we would want to cover every line with one or just a few unique cells such that no two lines share the same cell.
• In practice, try covering with just a few cells, no more than a dozen. Covering with more than 10,000 cells might not yield good performance.
• Query run time and memory consumption might differ greatly because of different S2 cell level values.

Performance improvement suggestions

• If possible, reduce lines count due to nature of the data or business needs. Filter out unnecessary lines before join, scope to the area of interest or unify lines.
• In case of very big lines, reduce their size using geo_line_simplify().
• Changing S2 cell level may improve performance and memory consumption.
• Changing join kind and hint may improve performance and memory consumption.
• In case positive radius is set, reverting to radius 0 on buffered shape using geo_line_buffer() may improve performance.

Examples

The following query finds all tube stations within 500 meters of streets and aggregates tubes count by street name.

let radius = 500;
let tube_stations = datatable(tube_station_name:string, lng:real, lat: real)
[
    "St. James' Park",        -0.13451078568013486, 51.49919145858172,
     "London Bridge station", -0.08492752160134387, 51.504876316440914,
     // more points
];
let streets = datatable(street_name:string, line:dynamic)
[
    "Buckingham Palace", dynamic({"type":"LineString","coordinates":[[-0.1399656708283601,51.50190802248855],[-0.14088438832752104,51.50012082761452]]}),
    "London Bridge",    dynamic({"type":"LineString","coordinates":[[-0.087152,51.509596],[-0.088340,51.506110]]}),
    // more lines
];
let join_level = 14;
let lines = materialize(streets | extend id = new_guid());
let res = 
    lines
    | project id, covering = geo_line_to_s2cells(line, join_level, radius)
    | mv-expand covering to typeof(string)
    | join kind=inner hint.strategy=broadcast
    (
        tube_stations
        | extend covering = geo_point_to_s2cell(lng, lat, join_level)
    ) on covering;
res | lookup lines on id
| where geo_distance_point_to_line(lng, lat, line) <= radius
| summarize count = count() by name = street_name

In case of invalid line, a null result will be returned.

let line = dynamic({"type":"LineString","coordinates":[[[0,0],[0,0]]]});
print isnull(geo_line_to_s2cells(line))

28 - geo_point_buffer()

Calculates polygon that contains all points within the given radius of the point on Earth.

Syntax

geo_point_buffer(longitude, latitude, radius, tolerance)

Parameters

Returns

Polygon around the input point. If the coordinates or radius or tolerance is invalid, the query produces a null result.

Examples

The following query calculates polygon around [-115.1745008278, 36.1497251277] coordinates, with 20km radius.

print buffer = geo_point_buffer(-115.1745008278, 36.1497251277, 20000)

The following query calculates buffer around each point and unifies result

datatable(longitude:real, latitude:real, radius:real)
[
    real(-80.3212217992616), 25.268683367546604, 5000,
    real(-80.81717403605833), 24.82658441221962, 3000
]
| project buffer = geo_point_buffer(longitude, latitude, radius)
| summarize polygons = make_list(buffer)
| project result = geo_union_polygons_array(polygons)

The following example returns true, due to invalid point.

print result = isnull(geo_point_buffer(200, 1,0.1))

The following example returns true, due to invalid radius.

print result = isnull(geo_point_buffer(10, 10, -1))

29 - geo_point_in_circle()

Calculates whether the geospatial coordinates are inside a circle on Earth.

Syntax

geo_point_in_circle(p_longitude, p_latitude, pc_longitude, pc_latitude, c_radius)

Parameters

Returns

Indicates whether the geospatial coordinates are inside a circle. If the coordinates or circle is invalid, the query produces a null result.

Examples

The following example finds all the places in the area defined by the following circle: Radius of 18 km, center at [-122.317404, 47.609119] coordinates.

datatable(longitude:real, latitude:real, place:string)
[
    real(-122.317404), 47.609119, 'Seattle',                   // In circle 
    real(-123.497688), 47.458098, 'Olympic National Forest',   // In exterior of circle  
    real(-122.201741), 47.677084, 'Kirkland',                  // In circle
    real(-122.443663), 47.247092, 'Tacoma',                    // In exterior of circle
    real(-122.121975), 47.671345, 'Redmond',                   // In circle
]
| where geo_point_in_circle(longitude, latitude, -122.317404, 47.609119, 18000)
| project place

Output

The following example finds storm events in Orlando. The events are filtered by 100 km within Orlando coordinates, and aggregated by event type and hash.

StormEvents
| project BeginLon, BeginLat, EventType
| where geo_point_in_circle(BeginLon, BeginLat, real(-81.3891), 28.5346, 1000 * 100)
| summarize count() by EventType, hash = geo_point_to_s2cell(BeginLon, BeginLat)
| project geo_s2cell_to_central_point(hash), EventType, count_
| render piechart with (kind=map) // map pie rendering available in Kusto Explorer desktop

Output

The following example shows New York city taxi pickups within 10 meters of a particular location. Relevant pickups are aggregated by hash.

nyc_taxi
| project pickup_longitude, pickup_latitude
| where geo_point_in_circle( pickup_longitude, pickup_latitude, real(-73.9928), 40.7429, 10)
| summarize by hash = geo_point_to_s2cell(pickup_longitude, pickup_latitude, 22)
| project geo_s2cell_to_central_point(hash)
| render scatterchart with (kind = map)

Output

The following example returns true.

print in_circle = geo_point_in_circle(-122.143564, 47.535677, -122.100896, 47.527351, 3500)

Output

The following example returns false.

print in_circle = geo_point_in_circle(-122.137575, 47.630683, -122.100896, 47.527351, 3500)

Output

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

print in_circle = geo_point_in_circle(200, 1, 1, 1, 1)

Output

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

print in_circle = geo_point_in_circle(1, 1, 1, 1, -1)

Output

30 - geo_point_in_polygon()

Calculates whether the geospatial coordinates are inside a polygon or a multipolygon on Earth.

Syntax

geo_point_in_polygon(longitude, latitude, polygon)

Parameters

Returns

Indicates whether the geospatial coordinates are inside a polygon. If the coordinates or polygon is invalid, the query produces a null result.

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, is chosen.
• LinearRing edge length must be less than 180 degrees. The shortest edge between the two vertices is chosen.
• LinearRings must not cross and must not share edges. LinearRings might share vertices.
• Polygon doesn’t necessarily contain its vertices. Point containment in polygon is defined so that if the Earth is subdivided into polygons, every point is contained by exactly one polygon.

Examples

The following example finds locations which fall within Manhattan island, excluding the area of Central Park.

datatable(longitude:real, latitude:real, description:string)
[
    real(-73.985654), 40.748487, 'Empire State Building',           // In Polygon 
    real(-73.963249), 40.779525, 'The Metropolitan Museum of Art',  // In exterior of polygon
    real(-73.874367), 40.777356, 'LaGuardia Airport',               // In exterior of polygon
]
| where geo_point_in_polygon(longitude, latitude, dynamic({"type":"Polygon","coordinates":[[[-73.92597198486328,40.87821814104651],[-73.94691467285156,40.85069618625578],[-73.94691467285156,40.841865966890786],[-74.01008605957031,40.7519385984599],[-74.01866912841797,40.704586878965245],[-74.01214599609375,40.699901911003046],[-73.99772644042969,40.70875101828792],[-73.97747039794922,40.71083299030839],[-73.97026062011719,40.7290474687069],[-73.97506713867186,40.734510840309376],[-73.970947265625,40.74543623770158],[-73.94210815429688,40.77586181063573],[-73.9434814453125,40.78080140115127],[-73.92974853515625,40.79691751000055],[-73.93077850341797,40.804454347291006],[-73.93489837646484,40.80965166748853],[-73.93524169921875,40.837190668541105],[-73.92288208007812,40.85770758108904],[-73.9101791381836,40.871728144624974],[-73.92597198486328,40.87821814104651]],[[-73.95824432373047,40.80071852197889],[-73.98206233978271,40.76815921628347],[-73.97309303283691,40.76422632379533],[-73.94914627075195,40.796949998204596],[-73.95824432373047,40.80071852197889]]]}))

Output

The following example searches for coordinates in a multipolygon.

let multipolygon = dynamic({"type":"MultiPolygon","coordinates":[[[[-73.991460000000131,40.731738000000206],[-73.992854491775518,40.730082566051351],[-73.996772,40.725432000000154],[-73.997634685522883,40.725786309886963],[-74.002855946639244,40.728346630056791],[-74.001413,40.731065000000207],[-73.996796995070824,40.73736378205173],[-73.991724524037934,40.735245208931886],[-73.990703782359589,40.734781896080477],[-73.991460000000131,40.731738000000206]]],[[[-73.958357552055688,40.800369095633819],[-73.98143901556422,40.768762584141953],[-73.981548752788598,40.7685590292784],[-73.981565335901905,40.768307084720796],[-73.981754418060945,40.768399727738668],[-73.982038573548124,40.768387823012056],[-73.982268248204349,40.768298621883247],[-73.982384797518051,40.768097213086911],[-73.982320919746599,40.767894461792181],[-73.982155532845766,40.767756204474757],[-73.98238873834039,40.767411004834273],[-73.993650353659021,40.772145571634361],[-73.99415893763998,40.772493009137818],[-73.993831082030937,40.772931787850908],[-73.993891252437052,40.772955194876722],[-73.993962585514595,40.772944653908901],[-73.99401262480508,40.772882846631894],[-73.994122058082397,40.77292405902601],[-73.994136652588594,40.772901870174394],[-73.994301342391154,40.772970028663913],[-73.994281535134448,40.77299380206933],[-73.994376552751078,40.77303955110149],[-73.994294029824005,40.773156243992048],[-73.995023275860802,40.773481196576356],[-73.99508939189289,40.773388475039134],[-73.995013963716758,40.773358035426909],[-73.995050284699261,40.773297153189958],[-73.996240651898916,40.773789791397689],[-73.996195837470992,40.773852356184044],[-73.996098807369748,40.773951805299085],[-73.996179459973888,40.773986954351571],[-73.996095245226442,40.774086186437756],[-73.995572265161172,40.773870731394297],[-73.994017424135961,40.77321375261053],[-73.993935876811335,40.773179512586211],[-73.993861942928888,40.773269531698837],[-73.993822393527211,40.773381758622882],[-73.993767019318497,40.773483981224835],[-73.993698463744295,40.773562141052594],[-73.993358326468751,40.773926888327956],[-73.992622663865575,40.774974056037109],[-73.992577842766124,40.774956016359418],[-73.992527743951555,40.775002110439829],[-73.992469745815342,40.775024159551755],[-73.992403837191887,40.775018140390664],[-73.99226708903538,40.775116033858794],[-73.99217809026365,40.775279293897171],[-73.992059084937338,40.775497598192516],[-73.992125372394938,40.775509075053385],[-73.992226867797001,40.775482211026116],[-73.992329346608813,40.775468900958522],[-73.992361756801131,40.775501899766638],[-73.992386042960277,40.775557180424634],[-73.992087684712729,40.775983970821372],[-73.990927174149746,40.777566878763238],[-73.99039616003671,40.777585065679204],[-73.989461267506471,40.778875124584417],[-73.989175778438053,40.779287524015778],[-73.988868617400072,40.779692922911607],[-73.988871874499793,40.779713738253008],[-73.989219022880576,40.779697895209402],[-73.98927785904425,40.779723439271038],[-73.989409054180143,40.779737706471963],[-73.989498614927044,40.779725044389757],[-73.989596493388234,40.779698146683387],[-73.989679812902509,40.779677568658038],[-73.989752702937935,40.779671244211556],[-73.989842247806507,40.779680752670664],[-73.990040102120489,40.779707677698219],[-73.990137977524839,40.779699769704784],[-73.99033584033225,40.779661794394983],[-73.990430598697046,40.779664973055503],[-73.990622199396725,40.779676064914298],[-73.990745069505479,40.779671328184051],[-73.990872114282197,40.779646007643876],[-73.990961672224358,40.779639683751753],[-73.991057472829539,40.779652352625774],[-73.991157429497036,40.779669775606465],[-73.991242817404469,40.779671367084504],[-73.991255318289745,40.779650782516491],[-73.991294887120119,40.779630209208889],[-73.991321967649895,40.779631796041372],[-73.991359455569423,40.779585883337383],[-73.991551059227476,40.779574821437407],[-73.99141982585985,40.779755280287233],[-73.988886144117032,40.779878898532999],[-73.988939656706265,40.779956178440393],[-73.988926103530844,40.780059292013632],[-73.988911680264692,40.780096037146606],[-73.988919261468567,40.780226094343945],[-73.988381050202634,40.780981074045783],[-73.988232413846987,40.781233144215555],[-73.988210420831663,40.781225482542055],[-73.988140000000143,40.781409000000224],[-73.988041288067166,40.781585961353777],[-73.98810029382463,40.781602878305286],[-73.988076449145055,40.781650935001608],[-73.988018059972219,40.781634188810422],[-73.987960792842145,40.781770987031535],[-73.985465811970457,40.785360700575431],[-73.986172704965611,40.786068452258647],[-73.986455862401996,40.785919219081421],[-73.987072345615601,40.785189638820121],[-73.98711901394276,40.785210319004058],[-73.986497781023601,40.785951202887254],[-73.986164628806279,40.786121882448327],[-73.986128422486075,40.786239001331111],[-73.986071135219746,40.786240706026611],[-73.986027274789123,40.786228964236727],[-73.986097637849426,40.78605822569795],[-73.985429321269592,40.785413942184597],[-73.985081137732209,40.785921935110366],[-73.985198833254501,40.785966552197777],[-73.985170502389906,40.78601333415817],[-73.985216218673656,40.786030501816427],[-73.98525509797993,40.785976205511588],[-73.98524273937646,40.785972572653328],[-73.98524962933017,40.785963139855845],[-73.985281779186749,40.785978620950075],[-73.985240032884533,40.786035858136792],[-73.985683885242182,40.786222123919686],[-73.985717529004575,40.786175994668795],[-73.985765660297687,40.786196274858618],[-73.985682871922691,40.786309786213067],[-73.985636270930442,40.786290150649279],[-73.985670722564691,40.786242911993817],[-73.98520511880038,40.786047669212785],[-73.985211035607492,40.786039554883686],[-73.985162639946992,40.786020999769754],[-73.985131636312062,40.786060297019972],[-73.985016964065125,40.78601423719563],[-73.984655078830457,40.786534741807841],[-73.985743787901043,40.786570082854738],[-73.98589227228328,40.786426529019593],[-73.985942854994988,40.786452847880334],[-73.985949561556794,40.78648711396653],[-73.985812373526713,40.786616865357047],[-73.985135209703174,40.78658761889551],[-73.984619428584324,40.786586016349787],[-73.981952458164173,40.790393724337193],[-73.972823037363767,40.803428052816756],[-73.971036786332192,40.805918478839672],[-73.966701,40.804169000000186],[-73.959647,40.801156000000113],[-73.958508540159471,40.800682279767472],[-73.95853274080838,40.800491362464697],[-73.958357552055688,40.800369095633819]]],[[[-73.943592454622546,40.782747908206574],[-73.943648235390199,40.782656161333449],[-73.943870759887162,40.781273026571704],[-73.94345932494096,40.780048275653243],[-73.943213862652243,40.779317588660199],[-73.943004239504688,40.779639495474292],[-73.942716005450905,40.779544169476175],[-73.942712374762181,40.779214856940001],[-73.942535563208608,40.779090956062532],[-73.942893408188027,40.778614093246276],[-73.942438481745029,40.777315235766039],[-73.942244919522594,40.777104088947254],[-73.942074188038887,40.776917846977142],[-73.942002667222781,40.776185317382648],[-73.942620205199006,40.775180871576474],[-73.94285645694552,40.774796600349191],[-73.94293043781397,40.774676268036011],[-73.945870899588215,40.771692257932997],[-73.946618690150586,40.77093339256956],[-73.948664164778933,40.768857624399587],[-73.950069793030679,40.767025088383498],[-73.954418260786071,40.762184104951245],[-73.95650786241211,40.760285256574043],[-73.958787773424007,40.758213471309809],[-73.973015157270069,40.764278692864671],[-73.955760332998182,40.787906554459667],[-73.944023,40.782960000000301],[-73.943592454622546,40.782747908206574]]]]});
let coordinates = 
    datatable(longitude:real, latitude:real, description:string)
    [
        real(-73.9741), 40.7914, 'Upper West Side',    // In MultiPolygon
        real(-73.9950), 40.7340, 'Greenwich Village',  // In MultiPolygon
        real(-73.8743), 40.7773, 'LaGuardia Airport',  // In exterior of MultiPolygon
    ];
coordinates
| where geo_point_in_polygon(longitude, latitude, multipolygon)

Output

The following example finds storm events in California. The events are filtered by a California state polygon and aggregated by event type and hash.

let california = dynamic({"type":"Polygon","coordinates":[[[-123.233256,42.006186],[-122.378853,42.011663],[-121.037003,41.995232],[-120.001861,41.995232],[-119.996384,40.264519],[-120.001861,38.999346],[-118.71478,38.101128],[-117.498899,37.21934],[-116.540435,36.501861],[-115.85034,35.970598],[-114.634459,35.00118],[-114.634459,34.87521],[-114.470151,34.710902],[-114.333228,34.448009],[-114.136058,34.305608],[-114.256551,34.174162],[-114.415382,34.108438],[-114.535874,33.933176],[-114.497536,33.697668],[-114.524921,33.54979],[-114.727567,33.40739],[-114.661844,33.034958],[-114.524921,33.029481],[-114.470151,32.843265],[-114.524921,32.755634],[-114.72209,32.717295],[-116.04751,32.624187],[-117.126467,32.536556],[-117.24696,32.668003],[-117.252437,32.876127],[-117.329114,33.122589],[-117.471515,33.297851],[-117.7837,33.538836],[-118.183517,33.763391],[-118.260194,33.703145],[-118.413548,33.741483],[-118.391641,33.840068],[-118.566903,34.042715],[-118.802411,33.998899],[-119.218659,34.146777],[-119.278905,34.26727],[-119.558229,34.415147],[-119.875891,34.40967],[-120.138784,34.475393],[-120.472878,34.448009],[-120.64814,34.579455],[-120.609801,34.858779],[-120.670048,34.902595],[-120.631709,35.099764],[-120.894602,35.247642],[-120.905556,35.450289],[-121.004141,35.461243],[-121.168449,35.636505],[-121.283465,35.674843],[-121.332757,35.784382],[-121.716143,36.195153],[-121.896882,36.315645],[-121.935221,36.638785],[-121.858544,36.6114],[-121.787344,36.803093],[-121.929744,36.978355],[-122.105006,36.956447],[-122.335038,37.115279],[-122.417192,37.241248],[-122.400761,37.361741],[-122.515777,37.520572],[-122.515777,37.783465],[-122.329561,37.783465],[-122.406238,38.15042],[-122.488392,38.112082],[-122.504823,37.931343],[-122.701993,37.893004],[-122.937501,38.029928],[-122.97584,38.265436],[-123.129194,38.451652],[-123.331841,38.566668],[-123.44138,38.698114],[-123.737134,38.95553],[-123.687842,39.032208],[-123.824765,39.366301],[-123.764519,39.552517],[-123.85215,39.831841],[-124.109566,40.105688],[-124.361506,40.259042],[-124.410798,40.439781],[-124.158859,40.877937],[-124.109566,41.025814],[-124.158859,41.14083],[-124.065751,41.442061],[-124.147905,41.715908],[-124.257444,41.781632],[-124.213628,42.000709],[-123.233256,42.006186]]]});
StormEvents
| project BeginLon, BeginLat, EventType
| where geo_point_in_polygon(BeginLon, BeginLat, california)
| summarize count() by EventType, hash = geo_point_to_s2cell(BeginLon, BeginLat, 7)
| project geo_s2cell_to_central_point(hash), EventType, count_
| render piechart with (kind=map) // map rendering available in Kusto Explorer desktop

Output

The following example shows how to classify coordinates to polygons using the partition operator.

let Polygons = datatable(description:string, polygon:dynamic)
    [  
      "New York city area", dynamic({"type":"Polygon","coordinates":[[[-73.85009765625,40.85744791303121],[-74.16046142578125,40.84290487729676],[-74.190673828125,40.59935608796518],[-73.83087158203125,40.61812224225511],[-73.85009765625,40.85744791303121]]]}),
      "Seattle area",       dynamic({"type":"Polygon","coordinates":[[[-122.200927734375,47.68573021131587],[-122.4591064453125,47.68573021131587],[-122.4755859375,47.468949677672484],[-122.17620849609374,47.47266286861342],[-122.200927734375,47.68573021131587]]]}),
      "Las Vegas",          dynamic({"type":"Polygon","coordinates":[[[-114.9,36.36],[-115.4498291015625,36.33282808737917],[-115.4498291015625,35.84453450421662],[-114.949951171875,35.902399875143615],[-114.9,36.36]]]}),
    ];
let Locations = datatable(longitude:real, latitude:real)
    [
      real(-73.95),  real(40.75), // Somewhere in New York
      real(-122.3),  real(47.6),  // Somewhere in Seattle
      real(-115.18), real(36.16)  // Somewhere in Las Vegas
    ];
Polygons
| project polygonPartition = tostring(pack("description", description, "polygon", polygon))
| partition hint.materialized=true hint.strategy=native by polygonPartition
{   
     Locations
     | extend description = parse_json(toscalar(polygonPartition)).description
     | extend polygon = parse_json(toscalar(polygonPartition)).polygon
     | where geo_point_in_polygon(longitude, latitude, polygon)
     | project-away polygon
}

Output

See also geo_polygon_to_s2cells().

The following example folds several polygons into one multipolygon and checks locations that fall within the multipolygon.

let Polygons = 
    datatable(polygon:dynamic)
    [
        dynamic({"type":"Polygon","coordinates":[[[-73.991460000000131,40.731738000000206],[-73.992854491775518,40.730082566051351],[-73.996772,40.725432000000154],[-73.997634685522883,40.725786309886963],[-74.002855946639244,40.728346630056791],[-74.001413,40.731065000000207],[-73.996796995070824,40.73736378205173],[-73.991724524037934,40.735245208931886],[-73.990703782359589,40.734781896080477],[-73.991460000000131,40.731738000000206]]]}),
        dynamic({"type":"Polygon","coordinates":[[[-73.958357552055688,40.800369095633819],[-73.98143901556422,40.768762584141953],[-73.981548752788598,40.7685590292784],[-73.981565335901905,40.768307084720796],[-73.981754418060945,40.768399727738668],[-73.982038573548124,40.768387823012056],[-73.982268248204349,40.768298621883247],[-73.982384797518051,40.768097213086911],[-73.982320919746599,40.767894461792181],[-73.982155532845766,40.767756204474757],[-73.98238873834039,40.767411004834273],[-73.993650353659021,40.772145571634361],[-73.99415893763998,40.772493009137818],[-73.993831082030937,40.772931787850908],[-73.993891252437052,40.772955194876722],[-73.993962585514595,40.772944653908901],[-73.99401262480508,40.772882846631894],[-73.994122058082397,40.77292405902601],[-73.994136652588594,40.772901870174394],[-73.994301342391154,40.772970028663913],[-73.994281535134448,40.77299380206933],[-73.994376552751078,40.77303955110149],[-73.994294029824005,40.773156243992048],[-73.995023275860802,40.773481196576356],[-73.99508939189289,40.773388475039134],[-73.995013963716758,40.773358035426909],[-73.995050284699261,40.773297153189958],[-73.996240651898916,40.773789791397689],[-73.996195837470992,40.773852356184044],[-73.996098807369748,40.773951805299085],[-73.996179459973888,40.773986954351571],[-73.996095245226442,40.774086186437756],[-73.995572265161172,40.773870731394297],[-73.994017424135961,40.77321375261053],[-73.993935876811335,40.773179512586211],[-73.993861942928888,40.773269531698837],[-73.993822393527211,40.773381758622882],[-73.993767019318497,40.773483981224835],[-73.993698463744295,40.773562141052594],[-73.993358326468751,40.773926888327956],[-73.992622663865575,40.774974056037109],[-73.992577842766124,40.774956016359418],[-73.992527743951555,40.775002110439829],[-73.992469745815342,40.775024159551755],[-73.992403837191887,40.775018140390664],[-73.99226708903538,40.775116033858794],[-73.99217809026365,40.775279293897171],[-73.992059084937338,40.775497598192516],[-73.992125372394938,40.775509075053385],[-73.992226867797001,40.775482211026116],[-73.992329346608813,40.775468900958522],[-73.992361756801131,40.775501899766638],[-73.992386042960277,40.775557180424634],[-73.992087684712729,40.775983970821372],[-73.990927174149746,40.777566878763238],[-73.99039616003671,40.777585065679204],[-73.989461267506471,40.778875124584417],[-73.989175778438053,40.779287524015778],[-73.988868617400072,40.779692922911607],[-73.988871874499793,40.779713738253008],[-73.989219022880576,40.779697895209402],[-73.98927785904425,40.779723439271038],[-73.989409054180143,40.779737706471963],[-73.989498614927044,40.779725044389757],[-73.989596493388234,40.779698146683387],[-73.989679812902509,40.779677568658038],[-73.989752702937935,40.779671244211556],[-73.989842247806507,40.779680752670664],[-73.990040102120489,40.779707677698219],[-73.990137977524839,40.779699769704784],[-73.99033584033225,40.779661794394983],[-73.990430598697046,40.779664973055503],[-73.990622199396725,40.779676064914298],[-73.990745069505479,40.779671328184051],[-73.990872114282197,40.779646007643876],[-73.990961672224358,40.779639683751753],[-73.991057472829539,40.779652352625774],[-73.991157429497036,40.779669775606465],[-73.991242817404469,40.779671367084504],[-73.991255318289745,40.779650782516491],[-73.991294887120119,40.779630209208889],[-73.991321967649895,40.779631796041372],[-73.991359455569423,40.779585883337383],[-73.991551059227476,40.779574821437407],[-73.99141982585985,40.779755280287233],[-73.988886144117032,40.779878898532999],[-73.988939656706265,40.779956178440393],[-73.988926103530844,40.780059292013632],[-73.988911680264692,40.780096037146606],[-73.988919261468567,40.780226094343945],[-73.988381050202634,40.780981074045783],[-73.988232413846987,40.781233144215555],[-73.988210420831663,40.781225482542055],[-73.988140000000143,40.781409000000224],[-73.988041288067166,40.781585961353777],[-73.98810029382463,40.781602878305286],[-73.988076449145055,40.781650935001608],[-73.988018059972219,40.781634188810422],[-73.987960792842145,40.781770987031535],[-73.985465811970457,40.785360700575431],[-73.986172704965611,40.786068452258647],[-73.986455862401996,40.785919219081421],[-73.987072345615601,40.785189638820121],[-73.98711901394276,40.785210319004058],[-73.986497781023601,40.785951202887254],[-73.986164628806279,40.786121882448327],[-73.986128422486075,40.786239001331111],[-73.986071135219746,40.786240706026611],[-73.986027274789123,40.786228964236727],[-73.986097637849426,40.78605822569795],[-73.985429321269592,40.785413942184597],[-73.985081137732209,40.785921935110366],[-73.985198833254501,40.785966552197777],[-73.985170502389906,40.78601333415817],[-73.985216218673656,40.786030501816427],[-73.98525509797993,40.785976205511588],[-73.98524273937646,40.785972572653328],[-73.98524962933017,40.785963139855845],[-73.985281779186749,40.785978620950075],[-73.985240032884533,40.786035858136792],[-73.985683885242182,40.786222123919686],[-73.985717529004575,40.786175994668795],[-73.985765660297687,40.786196274858618],[-73.985682871922691,40.786309786213067],[-73.985636270930442,40.786290150649279],[-73.985670722564691,40.786242911993817],[-73.98520511880038,40.786047669212785],[-73.985211035607492,40.786039554883686],[-73.985162639946992,40.786020999769754],[-73.985131636312062,40.786060297019972],[-73.985016964065125,40.78601423719563],[-73.984655078830457,40.786534741807841],[-73.985743787901043,40.786570082854738],[-73.98589227228328,40.786426529019593],[-73.985942854994988,40.786452847880334],[-73.985949561556794,40.78648711396653],[-73.985812373526713,40.786616865357047],[-73.985135209703174,40.78658761889551],[-73.984619428584324,40.786586016349787],[-73.981952458164173,40.790393724337193],[-73.972823037363767,40.803428052816756],[-73.971036786332192,40.805918478839672],[-73.966701,40.804169000000186],[-73.959647,40.801156000000113],[-73.958508540159471,40.800682279767472],[-73.95853274080838,40.800491362464697],[-73.958357552055688,40.800369095633819]]]}),
        dynamic({"type":"Polygon","coordinates":[[[-73.943592454622546,40.782747908206574],[-73.943648235390199,40.782656161333449],[-73.943870759887162,40.781273026571704],[-73.94345932494096,40.780048275653243],[-73.943213862652243,40.779317588660199],[-73.943004239504688,40.779639495474292],[-73.942716005450905,40.779544169476175],[-73.942712374762181,40.779214856940001],[-73.942535563208608,40.779090956062532],[-73.942893408188027,40.778614093246276],[-73.942438481745029,40.777315235766039],[-73.942244919522594,40.777104088947254],[-73.942074188038887,40.776917846977142],[-73.942002667222781,40.776185317382648],[-73.942620205199006,40.775180871576474],[-73.94285645694552,40.774796600349191],[-73.94293043781397,40.774676268036011],[-73.945870899588215,40.771692257932997],[-73.946618690150586,40.77093339256956],[-73.948664164778933,40.768857624399587],[-73.950069793030679,40.767025088383498],[-73.954418260786071,40.762184104951245],[-73.95650786241211,40.760285256574043],[-73.958787773424007,40.758213471309809],[-73.973015157270069,40.764278692864671],[-73.955760332998182,40.787906554459667],[-73.944023,40.782960000000301],[-73.943592454622546,40.782747908206574]]]}),
    ];
let Coordinates = 
    datatable(longitude:real, latitude:real, description:string)
    [
        real(-73.9741), 40.7914, 'Upper West Side',
        real(-73.9950), 40.7340, 'Greenwich Village',
        real(-73.8743), 40.7773, 'LaGuardia Airport',
    ];
let multipolygon = toscalar(
    Polygons
    | project individual_polygon = pack_array(polygon.coordinates)
    | summarize multipolygon_coordinates = make_list(individual_polygon)
    | project multipolygon = bag_pack("type","MultiPolygon", "coordinates", multipolygon_coordinates));
Coordinates
| where geo_point_in_polygon(longitude, latitude, multipolygon)

Output

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

print in_polygon = geo_point_in_polygon(200,1,dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,1],[0,0]]]}))

Output

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

print in_polygon = geo_point_in_polygon(1,1,dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,10],[0,0]]]}))

Output

31 - geo_point_to_geohash()

Calculates the geohash string value of a geographic location.

Read more about geohash.

Syntax

geo_point_to_geohash(longitude, latitude,[ accuracy ])

Parameters

Returns

The geohash string value of a given geographic location with requested accuracy length. If the coordinate or accuracy is invalid, the query produces an empty result.

Geohash rectangular area coverage per accuracy value:

See also geo_point_to_s2cell(), geo_point_to_h3cell().

Examples

The following example finds US storm events aggregated by geohash.

StormEvents
| project BeginLon, BeginLat
| summarize by hash=geo_point_to_geohash(BeginLon, BeginLat, 3)
| project geo_geohash_to_central_point(hash)
| render scatterchart with (kind=map)

Output

The following example calculates and returns the geohash string value.

print geohash = geo_point_to_geohash(-80.195829, 25.802215, 8)

Output

The following example finds groups of coordinates. Every pair of coordinates in the group resides in a rectangular area of 4.88 km by 4.88 km.

datatable(location_id:string, longitude:real, latitude:real)
[
  "A", double(-122.303404), 47.570482,
  "B", double(-122.304745), 47.567052,
  "C", double(-122.278156), 47.566936,
]
| summarize count = count(),                                          // items per group count
            locations = make_list(location_id)                        // items in the group
            by geohash = geo_point_to_geohash(longitude, latitude)    // geohash of the group

Output

The following example produces an empty result because of the invalid coordinate input.

print geohash = geo_point_to_geohash(200,1,8)

Output

The following example produces an empty result because of the invalid accuracy input.

print geohash = geo_point_to_geohash(1,1,int(null))

Output

32 - geo_point_to_h3cell()

Calculates the H3 Cell token string value of a geographic location.

Read more about H3 Cell.

Syntax

geo_point_to_h3cell(longitude, latitude, [ resolution ])

Parameters

Returns

The H3 Cell token string value of a given geographic location. If the coordinates or levels are invalid, the query will produce an empty result.

H3 Cell approximate area coverage per resolution value

The table source can be found in this H3 Cell statistical resource.

See also geo_point_to_s2cell(), geo_point_to_geohash().

Examples

print h3cell = geo_point_to_h3cell(-74.04450446039874, 40.689250859314974, 6)

Output

The following example finds groups of coordinates. Every pair of coordinates in the group resides in the H3 Cell with average hexagon area of 253 km².

datatable(location_id:string, longitude:real, latitude:real)
[
    "A", -73.956683, 40.807907,
    "B", -73.916869, 40.818314,
    "C", -73.989148, 40.743273,
]
| summarize count = count(),                                         // Items per group count
            locations = make_list(location_id)                       // Items in the group
            by h3cell = geo_point_to_h3cell(longitude, latitude, 5)  // H3 Cell of the group

Output

The following example produces an empty result because of the invalid coordinate input.

print h3cell = geo_point_to_h3cell(300,1,8)

Output

The following example produces an empty result because of the invalid level input.

print h3cell = geo_point_to_h3cell(1,1,16)

Output

The following example produces an empty result because of the invalid level input.

print h3cell = geo_point_to_h3cell(1,1,int(null))

Output

33 - geo_point_to_s2cell()

Calculates the S2 cell token string value of a geographic location.

Read more about S2 cell hierarchy. S2 cell can be a useful geospatial clustering tool. An S2 cell is a cell on a spherical surface and it has geodesic edges. S2 cells are part of a hierarchy dividing up the Earth’s surface. They have a maximum of 31 levels, ranging from zero to 30, which define the number of times a cell is subdivided. Levels range from the largest coverage on level zero with area coverage of 85,011,012.19km², to the lowest coverage of 0.44 cm² at level 30. As S2 cells are subdivided at higher levels, the cell center is preserved well. Two geographic locations can be very close to each other but they have different S2 cell tokens.

Read more about S2 cell hierarchy.

Syntax

geo_point_to_s2cell(longitude, latitude, [ level ])

Parameters

Returns

The S2 cell token string value of a given geographic location. If the coordinates or levels are invalid, the query produces an empty result.

S2 cell approximate area coverage per level value

For every level, the size of the S2 cell is similar but not exactly equal. Nearby cell sizes tend to be more equal.

The table source can be found in this S2 Cell statistical resource.

Examples

US storm events aggregated by S2 cell

The following example finds US storm events aggregated by S2 cells.

StormEvents
| project BeginLon, BeginLat
| summarize by hash=geo_point_to_s2cell(BeginLon, BeginLat, 5)
| project geo_s2cell_to_central_point(hash)
| render scatterchart with (kind=map)

Output

The following example calculates the S2 cell ID.

print s2cell = geo_point_to_s2cell(-80.195829, 25.802215, 8)

Output

Find a group of coordinates

The following example finds groups of coordinates. Every pair of coordinates in the group resides in the S2 cell with a maximum area of 1632.45 km².

datatable(location_id:string, longitude:real, latitude:real)
[
  "A", 10.1234, 53,
  "B", 10.3579, 53,
  "C", 10.6842, 53,
]
| summarize count = count(),                                        // items per group count
            locations = make_list(location_id)                      // items in the group
            by s2cell = geo_point_to_s2cell(longitude, latitude, 8) // s2 cell of the group

Output

Empty results

The following example produces an empty result because of the invalid coordinate input.

print s2cell = geo_point_to_s2cell(300,1,8)

Output

The following example produces an empty result because of the invalid level input.

print s2cell = geo_point_to_s2cell(1,1,35)

Output

The following example produces an empty result because of the invalid level input.

print s2cell = geo_point_to_s2cell(1,1,int(null))

Output

Related content

• geo_point_to_geohash()
• geo_point_to_h3cell()

34 - geo_polygon_area()

Calculates the area of a polygon or a multipolygon on Earth.

Syntax

geo_polygon_area(polygon)

Parameters

Returns

The area of a polygon or a multipolygon, in square meters, on Earth. If the polygon or the multipolygon is invalid, the query will produce a null result.

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.

Examples

The following example calculates NYC Central Park area.

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 area = geo_polygon_area(central_park)

Output

The following example performs union of polygons in multipolygon and calculates area on the unified polygon.

let polygons = dynamic({"type":"MultiPolygon","coordinates":[[[[-73.9495,40.7969],[-73.95807266235352,40.80068603561921],[-73.98201942443848,40.76825672305777],[-73.97317886352539,40.76455136505513],[-73.9495,40.7969]]],[[[-73.94262313842773,40.775991804565585],[-73.98107528686523,40.791849155467695],[-73.99600982666016,40.77092185281977],[-73.96150588989258,40.75609977566361],[-73.94262313842773,40.775991804565585]]]]});
print polygons_union_area = geo_polygon_area(polygons)

Output

The following example calculates top 5 biggest US states by area.

US_States
| project name = features.properties.NAME, polygon = geo_polygon_densify(features.geometry)
| project name, area = geo_polygon_area(polygon)
| top 5 by area desc

Output

The following example returns True because of the invalid polygon.

print isnull(geo_polygon_area(dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,10],[0,0]]]})))

Output

35 - geo_polygon_buffer()

Calculates polygon or multipolygon that contains all points within the given radius of the input polygon or multipolygon on Earth.

Syntax

geo_polygon_buffer(polygon, radius, tolerance)

Parameters

Returns

Polygon or MultiPolygon around the input Polygon or multipolygon. If the coordinates or radius or tolerance is invalid, the query will produce a null result.

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 contains its vertices.

Examples

The following query calculates polygon around input polygon, with radius of 10km.

let polygon = dynamic({"type":"Polygon","coordinates":[[[139.813757,35.719666],[139.72558,35.71813],[139.727471,35.653231],[139.818721,35.657264],[139.813757,35.719666]]]});
print buffer = geo_polygon_buffer(polygon, 10000)

The following query calculates buffer around each polygon and unifies result

datatable(polygon:dynamic, radius:real )
[
    dynamic({"type":"Polygon","coordinates":[[[12.451218693639277,41.906457003556625],[12.445753852969375,41.90160968881543],[12.453514425793855,41.90361551885886],[12.451218693639277,41.906457003556625]]]}), 100,
    dynamic({"type":"Polygon","coordinates":[[[12.4566086734784,41.905119850039995],[12.453913683559591,41.903652663265234],[12.455485761012113,41.90146110630562],[12.4566086734784,41.905119850039995]]]}), 20
]
| project buffer = geo_polygon_buffer(polygon, radius)
| summarize polygons = make_list(buffer)
| project result = geo_union_polygons_array(polygons)

The following example will return true, due to invalid polygon.

print buffer = isnull(geo_polygon_buffer(dynamic({"type":"p"}), 1))

The following example will return true, due to invalid radius.

print buffer = isnull(geo_polygon_buffer(dynamic({"type":"Polygon","coordinates":[[[10,10],[0,10],[0,0],[10,10]]]}), 0))

36 - geo_polygon_centroid()

Calculates the centroid of a polygon or a multipolygon on Earth.

Syntax

geo_polygon_centroid(polygon)

Parameters

Returns

The centroid coordinate values in GeoJSON Format and of a dynamic data type. If polygon or multipolygon are invalid, the query produces a null result.

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 and chooses the smaller of the two regions.
• LinearRing edge length must be less than 180 degrees. The shortest edge between the two vertices is chosen.
• LinearRings must not cross and must not share edges. LinearRings might share vertices.

Examples

The following example calculates the Central Park centroid in New York City.

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 centroid = geo_polygon_centroid(central_park)

Output

The following example calculates the Central Park centroid longitude.

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 
centroid = geo_polygon_centroid(central_park)
| project lng = centroid.coordinates[0]

Output

The following example performs union of polygons in multipolygon and calculates the centroid of the unified polygon.

let polygons = dynamic({"type":"MultiPolygon","coordinates":[[[[-73.9495,40.7969],[-73.95807266235352,40.80068603561921],[-73.98201942443848,40.76825672305777],[-73.97317886352539,40.76455136505513],[-73.9495,40.7969]]],[[[-73.94262313842773,40.775991804565585],[-73.98107528686523,40.791849155467695],[-73.99600982666016,40.77092185281977],[-73.96150588989258,40.75609977566361],[-73.94262313842773,40.775991804565585]]]]});
print polygons_union_centroid = geo_polygon_centroid(polygons)

Output

The following example visualizes the Central Park centroid on a map.

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 
centroid = geo_polygon_centroid(central_park)
| render scatterchart with (kind = map)

Output

The following example returns true because of the invalid polygon.

print isnull(geo_polygon_centroid(dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,10],[0,0]]]})))

Output

37 - geo_polygon_densify()

Converts polygon or multipolygon planar edges to geodesics by adding intermediate points.

Syntax

geo_polygon_densify(polygon, tolerance, [ preserve_crossing ])

Parameters

Polygon definition

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.

Constraints

• The maximum number of points in the densified polygon is limited to 10485760.
• Storing polygons in dynamic format has size limits.
• Densifying a valid polygon may invalidate the polygon. The algorithm adds points in a non-uniform manner, and as such may cause edges to intertwine with each other.

Motivation

• GeoJSON format defines an edge between two points as a straight cartesian line while geo_polygon_densify() uses geodesic.
• The decision to use geodesic or planar edges might depend on the dataset and is especially relevant in long edges.

Returns

Densified polygon in the GeoJSON format and of a dynamic data type. If either the polygon or tolerance is invalid, the query produces a null result.

Examples

The following example densifies Manhattan Central Park polygon. The edges are short and the distance between planar edges and their geodesic counterparts is less than the distance specified by tolerance. As such, the result remains unchanged.

print densified_polygon = tostring(geo_polygon_densify(dynamic({"type":"Polygon","coordinates":[[[-73.958244,40.800719],[-73.949146,40.79695],[-73.973093,40.764226],[-73.982062,40.768159],[-73.958244,40.800719]]]})))

Output

The following example densifies two edges of the polygon. Densified edges length is ~110 km

print densified_polygon = tostring(geo_polygon_densify(dynamic({"type":"Polygon","coordinates":[[[10,10],[11,10],[11,11],[10,11],[10,10]]]})))

Output

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

print densified_polygon = geo_polygon_densify(dynamic({"type":"Polygon","coordinates":[[[10,900],[11,10],[11,11],[10,11],[10,10]]]}))

Output

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

print densified_polygon = geo_polygon_densify(dynamic({"type":"Polygon","coordinates":[[[10,10],[11,10],[11,11],[10,11],[10,10]]]}), 0)

Output

38 - geo_polygon_perimeter()

Calculates the length of the boundary of a polygon or a multipolygon on Earth.

Syntax

geo_polygon_perimeter(polygon)

Parameters

Returns

The length of the boundary of polygon or a multipolygon, in meters, on Earth. If polygon or multipolygon are invalid, the query will produce a null result.

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.

Examples

The following example calculates the NYC Central Park perimeter, in meters.

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 perimeter = geo_polygon_perimeter(central_park)

Output

The following example performs union of polygons in multipolygon and calculates perimeter of the unified polygon.

let polygons = dynamic({"type":"MultiPolygon","coordinates":[[[[-73.9495,40.7969],[-73.95807266235352,40.80068603561921],[-73.98201942443848,40.76825672305777],[-73.97317886352539,40.76455136505513],[-73.9495,40.7969]]],[[[-73.94262313842773,40.775991804565585],[-73.98107528686523,40.791849155467695],[-73.99600982666016,40.77092185281977],[-73.96150588989258,40.75609977566361],[-73.94262313842773,40.775991804565585]]]]});
print perimeter = geo_polygon_perimeter(polygons)

Output

The following example returns True because of the invalid polygon.

print is_invalid = isnull(geo_polygon_perimeter(dynamic({"type": "Polygon","coordinates": [[[0,0],[10,10],[10,10],[0,0]]]})))

Output

39 - geo_polygon_simplify()

Simplifies a polygon or a multipolygon by replacing nearly straight chains of short edges with a single long edge on Earth.

Syntax

geo_polygon_simplify(polygon, tolerance)

Parameters

Returns

Simplified polygon or a multipolygon in the GeoJSON format and of a dynamic data type, with no two vertices with distance less than tolerance. If either the polygon or tolerance is invalid, the query will produce a null result.

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.

Examples

The following example simplifies polygons by removing vertices that are within a 10-meter distance from each other.

let polygon = dynamic({"type":"Polygon","coordinates":[[[-73.94885122776031,40.79673476355657],[-73.94885927438736,40.79692258628347],[-73.94887939095497,40.79692055577034],[-73.9488673210144,40.79693476936093],[-73.94888743758202,40.79693476936093],[-73.9488834142685,40.796959135509105],[-73.94890084862709,40.79695304397289],[-73.94906312227248,40.79710736271788],[-73.94923612475395,40.7968708081794],[-73.94885122776031,40.79673476355657]]]});
print simplified = geo_polygon_simplify(polygon)

Output

The following example simplifies polygons and combines results into GeoJSON geometry collection.

Polygons
| project polygon = features.geometry
| project simplified = geo_polygon_simplify(polygon, 1000)
| summarize lst = make_list(simplified)
| project geojson = bag_pack("type", "Feature","geometry", bag_pack("type", "GeometryCollection", "geometries", lst), "properties", bag_pack("name", "polygons"))

Output

The following example simplifies polygons and unifies result

US_States
| project polygon = features.geometry
| project simplified = geo_polygon_simplify(polygon, 1000)
| summarize lst = make_list(simplified)
| project polygons = geo_union_polygons_array(lst)

Output

The following example returns True because of the invalid polygon.

let polygon = dynamic({"type":"Polygon","coordinates":[[[5,48],[5,48]]]});
print is_invalid_polygon = isnull(geo_polygon_simplify(polygon))

Output

The following example returns True because of the invalid tolerance.

let polygon = dynamic({"type":"Polygon","coordinates":[[[5,48],[0,50],[0,47],[4,47],[5,48]]]});
print is_invalid_polygon = isnull(geo_polygon_simplify(polygon, -0.1))

Output

The following example returns True because high tolerance causes polygon to disappear.

let polygon = dynamic({"type":"Polygon","coordinates":[[[5,48],[0,50],[0,47],[4,47],[5,48]]]});
print is_invalid_polygon = isnull(geo_polygon_simplify(polygon, 1000000))

Output

40 - geo_polygon_to_h3cells()

Converts polygon to H3 cells. This function is a useful geospatial join and visualization tool.

Syntax

geo_polygon_to_h3cells(polygon [, resolution[, radius]])

Parameters

Returns

Array of H3 cell token strings of the same resolution that represet a polygon or a multipolygon. If radius is set to a positive value, then the polygon will be enlarged such that all points within the given radius of the input polygon or multipolygon will be contained inside and the newly calculated polygon that will be converted to H3 cells. If polygon, resolution, radius is invalid, or the cell count exceeds the limit, the query will produce a null result.

Seel also geo_polygon_to_s2cells().

Examples

The following example calculates H3 cells that approximate the polygon.

let polygon = dynamic({"type":"Polygon","coordinates":[[[-3.659,40.553],[-3.913,40.409],[-3.729,40.273],[-3.524,40.440],[-3.659,40.553]]]});
print h3_cells = geo_polygon_to_h3cells(polygon)

Output

The following example demonstrates a multipolygon that consists of H3 cells that approximate the above polygon. Specifing a higher resolution will improve polygon approximation.

let polygon = dynamic({"type":"Polygon","coordinates":[[[-3.659,40.553],[-3.913,40.409],[-3.729,40.273],[-3.524,40.440],[-3.659,40.553]]]});
print h3_cells = geo_polygon_to_h3cells(polygon)
| mv-expand cell = h3_cells to typeof(string) // extract cell to a separate row
| project polygon_cell = geo_h3cell_to_polygon(cell) // convert each cell to a polygon
| project individual_polygon_coordinates = pack_array(polygon_cell.coordinates)
| summarize multipolygon_coordinates = make_list(individual_polygon_coordinates)
| project multipolygon = bag_pack("type","MultiPolygon", "coordinates", multipolygon_coordinates)

Output

The following example return null because the polygon is invalid.

let polygon = dynamic({"type":"Polygon","coordinates":[[[0,0],[1,1]]]});
print is_null = isnull(geo_polygon_to_h3cells(polygon))

Output

41 - geo_polygon_to_s2cells()

Calculates S2 cell tokens that cover a polygon or multipolygon on Earth. This function is a useful geospatial join tool.

Read more about S2 cell hierarchy.

Syntax

geo_polygon_to_s2cells(polygon [, level[, radius]])

Parameters

Returns

Array of S2 cell token strings that cover a polygon or a multipolygon. If radius is set to a positive value, then the covering will be, in addition to input shape, of all points within the radius of the input geometry. If polygon, level, radius is invalid, or the cell count exceeds the limit, the query will produce a null result.

Motivation for covering polygons with S2 cell tokens

Without this function, here’s one approach we could take in order to classify coordinates into polygons containing these coordinates.

let Polygons = 
    datatable(description:string, polygon:dynamic)
    [  
      "New York",  dynamic({"type":"Polygon","coordinates":[[[-73.85009765625,40.85744791303121],[-74.16046142578125,40.84290487729676],[-74.190673828125,40.59935608796518],[-73.83087158203125,40.61812224225511],[-73.85009765625,40.85744791303121]]]}),
      "Seattle",   dynamic({"type":"Polygon","coordinates":[[[-122.200927734375,47.68573021131587],[-122.4591064453125,47.68573021131587],[-122.4755859375,47.468949677672484],[-122.17620849609374,47.47266286861342],[-122.200927734375,47.68573021131587]]]}),
      "Las Vegas", dynamic({"type":"Polygon","coordinates":[[[-114.9,36.36],[-115.4498291015625,36.33282808737917],[-115.4498291015625,35.84453450421662],[-114.949951171875,35.902399875143615],[-114.9,36.36]]]}),
    ];
let Coordinates = 
    datatable(longitude:real, latitude:real)
    [
      real(-73.95),  real(40.75), // New York
      real(-122.3),  real(47.6),  // Seattle
      real(-115.18), real(36.16)  // Las Vegas
    ];
Polygons | extend dummy=1
| join kind=inner (Coordinates | extend dummy=1) on dummy
| where geo_point_in_polygon(longitude, latitude, polygon)
| project longitude, latitude, description

Output

While this method works in some cases, it’s inefficient. This method does a cross-join, meaning that it tries to match every polygon to every point. This process consumes a large amount of memory and compute resources. Instead, we would like to match every polygon to a point with a high probability of containment success, and filter out other points.

This match can be achieved by the following process:

1. Converting polygons to S2 cells of level k,
2. Converting points to the same S2 cells level k,
3. Joining on S2 cells,
4. Filtering by geo_point_in_polygon(). This phase can be omitted if some amount of false positives is ok. The maximum error will be the area of s2 cells at level k beyond the boundary of the polygon.

Choosing the S2 cell level

• Ideally we would want to cover every polygon with one or just a few unique cells such that no two polygons share the same cell.
• If the polygons are close to each other, choose the S2 cell level such that its cell edge will be smaller (4, 8, 12 times smaller) than the edge of the average polygon.
• If the polygons are far from each other, choose the S2 cell level such that its cell edge will be similar or bigger than the edge of the average polygon.
• In practice, covering a polygon with more than 10,000 cells might not yield good performance.
• Sample use cases:
• S2 cell level 5 might prove to be good for covering countries/regions.
• S2 cell level 16 can cover dense and relatively small Manhattan (New York) neighborhoods.
• S2 cell level 11 can be used for covering suburbs of Australia.
• Query run time and memory consumption might differ greatly because of different S2 cell level values.

Examples

The following example classifies coordinates into polygons.

let Polygons = 
    datatable(description:string, polygon:dynamic)
    [
        'Greenwich Village', dynamic({"type":"Polygon","coordinates":[[[-73.991460000000131,40.731738000000206],[-73.992854491775518,40.730082566051351],[-73.996772,40.725432000000154],[-73.997634685522883,40.725786309886963],[-74.002855946639244,40.728346630056791],[-74.001413,40.731065000000207],[-73.996796995070824,40.73736378205173],[-73.991724524037934,40.735245208931886],[-73.990703782359589,40.734781896080477],[-73.991460000000131,40.731738000000206]]]}),
        'Upper West Side',   dynamic({"type":"Polygon","coordinates":[[[-73.958357552055688,40.800369095633819],[-73.98143901556422,40.768762584141953],[-73.981548752788598,40.7685590292784],[-73.981565335901905,40.768307084720796],[-73.981754418060945,40.768399727738668],[-73.982038573548124,40.768387823012056],[-73.982268248204349,40.768298621883247],[-73.982384797518051,40.768097213086911],[-73.982320919746599,40.767894461792181],[-73.982155532845766,40.767756204474757],[-73.98238873834039,40.767411004834273],[-73.993650353659021,40.772145571634361],[-73.99415893763998,40.772493009137818],[-73.993831082030937,40.772931787850908],[-73.993891252437052,40.772955194876722],[-73.993962585514595,40.772944653908901],[-73.99401262480508,40.772882846631894],[-73.994122058082397,40.77292405902601],[-73.994136652588594,40.772901870174394],[-73.994301342391154,40.772970028663913],[-73.994281535134448,40.77299380206933],[-73.994376552751078,40.77303955110149],[-73.994294029824005,40.773156243992048],[-73.995023275860802,40.773481196576356],[-73.99508939189289,40.773388475039134],[-73.995013963716758,40.773358035426909],[-73.995050284699261,40.773297153189958],[-73.996240651898916,40.773789791397689],[-73.996195837470992,40.773852356184044],[-73.996098807369748,40.773951805299085],[-73.996179459973888,40.773986954351571],[-73.996095245226442,40.774086186437756],[-73.995572265161172,40.773870731394297],[-73.994017424135961,40.77321375261053],[-73.993935876811335,40.773179512586211],[-73.993861942928888,40.773269531698837],[-73.993822393527211,40.773381758622882],[-73.993767019318497,40.773483981224835],[-73.993698463744295,40.773562141052594],[-73.993358326468751,40.773926888327956],[-73.992622663865575,40.774974056037109],[-73.992577842766124,40.774956016359418],[-73.992527743951555,40.775002110439829],[-73.992469745815342,40.775024159551755],[-73.992403837191887,40.775018140390664],[-73.99226708903538,40.775116033858794],[-73.99217809026365,40.775279293897171],[-73.992059084937338,40.775497598192516],[-73.992125372394938,40.775509075053385],[-73.992226867797001,40.775482211026116],[-73.992329346608813,40.775468900958522],[-73.992361756801131,40.775501899766638],[-73.992386042960277,40.775557180424634],[-73.992087684712729,40.775983970821372],[-73.990927174149746,40.777566878763238],[-73.99039616003671,40.777585065679204],[-73.989461267506471,40.778875124584417],[-73.989175778438053,40.779287524015778],[-73.988868617400072,40.779692922911607],[-73.988871874499793,40.779713738253008],[-73.989219022880576,40.779697895209402],[-73.98927785904425,40.779723439271038],[-73.989409054180143,40.779737706471963],[-73.989498614927044,40.779725044389757],[-73.989596493388234,40.779698146683387],[-73.989679812902509,40.779677568658038],[-73.989752702937935,40.779671244211556],[-73.989842247806507,40.779680752670664],[-73.990040102120489,40.779707677698219],[-73.990137977524839,40.779699769704784],[-73.99033584033225,40.779661794394983],[-73.990430598697046,40.779664973055503],[-73.990622199396725,40.779676064914298],[-73.990745069505479,40.779671328184051],[-73.990872114282197,40.779646007643876],[-73.990961672224358,40.779639683751753],[-73.991057472829539,40.779652352625774],[-73.991157429497036,40.779669775606465],[-73.991242817404469,40.779671367084504],[-73.991255318289745,40.779650782516491],[-73.991294887120119,40.779630209208889],[-73.991321967649895,40.779631796041372],[-73.991359455569423,40.779585883337383],[-73.991551059227476,40.779574821437407],[-73.99141982585985,40.779755280287233],[-73.988886144117032,40.779878898532999],[-73.988939656706265,40.779956178440393],[-73.988926103530844,40.780059292013632],[-73.988911680264692,40.780096037146606],[-73.988919261468567,40.780226094343945],[-73.988381050202634,40.780981074045783],[-73.988232413846987,40.781233144215555],[-73.988210420831663,40.781225482542055],[-73.988140000000143,40.781409000000224],[-73.988041288067166,40.781585961353777],[-73.98810029382463,40.781602878305286],[-73.988076449145055,40.781650935001608],[-73.988018059972219,40.781634188810422],[-73.987960792842145,40.781770987031535],[-73.985465811970457,40.785360700575431],[-73.986172704965611,40.786068452258647],[-73.986455862401996,40.785919219081421],[-73.987072345615601,40.785189638820121],[-73.98711901394276,40.785210319004058],[-73.986497781023601,40.785951202887254],[-73.986164628806279,40.786121882448327],[-73.986128422486075,40.786239001331111],[-73.986071135219746,40.786240706026611],[-73.986027274789123,40.786228964236727],[-73.986097637849426,40.78605822569795],[-73.985429321269592,40.785413942184597],[-73.985081137732209,40.785921935110366],[-73.985198833254501,40.785966552197777],[-73.985170502389906,40.78601333415817],[-73.985216218673656,40.786030501816427],[-73.98525509797993,40.785976205511588],[-73.98524273937646,40.785972572653328],[-73.98524962933017,40.785963139855845],[-73.985281779186749,40.785978620950075],[-73.985240032884533,40.786035858136792],[-73.985683885242182,40.786222123919686],[-73.985717529004575,40.786175994668795],[-73.985765660297687,40.786196274858618],[-73.985682871922691,40.786309786213067],[-73.985636270930442,40.786290150649279],[-73.985670722564691,40.786242911993817],[-73.98520511880038,40.786047669212785],[-73.985211035607492,40.786039554883686],[-73.985162639946992,40.786020999769754],[-73.985131636312062,40.786060297019972],[-73.985016964065125,40.78601423719563],[-73.984655078830457,40.786534741807841],[-73.985743787901043,40.786570082854738],[-73.98589227228328,40.786426529019593],[-73.985942854994988,40.786452847880334],[-73.985949561556794,40.78648711396653],[-73.985812373526713,40.786616865357047],[-73.985135209703174,40.78658761889551],[-73.984619428584324,40.786586016349787],[-73.981952458164173,40.790393724337193],[-73.972823037363767,40.803428052816756],[-73.971036786332192,40.805918478839672],[-73.966701,40.804169000000186],[-73.959647,40.801156000000113],[-73.958508540159471,40.800682279767472],[-73.95853274080838,40.800491362464697],[-73.958357552055688,40.800369095633819]]]}),
        'Upper East Side',   dynamic({"type":"Polygon","coordinates":[[[-73.943592454622546,40.782747908206574],[-73.943648235390199,40.782656161333449],[-73.943870759887162,40.781273026571704],[-73.94345932494096,40.780048275653243],[-73.943213862652243,40.779317588660199],[-73.943004239504688,40.779639495474292],[-73.942716005450905,40.779544169476175],[-73.942712374762181,40.779214856940001],[-73.942535563208608,40.779090956062532],[-73.942893408188027,40.778614093246276],[-73.942438481745029,40.777315235766039],[-73.942244919522594,40.777104088947254],[-73.942074188038887,40.776917846977142],[-73.942002667222781,40.776185317382648],[-73.942620205199006,40.775180871576474],[-73.94285645694552,40.774796600349191],[-73.94293043781397,40.774676268036011],[-73.945870899588215,40.771692257932997],[-73.946618690150586,40.77093339256956],[-73.948664164778933,40.768857624399587],[-73.950069793030679,40.767025088383498],[-73.954418260786071,40.762184104951245],[-73.95650786241211,40.760285256574043],[-73.958787773424007,40.758213471309809],[-73.973015157270069,40.764278692864671],[-73.955760332998182,40.787906554459667],[-73.944023,40.782960000000301],[-73.943592454622546,40.782747908206574]]]}),
    ];
let Coordinates = 
    datatable(longitude:real, latitude:real)
    [
        real(-73.9741), 40.7914, // Upper West Side
        real(-73.9950), 40.7340, // Greenwich Village
        real(-73.9584), 40.7688, // Upper East Side
    ];
let Level = 16;
Polygons
| extend covering = geo_polygon_to_s2cells(polygon, Level) // cover every polygon with s2 cell token array
| mv-expand covering to typeof(string)                     // expand cells array such that every row will have one cell mapped to its polygon
| join kind=inner hint.strategy=broadcast                  // assume that Polygons count is small (In some specific case)
(
    Coordinates
    | extend covering = geo_point_to_s2cell(longitude, latitude, Level) // cover point with cell
) on covering // join on the cell, this filters out rows of point and polygons where the point definitely does not belong to the polygon
| where geo_point_in_polygon(longitude, latitude, polygon) // final filtering for exact result
| project longitude, latitude, description

Output

Here is even more improvement on the above query. Count storm events per US state. The below query performs a very efficient join because it doesn’t carry polygons through the join and uses lookup operator

" target="_blank">Run the query

let Level = 6;
let polygons = materialize(
    US_States
    | project StateName = tostring(features.properties.NAME), polygon = features.geometry, id = new_guid());
let tmp = 
    polygons
    | project id, covering = geo_polygon_to_s2cells(polygon, Level) 
    | mv-expand covering to typeof(string)
    | join kind=inner hint.strategy=broadcast
            (
                StormEvents
                | project lng = BeginLon, lat = BeginLat
                | project lng, lat, covering = geo_point_to_s2cell(lng, lat, Level)
            ) on covering
    | project-away covering, covering1;
tmp | lookup polygons on id
| project-away id
| where geo_point_in_polygon(lng, lat, polygon)
| summarize StormEventsCountByState = count() by StateName

Output

The following example filters out polygons that don’t intersect with the area of the polygon of interest. The maximum error is diagonal of s2cell length. This example is based on a polygonized earth at night raster file.

let intersection_level_hint = 7;
let area_of_interest = dynamic({"type": "Polygon","coordinates": [[[-73.94966125488281,40.79698248639272],[-73.95841598510742,40.800426144169315],[-73.98124694824219,40.76806170936614],[-73.97283554077148,40.7645513650551],[-73.94966125488281,40.79698248639272]]]});
let area_of_interest_covering = geo_polygon_to_s2cells(area_of_interest, intersection_level_hint);
EarthAtNight
| project value = features.properties.DN, polygon = features.geometry
| extend covering = geo_polygon_to_s2cells(polygon, intersection_level_hint)
| mv-apply c = covering to typeof(string) on
(
    summarize is_intersects = take_anyif(1, array_index_of(area_of_interest_covering, c) != -1)
)
| where is_intersects == 1
| count

Output

Count of cells that will be needed in order to cover some polygon with S2 cells of level 5.

let polygon = dynamic({"type":"Polygon","coordinates":[[[0,0],[0,50],[100,50],[0,0]]]});
print s2_cell_token_count = array_length(geo_polygon_to_s2cells(polygon, 5));

Output

Covering a large-area polygon with small-area cells returns null.

let polygon = dynamic({"type":"Polygon","coordinates":[[[0,0],[0,50],[100,50],[0,0]]]});
print geo_polygon_to_s2cells(polygon, 30);

Output

Covering a large-area polygon with small-area cells returns null.

let polygon = dynamic({"type":"Polygon","coordinates":[[[0,0],[0,50],[100,50],[0,0]]]});
print isnull(geo_polygon_to_s2cells(polygon, 30));

Output

42 - geo_s2cell_neighbors()

Calculates S2 cell neighbors.

Read more about S2 cell hierarchy.

Syntax

geo_s2cell_neighbors(s2cell)

Parameters

Returns

An array of S2 cell neighbors. If the S2 Cell is invalid, the query produces a null result.

Examples

The following example calculates S2 cell neighbors.

print neighbors = geo_s2cell_neighbors('89c259')

Output

The following example calculates an array of input S2 cell with its neighbors.

let s2cell = '89c259';
print cells = array_concat(pack_array(s2cell), geo_s2cell_neighbors(s2cell))

Output

The following example calculates S2 cells polygons GeoJSON geometry collection.

let s2cell = '89c259';
print cells = array_concat(pack_array(s2cell), geo_s2cell_neighbors(s2cell))
| mv-expand cells to typeof(string)
| project polygons = geo_s2cell_to_polygon(cells)
| summarize arr = make_list(polygons)
| project geojson = bag_pack("type", "Feature","geometry", bag_pack("type", "GeometryCollection", "geometries", arr), "properties", bag_pack("name", "polygons"))

Output

The following example calculates polygon unions that represent S2 cell and its neighbors.

let s2cell = '89c259';
print cells = array_concat(pack_array(s2cell), geo_s2cell_neighbors(s2cell))
| mv-expand cells to typeof(string)
| project polygons = geo_s2cell_to_polygon(cells)
| summarize arr = make_list(polygons)
| project polygon = geo_union_polygons_array(arr)

Output

The following example returns true because of the invalid S2 Cell token input.

print invalid = isnull(geo_s2cell_neighbors('a'))

Output

43 - geo_s2cell_to_central_point()

Calculates the geospatial coordinates that represent the center of an S2 cell.

Read more about S2 cell hierarchy.

Syntax

geo_s2cell_to_central_point(s2cell)

Parameters

Returns

The geospatial coordinate values in GeoJSON Format and of a dynamic data type. If the S2 cell token is invalid, the query will produce a null result.

Examples

print point = geo_s2cell_to_central_point("1234567")
| extend coordinates = point.coordinates
| extend longitude = coordinates[0], latitude = coordinates[1]

Output

The following example returns a null result because of the invalid S2 cell token input.

print point = geo_s2cell_to_central_point("a")

Output

44 - geo_s2cell_to_polygon()

Calculates the polygon that represents the S2 Cell rectangular area.

Read more about S2 Cells.

Syntax

geo_s2cell_to_polygon(s2cell)

Parameters

Returns

Polygon in GeoJSON Format and of a dynamic data type. If the s2cell is invalid, the query produces a null result.

Examples

print s2cellPolygon = geo_s2cell_to_polygon("89c259")

Output

The following example assembles GeoJSON geometry collection of S2 Cell polygons.

datatable(lng:real, lat:real)
[
    -73.956683, 40.807907,
    -73.916869, 40.818314,
    -73.989148, 40.743273,
]
| project s2_hash = geo_point_to_s2cell(lng, lat, 10)
| project s2_hash_polygon = geo_s2cell_to_polygon(s2_hash)
| summarize s2_hash_polygon_lst = make_list(s2_hash_polygon)
| project bag_pack(
    "type", "Feature",
    "geometry", bag_pack("type", "GeometryCollection", "geometries", s2_hash_polygon_lst),
    "properties", bag_pack("name", "S2 Cell polygons collection"))

Output

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

print s2cellPolygon = geo_s2cell_to_polygon("a")

Output

45 - geo_simplify_polygons_array()

Simplifies polygons by replacing nearly straight chains of short edges with a single long edge on Earth.

Syntax

geo_simplify_polygons_array(polygons, tolerance)

Parameters

Returns

Simplified polygon or a multipolygon in the GeoJSON format and of a dynamic data type, with no two vertices with distance less than tolerance. If either the polygon or tolerance is invalid, the query will produce a null result.

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.

Examples

The following example simplifies polygons with mutual borders (USA states), by removing vertices that are within a 100-meter distance from each other.

US_States
| project polygon = features.geometry
| summarize lst = make_list(polygon)
| project polygons = geo_simplify_polygons_array(lst, 100)

Output

The following example returns True because one of the polygons is invalid.

datatable(polygons:dynamic)
[
    dynamic({"type":"Polygon","coordinates":[[[-73.9495,40.7969],[-73.95807,40.80068],[-73.98201,40.76825],[-73.97317,40.76455],[-73.9495,40.7969]]]}),
    dynamic({"type":"Polygon","coordinates":[[[-73.94622,40.79249]]]}),
    dynamic({"type":"Polygon","coordinates":[[[-73.97335,40.77274],[-73.9936,40.76630],[-73.97171,40.75655],[-73.97335,40.77274]]]})
]
| summarize arr = make_list(polygons)
| project is_invalid_polygon = isnull(geo_simplify_polygons_array(arr))

Output

The following example returns True because of the invalid tolerance.

datatable(polygons:dynamic)
[
    dynamic({"type":"Polygon","coordinates":[[[-73.9495,40.7969],[-73.95807,40.80068],[-73.98201,40.76825],[-73.97317,40.76455],[-73.9495,40.7969]]]}),
    dynamic({"type":"Polygon","coordinates":[[[-73.94622,40.79249],[-73.96888,40.79282],[-73.9577,40.7789],[-73.94622,40.79249]]]}),
    dynamic({"type":"Polygon","coordinates":[[[-73.97335,40.77274],[-73.9936,40.76630],[-73.97171,40.75655],[-73.97335,40.77274]]]})
]
| summarize arr = make_list(polygons)
| project is_null = isnull(geo_simplify_polygons_array(arr, -1))

Output

The following example returns True because high tolerance causes polygon to disappear.

datatable(polygons:dynamic)
[
    dynamic({"type":"Polygon","coordinates":[[[-73.9495,40.7969],[-73.95807,40.80068],[-73.98201,40.76825],[-73.97317,40.76455],[-73.9495,40.7969]]]}),
    dynamic({"type":"Polygon","coordinates":[[[-73.94622,40.79249],[-73.96888,40.79282],[-73.9577,40.7789],[-73.94622,40.79249]]]}),
    dynamic({"type":"Polygon","coordinates":[[[-73.97335,40.77274],[-73.9936,40.76630],[-73.97171,40.75655],[-73.97335,40.77274]]]})
]
| summarize arr = make_list(polygons)
| project is_null = isnull(geo_simplify_polygons_array(arr, 10000))

Output

46 - geo_union_lines_array()

Calculates the union of lines or multilines on Earth.

Syntax

geo_union_lines_array(lineStrings)

Parameters

Returns

A line or a multiline in GeoJSON Format and of a dynamic data type. If any of the provided lines or multilines is invalid, the query will produce a null result.

LineString definition and constraints

dynamic({“type”: “LineString”,“coordinates”: [[lng_1,lat_1], [lng_2,lat_2], …, [lng_N,lat_N]]})

dynamic({“type”: “MultiLineString”,“coordinates”: [[line_1, line_2, …, line_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 will be chosen.

Examples

The following example performs geospatial union on line rows.

datatable(lines:dynamic)
[
    dynamic({"type":"LineString","coordinates":[[-73.95683884620665,40.80502891480884],[-73.95633727312088,40.8057171711177],[-73.95489156246185,40.80510200431311]]}),
    dynamic({"type":"LineString","coordinates":[[-73.95633727312088,40.8057171711177],[-73.95489156246185,40.80510200431311],[-73.95537436008453,40.804413741624515]]}),
    dynamic({"type":"LineString","coordinates":[[-73.95633727312088,40.8057171711177],[-73.95489156246185,40.80510200431311]]})
]
| summarize lines_arr = make_list(lines)
| project lines_union = geo_union_lines_array(lines_arr)

Output

The following example performs geospatial union on line columns.

datatable(line1:dynamic, line2:dynamic)
[
    dynamic({"type":"LineString","coordinates":[[-73.95683884620665,40.80502891480884],[-73.95633727312088,40.8057171711177],[-73.95489156246185,40.80510200431311]]}), dynamic({"type":"LineString","coordinates":[[-73.95633727312088,40.8057171711177],[-73.95489156246185,40.80510200431311],[-73.95537436008453,40.804413741624515]]})
]
| project lines_arr = pack_array(line1, line2)
| project lines_union = geo_union_lines_array(lines_arr)

Output

The following example returns True because one of the lines is invalid.

datatable(lines:dynamic)
[
    dynamic({"type":"LineString","coordinates":[[-73.95683884620665,40.80502891480884],[-73.95633727312088,40.8057171711177],[-73.95489156246185,40.80510200431311]]}),
    dynamic({"type":"LineString","coordinates":[[1, 1]]})
]
| summarize lines_arr = make_list(lines)
| project invalid_union = isnull(geo_union_lines_array(lines_arr))

Output

47 - geo_union_polygons_array()

Calculates the union of polygons or multipolygons on Earth.

Syntax

geo_union_polygons_array(polygons)

Parameters

Returns

A polygon or a multipolygon in GeoJSON Format and of a dynamic data type. If any of the provided polygons or multipolygons is invalid, the query will produce a null result.

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.

Examples

The following example performs geospatial union on polygon rows.

datatable(polygons:dynamic)
[
    dynamic({"type":"Polygon","coordinates":[[[-73.9495,40.7969],[-73.95807,40.80068],[-73.98201,40.76825],[-73.97317,40.76455],[-73.9495,40.7969]]]}),
    dynamic({"type":"Polygon","coordinates":[[[-73.94622,40.79249],[-73.96888,40.79282],[-73.9577,40.7789],[-73.94622,40.79249]]]}),
    dynamic({"type":"Polygon","coordinates":[[[-73.97335,40.77274],[-73.9936,40.76630],[-73.97171,40.75655],[-73.97335,40.77274]]]})
]
| summarize polygons_arr = make_list(polygons)
| project polygons_union = geo_union_polygons_array(polygons_arr)

Output

The following example performs geospatial union on polygon columns.

datatable(polygon1:dynamic, polygon2:dynamic)
[
    dynamic({"type":"Polygon","coordinates":[[[-73.9495,40.7969],[-73.95807,40.80068],[-73.98201,40.76825],[-73.97317,40.76455],[-73.9495,40.7969]]]}), dynamic({"type":"Polygon","coordinates":[[[-73.94622,40.79249],[-73.96888,40.79282],[-73.9577,40.7789],[-73.94622,40.79249]]]})
]
| project polygons_arr = pack_array(polygon1, polygon2)
| project polygons_union = geo_union_polygons_array(polygons_arr)

Output

The following example returns True because one of the polygons is invalid.

datatable(polygons:dynamic)
[
    dynamic({"type":"Polygon","coordinates":[[[-73.9495,40.7969],[-73.95807,40.80068],[-73.98201,40.76825],[-73.97317,40.76455],[-73.9495,40.7969]]]}),
    dynamic({"type":"Polygon","coordinates":[[[-73.94622,40.79249]]]})
]
| summarize polygons_arr = make_list(polygons)
| project invalid_union = isnull(geo_union_polygons_array(polygons_arr))

Output

48 - Geospatial data visualizations

Geospatial data can be visualized as part of your query using the render operator as points, pies, or bubbles on a map.

Visualize points on a map

You can visualize points either using [Longitude, Latitude] columns, or GeoJSON column. Using a series column is optional. The [Longitude, Latitude] pair defines each point, in that order.

Example: Visualize points on a map

The following example finds storm events and visualizes 100 on a map.

StormEvents
| take 100
| project BeginLon, BeginLat
| render scatterchart with (kind = map)

Example: Visualize multiple series of points on a map

The following example visualizes multiple series of points, where the [Longitude, Latitude] pair defines each point, and a third column defines the series. In this example, the series is EventType.

StormEvents
| take 100
| project BeginLon, BeginLat, EventType
| render scatterchart with (kind = map)

Example: Visualize series of points on data with multiple columns

The following example visualizes a series of points on a map. If you have multiple columns in the result, you must specify the columns to be used for xcolumn (Longitude), ycolumn (Latitude), and series.

StormEvents
| take 100
| render scatterchart with (kind = map, xcolumn = BeginLon, ycolumns = BeginLat, series = EventType)

Example: Visualize points on a map defined by GeoJSON dynamic values

The following example visualizes points on the map using GeoJSON dynamic values to define the points.

StormEvents
| project BeginLon, BeginLat
| summarize by hash=geo_point_to_s2cell(BeginLon, BeginLat, 5)
| project geo_s2cell_to_central_point(hash)
| render scatterchart with (kind = map)

Visualization of pies or bubbles on a map

You can visualize pies or bubbles either using [Longitude, Latitude] columns, or GeoJSON column. These visualizations can be created with color or numeric axes.

Example: Visualize pie charts by location

The following example shows storm events aggregated by S2 cells. The chart aggregates events in bubbles by location in one color.

StormEvents
| project BeginLon, BeginLat, EventType
| where geo_point_in_circle(BeginLon, BeginLat, real(-81.3891), 28.5346, 1000 * 100)
| summarize count() by EventType, hash = geo_point_to_s2cell(BeginLon, BeginLat)
| project geo_s2cell_to_central_point(hash), count_
| extend Events = "count"
| render piechart with (kind = map)

Example: Visualize bubbles using a color axis

The following example shows storm events aggregated by S2 cells. The chart aggregates events by event type in pie charts by location.

StormEvents
| project BeginLon, BeginLat, EventType
| where geo_point_in_circle(BeginLon, BeginLat, real(-81.3891), 28.5346, 1000 * 100)
| summarize count() by EventType, hash = geo_point_to_s2cell(BeginLon, BeginLat)
| project geo_s2cell_to_central_point(hash), EventType, count_
| render piechart with (kind = map)

Related content

• Render operator
• Data analytics for automotive test fleets (geospatial clustering use case)
• Learn about Azure architecture for geospatial data processing and analytics

49 - Geospatial grid system

Geospatial data can be analyzed efficiently using grid systems to create geospatial clusters. You can use geospatial tools to aggregate, cluster, partition, reduce, join, and index geospatial data. These tools improve query runtime performance, reduce stored data size, and visualize aggregated geospatial data.

The following methods of geospatial clustering are supported:

• Geohash
• S2 Cell
• H3 Cell

The core functionalities of these methods are:

• Calculate hash\index\cell token of geospatial coordinate. Different geospatial coordinates that belong to same cell will have same cell token value.
• Calculate center point of hash\index\cell token. This point is useful because it may represent all the values in the cell.
• Calculate cell polygon. Calculating cell polygons is useful in cell visualization or other calculations, for example, distance, or point in polygon checks.

Compare methods

Geohash functions

S2 Cell functions

H3 Cell functions

Related content

• See a use case for geospatial clustering: Data analytics for automotive test fleets
• Learn about Azure architecture for geospatial data processing and analytics