geometryService | References | ArcGIS Maps SDK for JavaScript

import { areasAndLengths, autoComplete, buffer, convexHull, cut } from "@arcgis/core/rest/geometryService.js";

Since: ArcGIS Maps SDK for JavaScript 4.19

Represents geometry service resources exposed by the ArcGIS REST API. It is used to perform various operations on geometries such as project, simplify, buffer, and relationships.

View the About the geometry service help topic for details. Esri hosts a geometry service on sampleserver6.arcgisonline.com to support samples. However, we do not guarantee that the service will be available 24/7.

Many of the functions in geometryService are available for use client-side using geometry operators. See the Introduction to geometry operators guide topic for more details.

Functions

Name	Return Type	Object
`areasAndLengths`	`Promise<{ areas: number[]; lengths: number[]; }>`
`autoComplete`	`Promise<Polygon[]>`
`buffer`	`Promise<Polygon[]>`
`convexHull`	`Promise<GeometryUnion>`
`cut`	`Promise<CutResult>`
`densify`	`Promise<GeometryUnion[]>`
`difference`	`Promise<GeometryWithoutMeshUnion[]>`
`distance`	`Promise<number>`
`fromGeoCoordinateString`	`Promise<number[][]>`
`generalize`	`Promise<GeometryUnion[]>`
`intersect`	`Promise<GeometryUnion[]>`
`labelPoints`	`Promise<Point[]>`
`lengths`	`Promise<{ lengths: number[]; }>`
`offset`	`Promise<GeometryUnion[]>`
`project`	`Promise<GeometryUnion[]>`
`relation`	`Promise<Polygon[]>`
`reshape`	`Promise<GeometryUnion>`
`simplify`	`Promise<T[]>`
`toGeoCoordinateString`	`Promise<string[]>`
`trimExtend`	`Promise<Polyline[]>`
`union`	`Promise<GeometryUnion>`

areasAndLengths

Function

Computes the area and length for the input polygons.

See also

Signature: areasAndLengths (url: string, parameters: AreasAndLengthsParameters, requestOptions?: RequestOptions): Promise<{ areas: number[]; lengths: number[]; }>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`AreasAndLengthsParameters`	Specify the input polygons and optionally the linear and area units.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns

Promise<{ areas: number[]; lengths: number[]; }>

When resolved, returns an object with the following specification:

{
  areas: <Number[]>,
  lengths: <Number[]>
}

Example

simplify(url, { polygons: [polygon] }).then(function(simplifiedGeometries){
  const areasAndLengthParams = new AreasAndLengthsParameters({
    areaUnit: "square-kilometers",
    lengthUnit: "kilometers",
    polygons: simplifiedGeometries
  });
  areasAndLengths(url, areasAndLengthParams).then(function(results){
    console.log("area: ", results.areas[0]);
    console.log("length: ", results.lengths[0]);
  });
});

autoComplete

Function

The Auto Complete operation is performed on a geometry service resource. The AutoComplete operation simplifies the process of constructing new polygons that are adjacent to other polygons. It constructs polygons that fill in the gaps between existing polygons and a set of polylines.

See also

autoCompleteOperator

Signature: autoComplete (url: string, polygons: Polygon[], polylines: Polyline[], requestOptions?: RequestOptions): Promise<Polygon[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
polygons	`Polygon[]`	The array of polygons that will provide boundaries for new polygons.
polylines	`Polyline[]`	An array of polylines that will provide the remaining boundaries for new polygons.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<Polygon[]>
When resolved, returns an array of Polygon geometries containing polygons with the gaps filled with a set of polylines.

buffer

Function

Creates buffer polygons at a specified distance around the given geometries.

See also

Signature: buffer (url: string, parameters: BufferParameters, requestOptions?: RequestOptions): Promise<Polygon[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`BufferParameters`	Specifies the input geometries, buffer distances, and other options.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<Polygon[]>
Returns an array of Polygon geometries representing the buffered areas of the input.

Example

const webMerPoint = webMercatorUtils.geographicToWebMercator(point);
const parameters = new BufferParameters({
  distances: [560],
  unit: "kilometers",
  geodesic: true,
  bufferSpatialReference: new SpatialReference({wkid: 3857}),
  outSpatialReference: view.spatialReference,
  geometries: [webMerPoint]
});

buffer(url, parameters).then(function(results){
  bufferLayer.add(new Graphic({
     geometry: results[0]
  }));
});

convexHull

Function

The convexHull operation is performed on a geometry service resource. It returns the convex hull of the input geometry. The input geometry can be a point, multipoint, polyline or polygon. The hull is typically a polygon but can also be a polyline or point in degenerate cases.

See also

convexHullOperator

Signature: convexHull (url: string, geometries: GeometryUnion[], requestOptions?: RequestOptions): Promise<GeometryUnion>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
geometries	`GeometryUnion[]`	The geometries whose convex hull is to be created.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<GeometryUnion>
When resolved, returns a Geometry representing the convex hull of the input.

Example

const geoms = pointLayer.graphics.map(function(item, i){
  return webMercatorUtils.geographicToWebMercator(item.geometry);
});
convexHull(url, { geometries: geoms.toArray() }).then(function(result){
  convexLayer.add(new Graphic({
    geometry: result
  }));
},function(error){
   console.log("error occurred", error)
});

cut

Function

Type parameters: <T extends Polygon | Polyline>

The cut operation is performed on a geometry service resource. This operation splits the input polyline or polygon where it crosses a cutting polyline.

See also

cutOperator

Signature: cut <T extends Polygon | Polyline>(url: string, geometries: T[], cutter: Polyline, requestOptions?: RequestOptions): Promise<CutResult<T>>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
geometries	`T[]`	The polylines or polygons to be cut.
cutter	`Polyline`	The polyline that will be used to divide the target into pieces where it crosses the target.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns

Promise<CutResult>

When resolved, returns an object with the following specification:

{
  cutIndexes: <Number[]>,
  geometries: <Geometry[]>
}

densify

Function

The densify operation is performed on a geometry service resource. This operation densifies geometries by plotting points between existing vertices.

See also

Signature: densify (url: string, parameters: DensifyParameters, requestOptions?: RequestOptions): Promise<GeometryUnion[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`DensifyParameters`	The DensifyParameters objects contains `geometries`, `geodesic`, `lengthUnit`, and `maxSegmentLength` properties.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<GeometryUnion[]>
When resolved, returns an array of geometries defining the densified input features.

Example

const params = new DensifyParameters({
  geodesic: true,
  lengthUnit: "meters",
  maxSegmentLength: 30,
  geometries: [polygon]
});

densify(url, params).then(function(results){
  layer.add(new Graphic({
    geometry: results[0]
  }));
}.catch(function(error){
   console.log("error occurred", error)
});

difference

Function

The difference operation is performed on a geometry service resource. This operation constructs the set-theoretic difference between an array of geometries and another geometry.

See also

differenceOperator

Signature: difference (url: string, geometries: GeometryWithoutMeshUnion[], geometry: GeometryWithoutMeshUnion, requestOptions?: RequestOptions): Promise<GeometryWithoutMeshUnion[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
geometries	`GeometryWithoutMeshUnion[]`	An array of points, multipoints, polylines or polygons.
geometry	`GeometryWithoutMeshUnion`	A single geometry of any type, with a dimension equal to or greater than the items in geometries.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<GeometryWithoutMeshUnion[]>
When resolved, returns an array of geometries defining the difference of the input features.

distance

Function

Measures the planar or geodesic distance between geometries.

See also

Signature: distance (url: string, parameters: DistanceParameters, requestOptions?: RequestOptions): Promise<number>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`DistanceParameters`	Sets the input geometries to measure, distance units, and other parameters.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<number>
When resolved, returns a number representing the distance between the input geometries.

fromGeoCoordinateString

Function

Converts an array of well-known strings into xy-coordinates based on the conversion type and spatial reference supplied by the user. Only available with ArcGIS Server 10.3 or above.

See also

coordinateFormatter

Signature: fromGeoCoordinateString (url: string, parameters: FromGeoCoordinateStringParameters, requestOptions?: RequestOptions): Promise<number[][]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`FromGeoCoordinateStringParameters`	See the object specifications table below for the structure of the `parameters` object.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<number[][]>
When resolved, returns an array of XY-coordinate pairs.

Example

parameters = {
  conversionType: "geo-ref",
  sr: "4326",
  strings: ["ZGQA5999999900000000","EJCE3864000012728040","NKBH1196052000273924" ]
};

fromGeoCoordinateString(url, parameters).then(function(results){
  console.log("results", results);
}, function(error){
    console.log(error);
});

generalize

Function

Generalizes the input geometries using the Douglas-Peucker algorithm.

See also

generalizeOperator

Signature: generalize (url: string, parameters: GeneralizeParameters, requestOptions?: RequestOptions): Promise<GeometryUnion[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`GeneralizeParameters`	An array of geometries to generalize and a maximum deviation. Optionally set the deviation units.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<GeometryUnion[]>
When resolved, returns an array of geometries defining the generalized geometries of the input.

intersect

Function

The intersect operation is performed on a geometry service resource. This operation constructs the set-theoretic intersection between an array of geometries and another geometry.

See also

Signature: intersect (url: string, geometries: GeometryUnion[], intersector: GeometryUnion, requestOptions?: RequestOptions): Promise<GeometryUnion[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
geometries	`GeometryUnion[]`	An array of points, multipoints, polylines, or polygons.
intersector	`GeometryUnion`	A single geometry of any type, of dimension equal to or greater than the dimension of the items in `geometries`.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<GeometryUnion[]>
When resolved, returns an array of geometries defining the intersection of the input features.

labelPoints

Function

Calculates an interior point for each polygon specified. These interior points can be used by clients for labeling the polygons.

See also

labelPointOperator

Signature: labelPoints (url: string, polygons: Polygon[], requestOptions?: RequestOptions): Promise<Point[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
polygons	`Polygon[]`	The polygon graphics to process.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<Point[]>
When resolved, returns an array of Point geometries defining the interior points of the input polygons that may be used for labeling.

Example

if (geometries[0].rings.length > 0) {
 labelPoints(url, { geometries: geometries }).then(function(labelPoints) {
  const graphics = labelPoints.map(function(labelPoint, i){
      const textSymbol = {
        type: "text",  // autocasts as new TextSymbol()
        color: "white",
        haloColor: "black",
        haloSize: "1px",
        text: "X: " + number.format(labelPoint.x) + ", Y: " + number.format(labelPoint.y),
        xoffset: 3,
        yoffset: 3,
        font: {  // autocast as new Font()
          size: 12,
          family: "sans-serif",
          weight: "bolder"
        }
      };
    const labelPointGraphic = new Graphic({
      geometry: labelPoint,
      symbol: textSymbol
    });
    return labelPointGraphic;
  });

  // add the labels to the map
  view.graphics.addMany(graphics);
 });
}

lengths

Function

Gets the lengths for a Geometry when the geometry type is Polyline

See also

Signature: lengths (url: string, parameters: LengthsParameters, requestOptions?: RequestOptions): Promise<{ lengths: number[]; }>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`LengthsParameters`	Specify the polylines and optionally the length unit and the geodesic length option.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns

Promise<{ lengths: number[]; }>

When resolved, returns an object containing a lengths property, which is an array of numbers, each representing the length of an input line. See object specification below:

{
  lengths: <Number[]>
}

offset

Function

Constructs the offset of the input geometries based on a planar distance. If the offsetDistance is positive the constructed offset will be on the right side of the geometry. Left side offsets are constructed with negative values.

See also

offsetOperator

Signature: offset (url: string, parameters: OffsetParameters, requestOptions?: RequestOptions): Promise<GeometryUnion[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`OffsetParameters`	Set the geometries to offset, distance, and units.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<GeometryUnion[]>
When resolved, returns an array of geometries offset at the specified distance from the input.

project

Function

Projects a set of geometries to a new spatial reference.

See also

projectOperator

Signature: project (url: string, parameters: ProjectParameters, requestOptions?: RequestOptions): Promise<GeometryUnion[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`ProjectParameters`	The input projection parameters.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<GeometryUnion[]>
When resolved, returns an array of projected geometries.

Example

const [geometryService, ProjectParameters] = await $arcgis.import([
  "@arcgis/core/rest/geometryService.js",
  "@arcgis/core/rest/support/ProjectParameters.js"
]);

const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Utilities/Geometry/GeometryServer";

const params = new ProjectParameters({
  geometries: [point],
  outSpatialReference: outSpatialReference,
  transformation: transformation
});

geometryService.project(url, params).then(function(response){
  console.log("results: ", response);
});

relation

Function

Computes the set of pairs of geometries from the input geometry arrays that belong to the specified relation. Both arrays are assumed to be in the same spatial reference. The relations are evaluated in 2D. Z-coordinates are not used. Geometry types cannot be mixed within an array.

See also

Guide topic - Spatial relationship operators

Signature: relation (url: string, parameters: RelationParameters, requestOptions?: RequestOptions): Promise<Polygon[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`RelationParameters`	The set of parameters required to perform the comparison.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<Polygon[]>
When resolved, returns an array of Polygon geometries that meet the relation.

Example

const [geometryService, RelationParameters] = await $arcgis.import([
  "@arcgis/core/rest/geometryService.js",
  "@arcgis/core/rest/support/RelationParameters.js"
]);

const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Utilities/Geometry/GeometryServer";

const params = new RelationParameters({
  geometries1: geometries[0],
  geometries2: geometries[1],
  relation: "within"
});

geometryService.relation(url, params).then(function(response){
  console.log("results: ", response);
});

reshape

Function

The reshape operation is performed on a geometry service resource. It reshapes a Polyline or a part of a Polygon using a reshaping line.

See also

reshapeOperator

Signature: reshape (url: string, geometry: Polygon | Polyline, reshaper: Polyline, requestOptions?: RequestOptions): Promise<GeometryUnion>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
geometry	`Polygon \| Polyline`	The Polyline or Polygon to be reshaped.
reshaper	`Polyline`	The single-part polyline that performs the reshaping.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<GeometryUnion>
When resolved, returns the Geometry defining the reshaped input feature.

simplify

Function

Type parameters: <T extends GeometryUnion>

Alters the given geometries to make their definitions topologically legal with respect to their geometry type.

See also

simplifyOperator

Signature: simplify <T extends GeometryUnion>(url: string, geometries: T[], requestOptions?: RequestOptions): Promise<T[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
geometries	`T[]`	The geometries to simplify.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<T[]>
When resolved, returns an array of the simplified geometries.

Example

geometryService.simplify(url, [polygonGraphic.geometry]).then( ... );

toGeoCoordinateString

Function

Converts an array of XY-coordinates into well-known strings based on the conversion type and spatial reference supplied by the user. Only available with ArcGIS Server 10.3 or above.

See also

coordinateFormatter

Signature: toGeoCoordinateString (url: string, parameters: ToGeoCoordinateStringParameters, requestOptions?: RequestOptions): Promise<string[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`ToGeoCoordinateStringParameters`	See the object specifications table below for the structure of the `parameters` object.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<string[]>
When resolved, returns an array of well-known strings.

Example

const geometryService = await $arcgis.import("@arcgis/core/rest/geometryService.js");

const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Utilities/Geometry/GeometryServer";

const parameters = {
  sr: "4326",
  coordinates: [ [180,0] , [-117,34] , [0,52] ],
  conversionType: "mgrs",
  conversionMode: "mgrsNewWith180InZone01",
  numOfDigits: 8
};

geometryService.toGeoCoordinateString(url, parameters).then(function(response){
  // When resolved, these strings are stored in response object
  // response.strings[0] = "01N AA 66021443 00000000"
  // response.strings[1] = "11S NT 00000000 62155978"
  // response.strings[2] = "31U BT 94071081 65288255"
});

trimExtend

Function

Trims or extends the input polylines using the user specified guide polyline. When trimming features, the portion to the left of the cutting line is preserved in the output and the rest is discarded. If the input polyline is not cut or extended then an empty polyline is added to the output array.

See also

Signature: trimExtend (url: string, parameters: TrimExtendParameters, requestOptions?: RequestOptions): Promise<Polyline[]>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
parameters	`TrimExtendParameters`	Input parameters for the `trimExtend` operation.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<Polyline[]>
When resolved, returns an array of the trimmed or extended geometries.

union

Function

The union operation is performed on a geometry service resource. This operation constructs the set-theoretic union of the geometries in the input array. All inputs must be of the same type.

See also

unionOperator

Signature: union (url: string, geometries: GeometryUnion[], requestOptions?: RequestOptions): Promise<GeometryUnion>

Parameters

Parameter	Type	Description
url	`string`	The ArcGIS Server REST service URL of a GeometryService. Esri hosts a geometry service on sampleserver6.arcgisonline.com for development and testing purposes.
geometries	`GeometryUnion[]`	An array of the geometries to be unioned.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<GeometryUnion>
When resolved, returns a Geometry representing the union of the input features.