Geometry Functions

The following functions allow you to create and evaluate geometry objects. For convenience, you may pass a Feature object (e.g. $feature) as input to any of these methods, and the feature will internally cast as a geometry. These functions are grouped into the following categories:

Create geometries

• Geometry() - Extent() - MultiPartToSinglePart() - Multipoint() - Point() - Polyline() - Polygon() - SetGeometry()

Measurement

• Angle() - Area() - AreaGeodetic() - Bearing() - Centroid() - DistanceGeodetic() - Length() - LengthGeodetic()

Topological relationship testing

• Contains() - Crosses() - Disjoint() - Equals() - Intersects() - IsSelfIntersecting() - Overlaps() - RingIsClockwise() - Touches() - Within()

Overlay

• Clip() - Cut() - Difference() - Intersection() - SymmetricDifference() - Union()

Proximity

• Buffer() - BufferGeodetic() - Distance()

Units reference

If a function references units, then any of the values described in the table below may be used. Units can either be identified as a number or a string. If the value is a number, it will be based on the standard referenced here. Where appropriate, linear and areal units may be used interchangeably. For example, if calculating an area and meters is specified as the unit, then the unit will be treated as square-meters and vice versa.

* Indicates the unit may only be used for calculating areas.

Angle

Angle( pointA, pointB, pointC? ) -> Number

Since version 1.7

Returns the arithmetic angle of a line between two or three points in degrees (0 - 360). The angle is measured from 0 - 360 degrees in a counter-clockwise direction relative to east. An angle of 90 degrees points due north. See bearing.

Returns: Number

Example

Returns the angle between the feature and another point in degrees

var pointA = Point({ "x":976259, "y":8066511, "spatialReference": { "wkid": 3857 } });
Angle(pointA,$feature)

Area

Area( geometry, unit? ) -> Number

Since version 1.7

Returns the area of the input geometry or FeatureSet in the given units. This is a planar measurement using Cartesian mathematics.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Number

Example

Returns the area of the feature in square meters

Area($feature, 'square-meters')

Returns the area of the layer in square kilometers

Area($layer, 'square-kilometers')

AreaGeodetic

AreaGeodetic( geometry, unit? ) -> Number

Since version 1.7

Returns the geodetic area of the input geometry or FeatureSet in the given units. This is more reliable measurement of area than Area() because it takes into account the Earth's curvature. Support is limited to geometries with a Web Mercator (wkid 3857) or a WGS 84 (wkid 4326) spatial reference.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Number

Example

Returns the geodetic area of the feature in square meters

AreaGeodetic($feature, 'square-meters')

Returns the geodetic area of the layer in square kilometers

AreaGeodetic($layer, 'square-kilometers')

Bearing

Bearing( pointA, pointB, pointC? ) -> Number

Since version 1.7

Returns the geographic angle of a line between two or three points in degrees. The bearing is measured from 0 - 360 degrees in a clockwise direction relative to north. A bearing of 225 degrees represents a southwest orientation. See also angle.

Returns: Number

Example

Returns the bearing between the feature and a point in degrees

var pointA = Point({ "x":976259, "y":8066511, "spatialReference": { "wkid": 3857 } });
Bearing(pointA,$feature)

Buffer

Buffer( geometry, distance, unit? ) -> Polygon

Since version 1.3

Returns the planar (or Euclidean) buffer at a specified distance around the input geometry. This is a planar measurement using Cartesian mathematics.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Polygon

Example

Returns a polygon representing a 1/2-mile buffer around the input geometry

Buffer($feature, 0.5, 'miles')

BufferGeodetic

BufferGeodetic( geometry, distance, unit? ) -> Polygon

Since version 1.3

Returns the geodetic buffer at a specified distance around the input geometry. This is a geodesic measurement, which calculates distances on an ellipsoid. Support is limited to geometries with a Web Mercator (wkid 3857) or a WGS 84 (wkid 4326) spatial reference.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Polygon

Example

Returns a polygon representing a 1/2-mile buffer around the input geometry

BufferGeodetic($feature, 0.5, 'miles')

Centroid

Centroid( points ) -> Point

Since version 1.7

Returns the centroid of the input geometry.

Returns: Point

Example

Returns the centroid of the given polygon

Centroid($feature)

Returns the centroid of the given polygon ring

var ringPoints = Geometry($feature).rings[0];
Centroid(ringPoints);

Clip

Clip( geometry, envelope ) -> Geometry

Since version 1.3

Calculates the clipped geometry from a target geometry by an envelope.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Geometry

Example

Returns the area of the clipped geometry

var envelope = Extent({ ... });
Area(Clip($feature, envelope), 'square-miles');

Contains

Contains( containerGeometry, insideGeometry ) -> Boolean / FeatureSet

Since version 1.7

Indicates if one geometry contains another geometry.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Boolean | FeatureSet

Example

Returns true if the feature is contained within the given polygon

var container = Polygon({ ... });
Contains(container, $feature);

Returns the number of features that contain the given polygon

var projectArea = Polygon({ ... });
Count(Contains(projectArea, $layer));

Crosses

Crosses( geometry1, geometry2 ) -> Boolean / FeatureSet

Since version 1.3

Indicates if one geometry crosses another geometry.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Boolean | FeatureSet

Example

Returns true if the feature crosses the given polygon

var geom2 = Polygon({ ... });
Crosses($feature, geom2);

Returns the number of features in the feature set that cross the given polygon

var geom2 = Polygon({ ... });
Count( Crosses($layer, geom2) );

Cut

Cut( geometry, cutter ) -> Geometry[]

Since version 1.3

Splits the input Polyline or Polygon where it crosses a cutting Polyline. For Polylines, all resulting left cuts are grouped together in the first Geometry. Right cuts and coincident cuts are grouped in the second Geometry. Each undefined cut, along with any uncut parts, are output as separate Polylines.

For Polygons, all resulting left cuts are grouped in the first Polygon, all right cuts are grouped in the second Polygon, and each undefined cut, along with any left-over parts after cutting, are output as a separate Polygon. If no cuts are returned then the array will be empty. An undefined cut will only be produced if a left cut or right cut was produced and there was a part left over after cutting, or a cut is bounded to the left and right of the cutter.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Geometry[]

Example

Cuts the feature's geometry with the given polyline

var cutter = Polyline({ ... });
Cut($feature, cutter));

Difference

Difference( inputGeometry, subtractor ) -> Geometry

Since version 1.3

Performs the topological difference operation for the two geometries. The resultant geometry comes from inputGeometry, not the subtractor. The dimension of subtractor has to be equal to or greater than that of inputGeometry.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Geometry

Example

Subtracts the given polygon area from the feature.

var subtractor = Polygon({ ... });
Difference($feature, subtractor);

Disjoint

Disjoint( geometry1, geometry2 ) -> Boolean

Since version 1.3

Indicates if one geometry is disjoint (doesn't intersect in any way) with another geometry.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Boolean

Example

Returns true if the geometries don't intersect

var geom2 = Polygon({ ... });
Disjoint($feature, geom2);

Distance

Distance( geometry1, geometry2, unit? ) -> Number

Since version 1.7

Returns the planar distance between two geometries in the given units. This is a planar measurement using Cartesian mathematics.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Number

Example

Returns the distance between two geometries in meters

var geom2 = Point({ ... });
Distance($feature, geom2, 'meters')

DistanceGeodetic

DistanceGeodetic( point1, point2, units? ) -> Number

Since version 1.8

Calculates the shortest distance between two points along a great circle. Applies only to points with a Geographic Coordinate System (GCS) or the Web Mercator spatial reference. If the input points have a Projected Coordinate System (other than Web Mercator), you should use the distance method.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Number

Example

Returns the distance from a bus in a stream layer to the central station in kilometers.

var unionStation = Point({"x": -118.15, "y": 33.80, "spatialReference": { "wkid": 3857 }});
distanceGeodetic($feature, unionStation, 'kilometers');

Equals

Equals( geometry1, geometry2 ) -> Boolean

Since version 1.3

Indicates if two geometries are equal, or geographically equivalent given the spatial reference and tolerance of the data. The two input geometries don't have to be clones to be considered equal.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Boolean

Example

Returns true if the geometries are equal

var geom2 = Point({ ... });
Equals($feature, geom2);

Extent

Extent( json ) -> Extent

Constructs an Extent object from a JSON string or an object literal. The JSON schema must follow the ArcGIS REST API format for Envelope geometries. This function may also return the extent of an input Polygon, Point, Polyline or Multipoint.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Extent

Example

// Creates an Extent object
var extentJSON = {
  "xmin": -109.55, "ymin": 25.76, "xmax": -86.39, "ymax": 49.94,
  "spatialReference": { "wkid": 3857 }
};
Extent(extentJSON);

// Returns the Extent of the given feature
Extent($feature)

Geometry

Geometry( feature ) -> Geometry

Constructs a Geometry object from a JSON string or an object literal. The JSON schema must follow the ArcGIS REST API format for geometries. This function may also return the Geometry of an input feature.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Geometry

Example

Returns the geometry of the feature

Geometry($feature)

Constructs a point geometry. This can be done with any geometry type.

var pointJSON = {"x": -118.15, "y": 33.80, "spatialReference": { "wkid": 4326 } };
Geometry(pointJSON);

Intersection

Intersection( geometry1, geometry2 ) -> Geometry

Since version 1.3

Constructs the set-theoretic intersection between two geometries and returns a new geometry.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Geometry

Example

Returns the area common to both polygons

var geom2 = Polygon({ ... });
Area(Intersection($feature, geom2), 'square-miles');

Intersects

Intersects( geometry1, geometry2 ) -> Boolean / FeatureSet

Since version 1.3

Indicates if one geometry intersects another geometry.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Boolean | FeatureSet

Example

Returns true if the geometries intersect

var geom2 = Polygon({ ... });
Intersects($feature, geom2);

Returns the number of features that intersect the polygon

var geom2 = Polygon({ ... });
Count( Intersects($layer, geom2) );

IsSelfIntersecting

IsSelfIntersecting( geometry ) -> Boolean

Since version 1.8

Indicates whether the input geometry has rings, paths, or points that intersect or cross other parts of the geometry. For example, a single polyline feature whose paths intersect each other or a polygon with rings that self intersect would return true.

Returns: Boolean

Example

Returns true if the polyline's paths intersect each other.

var polyline = Polyline({ ... });
IsSelfIntersecting(polyline);

Length

Length( geometry, unit? ) -> Number

Since version 1.7

Returns the length of the input geometry or FeatureSet in the given units. This is a planar measurement using Cartesian mathematics.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Number

Example

Returns the planar length of the feature in kilometers

Length($feature, 'kilometers')

Returns the planar length of the layer in meters

Length($layer, 'meters')

LengthGeodetic

LengthGeodetic( geometry, unit? ) -> Number

Since version 1.7

Returns the geodetic length of the input geometry or FeatureSet in the given units. This is more reliable measurement of length than Length() because it takes into account the Earth's curvature. Support is limited to geometries with a Web Mercator (wkid 3857) or a WGS 84 (wkid 4326) spatial reference.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Number

Example

Returns the geodetic length of the feature in kilometers

LengthGeodetic($feature, 'kilometers')

Returns the geodetic length of the layer in meters

LengthGeodetic($layer, 'meters')

MultiPartToSinglePart

MultiPartToSinglePart( geometry ) -> Geometry[]

Since version 1.3

Converts a multi-part geometry into separate geometries.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Geometry[]

Example

Returns an array of single-part geometries from a multi-part geometry

var allParts = MultiPartToSinglePart($feature)

Multipoint

Multipoint( json ) -> Multipoint

Constructs a Multipoint object from a JSON string or an object literal. The JSON schema must follow the ArcGIS REST API format for multipoint geometries.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Multipoint

Example

// Creates a Multipoint object
var multipointJSON = {
  "points": [[-97.06138,32.837],[-97.06133,32.836],[-97.06124,32.834],[-97.06127,32.832]],
  "spatialReference" : { "wkid": 3857 }
};
Multipoint(multipointJSON);

Overlaps

Overlaps( geometry1, geometry2 ) -> Boolean / FeatureSet

Since version 1.3

Indicates if one geometry overlaps another geometry.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Boolean | FeatureSet

Example

Returns true if the geometries overlap

var geom2 = Polygon({ ... });
Overlaps($feature, geom2);

Returns the number of features that overlap the polygon

var geom2 = Polygon({ ... });
Count( Overlaps($layer, geom2) );

Point

Point( json ) -> Point

Constructs a Point object from a JSON string or an object literal. The JSON schema must follow the ArcGIS REST API format for Point geometries.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Point

Example

// Creates a Point object
var pointJSON = { "x": -118.15, "y": 33.80, "spatialReference": { "wkid": 4326 }};
Point(pointJSON)

Polygon

Polygon( json ) -> Polygon

Constructs a Polygon object from a JSON string or an object literal. The JSON schema must follow the ArcGIS REST API format for Polygon geometries.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Polygon

Example

// Creates a Polygon object
var polygonJSON = {
  "rings": [ [[-97.06138,32.837],[-97.06133,32.836],[-97.06124,32.834],[-97.06127,32.832], [-97.06138,32.837]],[[-97.06326,32.759],[-97.06298,32.755],[-97.06153,32.749], [-97.06326,32.759]] ],
  "spatialReference": { "wkid": 3857 }
};
Polygon(polygonJSON);

Polyline

Polyline( json ) -> Polyline

Constructs a Polyline object from a JSON string or an object literal. The JSON schema must follow the ArcGIS REST API format for Polyline geometries.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Polyline

Example

// Creates a Polyline object
var polylineJSON = {
  "paths": [ [[-97.06138,32.837],[-97.06133,32.836],[-97.06124,32.834],[-97.06127,32.832]], [[-97.06326,32.759],[-97.06298,32.755]] ],
  "spatialReference": { "wkid": 4326 }
};
Polyline(polylineJSON);

RingIsClockwise

RingIsClockwise( points ) -> Boolean

Since version 1.7

Indicates whether the points in a polygon ring are ordered in a clockwise direction.

Returns: Boolean

Example

// $feature is a polygon feature
var polygonRings = Geometry($feature).rings;
IIF(RingIsClockwise(polygonRings[0]), 'correct polygon', 'incorrect direction')

SetGeometry

SetGeometry( internalFeature, geometry )

Since version 1.3

Sets or replaces a geometry on a user-defined Feature. Note that features referenced as global variables are immutable; their geometries cannot be changed.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Example

Sets a new geometry on the feature

var feature = Feature(Point( ... ), 'name', 'buffer centroid');
var buffer = BufferGeodetic(Geometry(feature), 1, 'mile');
SetGeometry(feature, buffer);

SymmetricDifference

SymmetricDifference( leftGeometry, rightGeometry ) -> Geometry

Since version 1.3

Performs the Symmetric difference operation on the two geometries. The symmetric difference includes the parts of both geometries that are not common with each other.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Geometry

Example

Returns a polygon representing areas where both inputs do not overlap

var geom2 = Polygon({ ... });
SymmetricDifference($feature, geom2);

Touches

Touches( geometry1, geometry2 ) -> Boolean / FeatureSet

Since version 1.3

Indicates if one geometry touches another geometry.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Boolean | FeatureSet

Example

Returns true if the geometries touch

var geom2 = Polygon({ ... });
Touches($feature, geom2);

Returns the number of features in the layer that touch the geometry.

var geom = Polygon({ ... });
Count( Touches($layer, geom) );

Union

Union( geometries ) -> Geometry

Since version 1.3

Constructs the set-theoretic union of the geometries in an input array, or list, and returns a single Geometry. All inputs must have the same geometry type and share the same spatial reference.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Geometry

Example

Unions geometries passed as an array

var geom2 = Polygon({ ... });
Union([ $feature, geom2 ]);

Unions geometries passed as a list

var geom2 = Polygon({ ... });
var geom3 = Polygon({ ... });
var geom4 = Polygon({ ... });
Union(Geometry($feature), geom2, geom3, geom4);

Within

Within( innerGeometry, outerGeometry ) -> Boolean / FeatureSet

Since version 1.7

Indicates if one geometry is within another geometry.

Be aware that using $feature as input to this function will yield results only as precise as the view's scale resolution. Therefore values returned from expressions using this function may change after zooming between scales. Read more here.

Returns: Boolean | FeatureSet

Example

Returns true if the feature is within the given polygon

var outerGeom = Polygon({ ... });
Within($feature, outerGeom);

Returns the number of features in the layer within the polygon

var outerGeom = Polygon({ ... });
Count( Within(outerGeom, $layer) );