geometryService

AMD: require(["esri/rest/geometryService"], (geometryService) => { /* code goes here */ });
ESM: import * as geometryService from "@arcgis/core/rest/geometryService.js";
Object: esri/rest/geometryService
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.

It is recommended that you utilize geometry service functions within your applications. View the About the geometry service help topic in the Server Resource Center for details. Esri hosts a geometry service on sampleserver6.arcgisonline.com to support samples published in the Resource Center. 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 GeometryEngine. See GeometryEngine for more details.

See also

Method Overview

Name Return Type Summary Object
Promise<object>

Computes the area and length for the input polygons.

geometryService
Promise<Polygon[]>

The Auto Complete operation is performed on a geometry service resource.

geometryService
Promise<Polygon[]>

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

geometryService
Promise<Geometry>

The convexHull operation is performed on a geometry service resource.

geometryService
Promise<object>

The cut operation is performed on a geometry service resource.

geometryService
Promise<Geometry[]>

The densify operation is performed on a geometry service resource.

geometryService
Promise<Geometry>

The difference operation is performed on a geometry service resource.

geometryService
Promise<number>

Measures the planar or geodesic distance between geometries.

geometryService
Promise

Converts an array of well-known strings into xy-coordinates based on the conversion type and spatial reference supplied by the user.

geometryService
Promise<Geometry[]>

Generalizes the input geometries using the Douglas-Peucker algorithm.

geometryService
Promise<Geometry[]>

The intersect operation is performed on a geometry service resource.

geometryService
Promise<Point[]>

Calculates an interior point for each polygon specified.

geometryService
Promise<object>

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

geometryService
Promise<Geometry[]>

Constructs the offset of the input geometries based on a planar distance.

geometryService
Promise<Geometry[]>

Projects a set of geometries to a new spatial reference.

geometryService
Promise<Polygon[]>

Computes the set of pairs of geometries from the input geometry arrays that belong to the specified relation.

geometryService
Promise<Geometry>

The reshape operation is performed on a geometry service resource.

geometryService
Promise<Geometry[]>

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

geometryService
Promise<string[]>

Converts an array of XY-coordinates into well-known strings based on the conversion type and spatial reference supplied by the user.

geometryService
Promise<Polyline[]>

Trims or extends the input polylines using the user specified guide polyline.

geometryService
Promise<Geometry>

The union operation is performed on a geometry service resource.

geometryService

Method Details

areasAndLengths

Method
areasAndLengths(url, areasAndLengthsParameters, requestOptions){Promise<object>}

Computes the area and length for the input polygons.

Parameters
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.

areasAndLengthsParameters AreasAndLengthsParameters

Specify the input polygons and optionally the linear and area units.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<object> 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

Method
autoComplete(url, polygons, polylines, requestOptions){Promise<Polygon[]>}

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.

Parameters
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 Object
optional

Additional options to be used for the data request.

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

buffer

Method
buffer(url, bufferParameters, requestOptions){Promise<Polygon[]>}

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

Parameters
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.

bufferParameters BufferParameters

Specifies the input geometries, buffer distances, and other options.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<Polygon[]> Returns an array of Polygon geometries representing the buffered areas of the input.
Example
const webMerPoint = webMercatorUtils.geographicToWebMercator(point);
const params = new BufferParameters({
  distances: [560],
  unit: "kilometers",
  geodesic: true,
  bufferSpatialReference: new SpatialReference({wkid: 3857}),
  outSpatialReference: view.spatialReference,
  geometries: [webMerPoint]
});

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

convexHull

Method
convexHull(url, geometries, requestOptions){Promise<Geometry>}

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.

Parameters
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 Geometry[]

The geometries whose convex hull is to be created.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<Geometry> 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

Method
cut(url, geometries, cutter, requestOptions){Promise<object>}

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

Parameters
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 Geometry[]

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 Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<object> When resolved, returns an object with the following specification:
{
  cutIndexes: <Number[]>,
  geometries: <Geometry[]>
}

densify

Method
densify(url, densifyParameters, requestOptions){Promise<Geometry[]>}

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

Parameters
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.

densifyParameters DensifyParameters

The DensifyParameters objects contains geometries, geodesic, lengthUnit, and maxSegmentLength properties.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<Geometry[]> 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

Method
difference(url, geometries, geometry, requestOptions){Promise<Geometry>}

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.

Parameters
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 Geometry[]

An array of points, multipoints, polylines or polygons.

geometry Geometry

A single geometry of any type, with a dimension equal to or greater than the items in geometries.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<Geometry> When resolved, returns an array of geometries defining the difference of the input features.

distance

Method
distance(url, distanceParameters, requestOptions){Promise<number>}

Measures the planar or geodesic distance between geometries.

Parameters
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.

distanceParameters DistanceParameters

Sets the input geometries to measure, distance units, and other parameters.

requestOptions Object
optional

Additional options to be used for the data request.

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

fromGeoCoordinateString

Method
fromGeoCoordinateString(url, params, requestOptions){Promise}

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.

Parameters
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.

params Object

See the object specifications table below for the structure of the params object.

Specification
strings String[]

An array of formatted strings as specified by conversionType. Example: ["01N AA 66021 00000" , "11S NT 00000 62155" , "31U BT 94071 65288"]

The spatial reference or well-known ID to convert the input string coordinates to.

conversionType String
optional
Default Value: mrgs

The conversion type of the input strings.

Possible Values:"mrgs"|"usng"|"utm"|"geo-ref"|"gars"|"dms"|"ddm"|"dd"

conversionMode String
optional

Conversion options for mrgs, utm and gars conversion types. See the ArcGIS REST API documentation for possible values and their descriptions.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise When resolved, returns an array of XY-coordinate pairs.
Example
params = {
  conversionType: "geo-ref",
  sr: "4326",
  strings: ["ZGQA5999999900000000","EJCE3864000012728040","NKBH1196052000273924" ]
};

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

generalize

Method
generalize(url, generalizeParameters, requestOptions){Promise<Geometry[]>}

Generalizes the input geometries using the Douglas-Peucker algorithm.

Parameters
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.

generalizeParameters GeneralizeParameters

An array of geometries to generalize and a maximum deviation. Optionally set the deviation units.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<Geometry[]> When resolved, returns an array of geometries defining the generalized geometries of the input.

intersect

Method
intersect(url, geometries, intersector, requestOptions){Promise<Geometry[]>}

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.

Parameters
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 Geometry[]

An array of points, multipoints, polylines, or polygons.

intersector Geometry

A single geometry of any type, of dimension equal to or greater than the dimension of the items in geometries.

requestOptions Object
optional

Additional options to be used for the data request.

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

labelPoints

Method
labelPoints(url, polygons, requestOptions){Promise<Point[]>}

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

Parameters
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 Object
optional

Additional options to be used for the data request.

Returns
Type Description
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

Method
lengths(url, lengthsParameters, requestOptions){Promise<object>}

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

Parameters
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.

lengthsParameters LengthsParameters

Specify the polylines and optionally the length unit and the geodesic length option.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<object> 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

Method
offset(url, offsetParameters, requestOptions){Promise<Geometry[]>}

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.

Parameters
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.

offsetParameters OffsetParameters

Set the geometries to offset, distance, and units.

requestOptions Object
optional

Additional options to be used for the data request.

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

project

Method
project(url, projectParameters, requestOptions){Promise<Geometry[]>}

Projects a set of geometries to a new spatial reference.

Parameters
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.

projectParameters ProjectParameters

The input projection parameters.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<Geometry[]> When resolved, returns an array of projected geometries.
Example
require([
  "esri/rest/geometryService", "esri/rest/support/ProjectParameters"
], function(geometryService, ProjectParameters) {

  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

Method
relation(url, relationParameters, requestOptions){Promise<Polygon[]>}

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.

Parameters
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.

relationParameters RelationParameters

The set of parameters required to perform the comparison.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<Polygon[]> When resolved, returns an array of Polygon geometries that meet the relation.
Example
require([
  "esri/rest/geometryService", "esri/rest/support/RelationParameters"
], function(geometryService, RelationParameters) {

  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

Method
reshape(url, geometry, reshaper, requestOptions){Promise<Geometry>}

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

Parameters
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 Geometry

The Polyline or Polygon to be reshaped.

reshaper Polyline

The single-part polyline that performs the reshaping.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<Geometry> When resolved, returns the Geometry defining the reshaped input feature.

simplify

Method
simplify(url, geometries, requestOptions){Promise<Geometry[]>}

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

Parameters
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 Geometry[]

The geometries to simplify.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<Geometry[]> When resolved, returns an array of the simplified geometries.
Example
geometryService.simplify(url, [polygonGraphic.geometry]).then( ... );

toGeoCoordinateString

Method
toGeoCoordinateString(url, params, requestOptions){Promise<string[]>}

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.

Parameters
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.

params Object

See the object specifications table below for the structure of the params object.

Specification

The spatial reference (or WKID of the spatial reference) of the XY-coordinates to be converted.

coordinates Number[][]

An array of XY-coordinates (in JSON format) to be converted.

conversionType String

The conversion type of the input strings.

Possible Values:"mgrs"|"usng"|"utm"|"geo-ref"|"gars"|"dms"|"ddm"|"dd"

conversionMode String
optional

Conversion options for mgrs and utm conversion types. See the ArcGIS REST API documentation for valid conversion modes and their descriptions.

numOfDigits Number
optional

The number of digits to output for each of the numerical portions in the string. The default value depends of conversionType. See the ArcGIS REST API documentation for default values.

rounding Boolean
optional
Default Value: true

If true, then numeric portions of the string are rounded to the nearest whole magnitude as specified by numOfDigits. Otherwise, numeric portions of the string are truncated. The rounding parameter applies only to conversion types mgrs, usng and geo-ref.

addSpaces Boolean
optional

If true, then spaces are added between components of the string. The addSpaces parameter applies only to conversion types mgrs, usng and utm. The default value for mgrs is false , while the default value for both usng and utm is true.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<string[]> When resolved, returns an array of well-known strings.
Example
require([
  "esri/rest/geometryService"
], function(geometryService) {

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

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

  geometryService.toGeoCoordinateString(url, params).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

Method
trimExtend(url, trimExtendParameters, requestOptions){Promise<Polyline[]>}

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.

Parameters
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.

trimExtendParameters TrimExtendParameters

Input parameters for the trimExtend operation.

requestOptions Object
optional

Additional options to be used for the data request.

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

union

Method
union(url, geometries, requestOptions){Promise<Geometry>}

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.

Parameters
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 Geometry[]

An array of the geometries to be unioned.

requestOptions Object
optional

Additional options to be used for the data request.

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

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.