Geometry Objects

This document defines the JSON formats of the geometry and spatial reference objects as returned by the REST API. The REST API supports 5 geometry types - points, multipoints, polylines, polygons and envelopes. Starting at 10.1 geometries containing m and z values are supported.

The spatial reference can be defined using a well-known ID (`wkid`

) or
well-known text (`wkt`

). The well-known id for a given spatial reference can occasionally change.
For example, the WGS 1984 Web Mercator (Auxiliary Sphere) projection was originally assigned wkid 102100, but was later
changed to 3857. To ensure backward compatibility with older spatial data servers, the JSON `wkid`

property
will always be the value that was originally assigned to an SR when it was created.

Starting at 10.1 an additional property, `latestWkid`

, will identify the current wkid value (as of a given software release) associated with the same SR.

Also new at 10.1 an SR can optionally include a definition for a vertical coordinate system (VCS), which is used to interpret the z values
of a geometry. A VCS defines units of measure, the location of z=0, and whether the positive vertical direction is up or down. When a vertical coordinate system is specified with a
wkid, the same caveat as mentioned above applies. There are two vcs wkid properties: `vcsWkid`

and `latestVcsWkid`

.
A VCS WKT can also be embedded in the string value of the `wkt`

property. In other words, the WKT syntax can be used to define
an SR with both horizontal and vertical components in one string. If either part of an SR is custom then the entire SR will be serialized with
only the wkt property.

** wkid based syntax**:

For a list of valid WKID values, see Projected coordinate Systems, Geographic coordinate Systems and Vertical coordinate Systems.

{ "wkid" : <wkid>,

"latestWkid" : <wkid>,

"vcsWkid" : <wkid>,

"latestVcsWkid" : <wkid> }

{ "wkid" : 102100,

"latestWkid" : 3857 }

** wkt based syntax**:

{"wkt" : "<wkt>"}

{"wkt" : "GEOGCS[\"GCS_WGS_1984\",DATUM[\"D_WGS_1984\",SPHEROID[\"WGS_1984\",6378137,298.257223563]],PRIMEM[\"Greenwich\",0],UNIT[\"Degree\",0.017453292519943295]]"}

A point contains `x`

and `y`

fields along with a
`spatialReference`

field. A point can also contain `m`

and
`z`

fields. A point is empty
when its `x`

field is present and has the value `null`

or the string "NaN".
An empty point has no location in space.

{

"x" : <x>, "y" : <y>, "z" : <z>, "m" : <m>, "spatialReference" : {<spatialReference>}

}

A 2D point

{

"x" : -118.15, "y" : 33.80, "spatialReference" : {"wkid" : 4326}

}

A 3D point

{

"x" : -118.15, "y" : 33.80, "z" : 10.0, "spatialReference" : {"wkid" : 4326}

}

An empty point

{ "x" : null, "spatialReference" : {"wkid" : 4326}

}

An empty point

{ "x" : "NaN", "y" : 22.2, "spatialReference" : {"wkid" : 4326}

}

A multipoint contains an array of `points`

, along with a `spatialReference`

field. A multipoint can also have boolean-valued `hasZ`

and `hasM`

fields. These fields control the interpretation of elements of the `points`

array.
Omitting an `hasZ`

or `hasM`

field is equivalent to setting it to false.

Each element of the
`points`

array is itself an array of 2, 3 or 4 numbers. It will have two elements for 2D points, 2 or 3 elements
for 2D points with Ms, 3 elements for 3D points,
and 3 or 4 elements for 3D points with Ms. In all cases, the x coordinate is at index 0 of a point's array and the y coordinate is
at index 1. For 2D points with Ms, the m coordinate, if present, is at index 2. For 3D points, the Z coordinate is required and is at index 2. For 3D
points with Ms, the Z coordinate is at index 2 and the M coordinate, if present, is at index 3.

An empty multipoint has a `points`

field with no elements. Empty points are ignored.

{

"hasM" : true | false,

"hasZ" : true | false,

"points" : [ [ <x1>, <y1>, <z1>, <m1> ] , [ <x2>, <y2>, <z2>, <m2> ], ... ],

"spatialReference" : {<spatialReference>}

}

A 2D multipoint

{ "points" : [ [-97.06138,32.837], [-97.06133,32.836], [-97.06124,32.834], [-97.06127,32.832] ],

"spatialReference" : {<spatialReference>}}

A 3D multipoint

{

"hasZ" : true,

"points" : [ [-97.06138,32.837,35.0], [-97.06133,32.836,35.1], [-97.06124,32.834,35.2], [-97.06127,32.832,35.3] ],

"spatialReference" : {"wkid" : 4326}

}

An empty multipoint

{ "points" : [ ],

"spatialReference" : {"wkid" : 4326}

}

A polyline contains an array of `paths`

and a
`spatialReference`

. Each path is represented as an array of
points, and each point in the path is represented as an array of numbers. A polyline can also have
boolean-valued `hasM`

and `hasZ`

fields.

Refer to the description of multipoints for details on how the point arrays are interpreted.

An empty polyline is represented with an empty array for the `paths`

field. Nulls and/or NaNs embedded in an otherwise defined coordinate stream for polylines/polygons is a syntax error.

{

"hasZ" : true | false,

"hasM" : true | false,

"paths" : [

[ [<x11>, <y11>, <z11>, <m11>], [<x12>, <y12>, <z12>, <m12>] ],

[ [<x21>, <y21>, <z21>, <m21>], [<x22>, <y22>, <z22>, <m22>] ]

],

"spatialReference" : {<spatialReference>}

}

A 2D polyline

{

"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}

}

A 2D polyline with Ms (note that the 2nd path does not have ms defined)

{

"hasM" : true,

"paths" : [

[ [-97.06138,32.837,5], [-97.06133,32.836,6], [-97.06124,32.834,7], [-97.06127,32.832,8] ],

[ [-97.06326,32.759], [-97.06298,32.755] ]

],

"spatialReference" : {"wkid" : 4326}

}

An empty polyline

{ "paths" : [ ]

}

A polygon contains an array of `rings`

and a
`spatialReference`

. Each ring is represented as an array of
points. The first point of each ring is always the same as the last point.
Each point in the ring is represented as an array of numbers. A polygon can also have
boolean-valued `hasM`

and `hasZ`

fields.

Refer to the description of multipoints for details on how the point arrays are interpreted.

An empty polygon is represented with an empty array for the `rings`

field. Nulls and/or NaNs embedded in an otherwise defined coordinate stream for polylines/polygons is a syntax error.

{

"hasZ" : true | false,

"hasM" : true | false,

"rings" : [

[ [<x11>, <y11>, <z11>, <m11>], [<x12>, <y12>, <z12>, <m12>], ..., [<x11>, <y11>, <z11>, <m11>] ],

[ [<x21>, <y21>, <z21>, <m21>], [<x22>, <y22>, <z22>, <m22>], ..., [<x21>, <y21>, <z21>, <m21>] ]

],

"spatialReference" : {<spatialReference>}

}

A 2D polygon

{

"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}

}

A 3D polygon with Ms (note that the second ring does not have Ms defined for it)

{

"hasZ" : true,

"hasM" : true,

"rings" : [

[ [-97.06138, 32.837, 35.1, 4], [-97.06133, 32.836, 35.2, 4.1], [-97.06124, 32.834, 35.3, 4.2], [-97.06127, 32.832, 35.2, 44.3], [-97.06138, 32.837, 35.1, 4] ],

[ [-97.06326, 32.759, 35.4], [-97.06298, 32.755, 35.5], [-97.06153, 32.749, 35.6], [-97.06326, 32.759, 35.4] ]

],

"spatialReference" : {"wkid" : 4326}

}

An empty polygon

{ "rings" : [ ] }

`spatialReference`

field. The fields for the
z and m ranges are optional.
An empty envelope has no location in space and is defined by the presence of an `xmin`

field a `null`

value or a "NaN" string.
{

"xmin" : <xmin>, "ymin" : <ymin>,

"xmax" : <xmax>, "ymax" : <ymax>,

"zmin" : <zmin>, "zmax" : <zmax>,

"mmin" : <mmin>, "mmax" : <mmax>,

"spatialReference" : {<spatialReference>}

}

A 2D envelope

{

"xmin" : -109.55, "ymin" : 25.76, "xmax" : -86.39, "ymax" : 49.94,

"spatialReference" : {"wkid" : 4326}

}

A 3D envelope

{

"xmin" : -109.55, "ymin" : 25.76, "xmax" : -86.39, "ymax" : 49.94, "zmin" : -12.0, "zmax" : 13.3,

"spatialReference" : {"wkid" : 4326}

}

An empty envelope

{

"xmin" : null,

"spatialReference" : {"wkid" : 4326}

}

An empty envelope

{

"xmin" : "NaN"

}