Geometry Functions

Since Arcade expressions execute for each feature, using multiple geometry operations within the context of the labeling and visualization profiles can be expensive and severely impact the performance of the application. Also note that geometries fetched from feature services, especially polylines and polygons, are generalized according to the view's scale resolution. Be aware that using a feature's geometry (i.e. $feature) as input to any geometry function will yield results only as precise as the view scale. Therefore, results returned from geometry operations in the visualization and labeling profiles may be different at each scale level. Use these functions at your discretion within these contexts.

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
Measurement
Topological relationship testing
Overlay
Proximity

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.

Unit valueAlternate values
*acresacre, ac
feetfoot, ft, square-feet, square-foot, squarefeet, squarefoot
*hectareshectare, ha
kilometerskilometer, km, square-kilometers, square-kilometer, squarekilometers, squarekilometer
milesmile, square-miles, square-mile, squaremiles, squaremile
metersmeter, m, square-meters, square-meter, squaremeters, squaremeter
yardsyard, yd, square-yards, square-yard, squareyards, squareyard

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

Area

Area( geometry, unit? ) -> returns: Number

Since version 1.3

Returns the area of the input geometry 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.

Name Type Description
geometry Polygon / Feature The Polygon or Extent geometry for which to calculate the planar area.
unit String / Number optional Measurement unit of the return value. Use one of the string values listed in the Units reference or any of the numeric codes for area units.
Returns: Number
Example
Returns the area of the feature in square meters
Area($feature, 'square-meters')

AreaGeodetic

AreaGeodetic( geometry, unit? ) -> returns: Number

Since version 1.3

Returns the geodetic area of the input geometry 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.

Name Type Description
geometry Polygon / Feature The Polygon or Extent geometry for which to calculate the planar area.
unit String / Number optional Measurement unit of the return value. Use one of the string values listed in the Units reference or any of the numeric codes for area units.
Returns: Number
Example
Returns the geodetic area of the feature in square meters
AreaGeodetic($feature, 'square-meters')

Buffer

Buffer( geometry, distance, unit? ) -> returns: 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.

Name Type Description
geometry Geometry / Feature The geometry to buffer.
distance Number The distance to buffer from the geometry.
unit String / Number optional Measurement unit of the buffer distance. Use one of the string values listed in the Units reference or any of the numeric codes.
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? ) -> returns: 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.

Name Type Description
geometry Geometry / Feature The geometry to buffer.
distance Number The distance to buffer from the geometry.
unit String / Number optional Measurement unit of the buffer distance. Use one of the string values listed in the Units reference or any of the numeric codes.
Returns: Polygon
Example
Returns a polygon representing a 1/2-mile buffer around the input geometry
BufferGeodetic($feature, 0.5, 'miles')

Centroid

Centroid( geometry ) -> returns: Point

Since version 1.3

Returns the centroid of the input 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.

Name Type Description
geometry Polygon / Feature The polygon or feature for which to calculate the centroid.
Returns: Point
Example
Returns the centroid of the given polygon
Centroid($feature)

Clip

Clip( geometry, envelope ) -> returns: 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.

Name Type Description
geometry Geometry / Feature The geometry to be clipped.
envelope Extent The envelope used to clip the geometry.
Returns: Geometry
Example
Returns the area of the clipped geometry
var envelope = Extent({ ... });
Area(Clip($feature, envelope), 'square-miles');


Contains

Contains( containerGeometry, insideGeometry ) -> returns: Boolean

Since version 1.3

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.

Name Type Description
containerGeometry Geometry / Feature The geometry that is tested for the 'contains' relationship to insideGeometry. Think of this geometry as the potential 'container' of the insideGeometry.
insideGeometry Geometry / Feature The geometry that is tested for the 'within' relationship to the containerGeometry.
Returns: Boolean
Example
Returns true if the feature is contained within the given polygon
var container = Polygon({ ... });
Contains(container, $feature);


Crosses

Crosses( geometry1, geometry2 ) -> returns: Boolean

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.

Name Type Description
geometry1 Geometry / Feature The geometry to cross.
geometry2 Geometry / Feature The geometry being crossed.
Returns: Boolean
Example
Returns true if the feature crosses the given polygon
var geom2 = Polygon({ ... });
Crosses($feature, geom2);


Cut

Cut( geometry, cutter ) -> returns: 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.

Name Type Description
geometry Polyline / Polygon / Feature The geometry to cut.
cutter Polyline / Feature The Polyline used to cut the geometry.
Returns: Geometry[]
Example
Cuts the feature's geometry with the given polyline
var cutter = Polyline({ ... });
Cut($feature, cutter));


Difference

Difference( inputGeometry, subtractor ) -> returns: 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.

Name Type Description
inputGeometry Geometry / Feature The input geometry from which to subtract.
subtractor Geometry / Feature The geometry to subtract from inputGeometry.
Returns: Geometry
Example
Subtracts the given polygon area from the feature.
var subtractor = Polygon({ ... });
Difference($feature, subtractor);


Disjoint

Disjoint( geometry1, geometry2 ) -> returns: 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.

Name Type Description
geometry1 Geometry / Feature The base geometry that is tested for the 'disjoint' relationship to geometry2.
geometry2 Geometry / Feature The comparison geometry that is tested for the 'disjoint' relationship to geometry1.
Returns: Boolean
Example
Returns true if the geometries don't intersect
var geom2 = Polygon({ ... });
Disjoint($feature, geom2);


Distance

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

Since version 1.3

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.

Name Type Description
geometry1 Geometry / Feature The geometry used to measure the distance from geometry2.
geometry2 Geometry / Feature The geometry used to measure the distance from geometry1.
unit String / Number optional Measurement unit of the return value. Use one of the string values listed in the Units reference or any of the numeric codes.
Returns: Number
Example
Returns the distance between two geometries in meters
var geom2 = Point({ ... });
Distance($feature, geom2, 'meters')


Equals

Equals( geometry1, geometry2 ) -> returns: 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.

Name Type Description
geometry1 Geometry / Feature The first input geometry.
geometry2 Geometry / Feature The second input geometry.
Returns: Boolean
Example
Returns true if the geometries are equal
var geom2 = Point({ ... });
Equals($feature, geom2);


Extent

Extent( json ) -> returns: 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.

Name Type Description
json Object / Geometry The JSON or Geometry from which to construct the extent geometry object.
Returns: Extent
Example
// Creates an Extent object
var extentJSON = {
  'xmin' : -109.55, 'ymin' : 25.76, 'xmax' : -86.39, 'ymax' : 49.94,
  'spatialReference' : {'wkid' : 4326}
};
Extent(extentJSON);

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


Geometry

Geometry( feature ) -> returns: 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.

Name Type Description
feature Feature / Object The Feature or JSON from which to construct the geometry object.
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 ) -> returns: 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.

Name Type Description
geometry1 Geometry / Feature The geometry to intersect with geometry2.
geometry2 Geometry / Feature The geometry to intersect with geometry1.
Returns: Geometry
Example
Returns the area common to both polygons
var geom2 = Polygon({ ... });
Area(Intersection($feature, geom2), 'square-miles');


Intersects

Intersects( geometry1, geometry2 ) -> returns: Boolean

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.

Name Type Description
geometry1 Geometry / Feature The geometry that is tested for the intersects relationship to the other geometry.
geometry2 Geometry / Feature The geometry being intersected.
Returns: Boolean
Example
Returns true if the geometries intersect
var geom2 = Polygon({ ... });
Intersects($feature, geom2);


Length

Length( geometry, unit? ) -> returns: Number

Since version 1.3

Returns the length of the input geometry 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.

Name Type Description
geometry Geometry / Feature The geometry for which to calculate the planar length.
unit String / Number optional Measurement unit of the return value. Use one of the string values listed in the Units reference or any of the numeric codes.
Returns: Number
Example
Returns the planar length of the feature in kilometers
Length($feature, 'kilometers')

LengthGeodetic

LengthGeodetic( geometry, unit? ) -> returns: Number

Since version 1.3

Returns the geodetic length of the input geometry 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.

Name Type Description
geometry Geometry / Feature The geometry for which to calculate the geodetic length.
unit String / Number optional Measurement unit of the return value. Use one of the string values listed in the Units reference or any of the numeric codes.
Returns: Number
Example
Returns the geodetic length of the feature in kilometers
LengthGeodetic($feature, 'kilometers')

MultiPartToSinglePart

MultiPartToSinglePart( geometry ) -> returns: 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.

Name Type Description
geometry Geometry / Feature The multi-part geometry to break into single parts.
Returns: Geometry[]
Example
Returns an array of single-part geometries from a multi-part geometry
var allParts = MultiPartToSinglePart($feature)

Multipoint

Multipoint( json ) -> returns: 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.

Name Type Description
json Object The JSON from which to construct the multipoint geometry object.
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' : 4326}
};
Multipoint(multipointJSON);


Overlaps

Overlaps( geometry1, geometry2 ) -> returns: Boolean

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.

Name Type Description
geometry1 Geometry / Feature The base geometry that is tested for the 'overlaps' relationship with geometry2.
geometry2 Geometry / Feature The comparison geometry that is tested for the 'overlaps' relationship with geometry1.
Returns: Boolean
Example
Returns true if the geometries overlap
var geom2 = Polygon({ ... });
Overlaps($feature, geom2);


Point

Point( json ) -> returns: 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.

Name Type Description
json Object The JSON from which to construct the point geometry object.
Returns: Point
Example
// Creates a Point object
var pointJSON = {'x' : -118.15, 'y' : 33.80, 'spatialReference' : {'wkid' : 4326}};
Point(pointJSON)


Polygon

Polygon( json ) -> returns: 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.

Name Type Description
json Object The JSON from which to construct the polygon geometry object.
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' : 4326}
};
Polygon(polygonJSON);


Polyline

Polyline( json ) -> returns: 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.

Name Type Description
json Object The JSON from which to construct the polyline geometry object.
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);


Relate

Relate( geometry1, geometry2, relation ) -> returns: Boolean

Since version 1.3

Indicates if the given DE-9IM relation holds for the two 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.

Name Type Description
geometry1 Geometry / Feature The geometry to test with geometry2 for the given relation.
geometry2 Geometry / Feature The geometry to test with geometry1 for the given relation.
relation String

The Dimensionally Extended 9 Intersection Model (DE-9IM) matrix relation (encoded as a string) to test against the relationship of the two geometries. This string contains the test result of each intersection represented in the DE-9IM matrix. Each result is one character of the string and may be represented as either a number (maximum dimension returned: 0,1,2), a Boolean value (T or F), or a mask character (for ignoring results: *).

Example: Each of the following DE-9IM string codes are valid for testing whether a polygon geometry completely contains a line geometry: TTTFFTFFT (Boolean), T******FF* (ignore irrelevant intersections), or 102FF*FF* (dimension form). Each returns the same result. See this ArcGIS help page for more information about the DE-9IM model and how string codes are constructed.

Returns: Boolean
Example
Returns true if the polygon completely contains the polyline feature
var container = Polygon({ ... });
Relate(container, $feature, 'TTTFFTFFT');


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.

Name Type Description
internalFeature Feature A feature whose geometry will be updated.
geometry Geometry The geometry to set on the input feature.
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 ) -> returns: 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.

Name Type Description
leftGeometry Geometry / Feature The geometry instance to compare to rightGeometry in the XOR operation.
rightGeometry Geometry / Feature The geometry instance to compare to leftGeometry in the XOR operation.
Returns: Geometry
Example
Returns a polygon representing areas where both inputs do not overlap
var geom2 = Polygon({ ... });
SymmetricDifference($feature, geom2);


Touches

Touches( geometry1, geometry2 ) -> returns: Boolean

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.

Name Type Description
geometry1 Geometry / Feature The geometry to test the 'touches' relationship with geometry2.
geometry2 Geometry / Feature The geometry to test the 'touches' relationship with geometry1.
Returns: Boolean
Example
Returns true if the geometries touch
var geom2 = Polygon({ ... });
Touches($feature, geom2);


Union

Union( geometries ) -> returns: 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.

Name Type Description
geometries Geometry[] / Feature[] An array, or list, of geometries to union into a single geometry. This can be any number of geometries.
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 ) -> returns: Boolean

Since version 1.3

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.

Name Type Description
innerGeometry Geometry / Feature The base geometry that is tested for the 'within' relationship to outerGeometry.
outerGeometry Geometry / Feature The comparison geometry that is tested for the 'contains' relationship to innerGeometry.
Returns: Boolean
Example
Returns true if the feature is within the given polygon
var outerGeom = Polygon({ ... });
Within($feature, outerGeom);



Feedback on this topic?