Overview

This topic defines the JSON formats of the geometry and spatial reference objects as returned by ArcGIS REST API. ArcGIS REST API supports the following geometry types:

• Point
• Multipoint
• Polyline
• Polygon
• Envelope

These geometry types (associated with the geometryType parameter and response property) can act as accepted values for operations, such as the Difference operation for geometry service resources or the feature layer-level Query operation for feature service layers, or in the properties of a layer resource.

Starting at 10.1, geometries containing m- and z-values are supported.

Starting at 10.3, polylines and polygons with curves are supported. See the sections on JSON curve object, Polyline with curve, and Polygon with curve for more information.

Spatial reference

A spatial reference can be defined using a well-known ID (wkid) or well-known text (wkt). The default tolerance and resolution values for the associated coordinate system are used. The xy and z tolerance values are 1 mm or the equivalent in the unit of the coordinate system. If the coordinate system uses feet, the tolerance is 0.00328083333 ft. The resolution values are 10x smaller or 1/10 the tolerance values. Thus, 0.0001 m or 0.0003280833333 ft. For geographic coordinate systems using degrees, the equivalent of a mm at the equator is used.

The well-known ID (WKID) 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.

An additional property, latestWkid, identifies the current WKID value (as of a given software release) associated with the same spatial reference.

A spatial reference 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, the entire SR will be serialized with only the wkt property.

Starting at 10.3, Image Service supports image coordinate systems. See Image Coordinate System for more information.

{
  "wkid": <wkid>, 
  "latestWkid": <wkid>, //This property can be omitted
  "vcsWkid": <wkid>,  
  "latestVcsWkid": <wkid> //This property can be omitted
}

{
  "wkid": 102100,
  "latestWkid": 3857
}

{"wkt": "<wkt>"}

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

Point

A point (specified as esriGeometryPoint) 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>
  }
}

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

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

//Example one
{
  "x": null,
  "spatialReference": {
    "wkid": 4326
  }
}

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

Multipoint

A multipoint (specified as esriGeometryMultipoint) 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 two, three, or four numbers. It will have two elements for 2D points, two or three elements for 2D points with Ms, three elements for 3D points, and three or four 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>
  }
}

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

{
  "hasZ": true, 
  "points": [
    [
      -97.06138,
      32.837,35.0
    ],
    [
      -97.06133,
      32.836,35.1
    ],
    [
      -97.06124,
      32.834,35.2
    ]
  ],
  "spatialReference": {
    "wkid": 4326
  }
}

{
  "points": [],
  "spatialReference": {
    "wkid": 4326
  }
}

Polyline

A polyline (specified as esriGeometryPolyline) contains an array of paths or curvePaths and a spatialReference. For polylines with curvePaths, see the sections on JSON curve object and Polyline with curve. 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.

See 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>],
      [<x1N>, <y1N>, <z1N>, <m1N>]
    ],
    [
      [<xk1>, <yk1>, <zk1>, <mk1>],
      [<xkM>, <ykM>, <zkM>, <mkM>]
    ]
  ],
  "spatialReference": {<spatialReference>}
}

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

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

{
  "paths": [ ]
}

Polygon

A polygon (specified as esriGeometryPolygon) contains an array of rings or curveRings and a spatialReference. For polygons with curveRings, see the sections on JSON curve object and Polygon with curve. 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.

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

Polygons should be topologically simple. Exterior rings are oriented clockwise, while holes are oriented counterclockwise. Rings can touch at a vertex or self-touch at a vertex, but there should be no other intersections. Polygons returned by services are topologically simple.

When drawing a polygon, use the even-odd fill rule. The even-odd fill rule will guarantee that the polygon will draw correctly even if the ring orientation is not as described above.

{
  "hasZ": <true | false>,
  "hasM": <true | false>,
  "rings": [
    [
      [<x11>, <y11>, <z11>, <m11>],
      [<x1N>, <y1N>, <z1N>, <m1N>]
    ],
    [
      [<xk1>, <yk1>, <zk1>, <mk1>],
      [<xkM>, <ykM>, <zkM>, <mkM>]
    ]
  ],
  "spatialReference": {<spatialReference>}
}

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

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

{
  "rings": [ ]
}

JSON curve object

At 10.3, a circular arc, an elliptical arc, and a Bézier curve can be represented as a JSON curve object. A curve object is a segment in a polyline or polygon. It cannot be used as a stand-alone object.

A curve object is given in a compact "curve to" manner with the first element representing the "to" point or end point. The "from" point is derived from the previous segment or curve object.

The supported curve objects are as follows:

• Circular Arc "c"
  • Defined by an end point and an interior point
  • {"c": [[x, y, <z>, <m>],[interior_x, interior_y]]}
• Arc "a"
  • Elliptic Arc
  • Defined by the following:
    • End point
    • Center point
    • Minor: 1 if the arc is minor (less than 180 degrees), 0 if the arc is major
    • Clockwise: 1 if the arc is oriented clockwise, 0 if the arc is oriented counterclockwise
    • Rotation: angle of rotation of major axis in radians with a positive value being counterclockwise
    • Axis: length of the semi-major axis
    • Ratio: ratio of the minor axis to major axis
    • {"a": [[x, y, <z>, <m>],[center_x, center_y], minor, clockwise, rotation, axis, ratio]}
• Circular Arc (format used prior to 10.3)
  • Special case of elliptic arc
  • Exclude rotation, axis, ratio
  • {"a": [[x, y, <z>, <m>],[center_x, center_y],minor, clockwise]}
• Bézier curve "b"
  • Defined by an end point and two control points
  • {"b": [[x, y, <z>, <m>], [x, y], [x, y]]}

Polyline with curves

A polyline with curves contains an array of curvePaths and an optional spatialReference. See the section on JSON curve object. If you need to interoperate with a new (10.3 or later) and an older server (prior to 10.3), you can pass two variants in the JSON object using curvePaths for the new server and paths for the old server, which are interpreted as line segments.

Each curve path is represented as an array containing points and curve objects.

{
  "curvePaths": [start point, next point or curve object]
}

{
  "curvePaths": [
    [
      [0, 0],
      {
        "c": [
          [3, 3],
          [1, 4]
        ]
      }
    ]
  ]
}

{
  "curvePaths": [
    [
      [6,3],
      [5,3],
      {
        "b": [
          [3, 2],
          [6, 1],
          [2, 4]
        ]
      },
      [1, 2],
      {
        "a": [
          [0, 2],
          [0, 3],
        ]
      }
    ]
  ]
}

Polygon with curves

A polygon with curves contains an array of curveRings and an optional spatialReference. Similar to polylines, if you need to interoperate with a new (10.3 or later) and an older server (prior to 10.3), pass two variants in the JSON object using curveRings for the new server and rings for the old server, which are interpreted as line segments.

Each curve ring is represented as an array containing points and curve objects.

{
  "curveRings": [start point, next point or curve object]
}

{
  "hasM":true,
  "curveRings": [
    [
      [11, 11, 1],
      [10, 10, 2],
      [10, 11, 3],
      [11, 11, 4],
      {
        "b": [
          [15, 15, 2],
          [10, 17],
          [18, 20]
        ]
      },
      [11, 11, 4]
    ],
    [
      [15, 15, 1],
      {
        "c": [
          [20, 16, 3],
          [20, 14]
        ]
      },
      [15, 15, 3]
    ]
  ],
  "rings":[
    [
      [11, 11, 1],
      [10, 10, 2],
      [10, 11, 3],
      [11, 11, 4]
    ],
    [
      [15, 15, 1],
      [11, 11, 2],
      [12, 15.5],
      [15.4, 17.3],
      [15, 15, 3]
    ],
    [
      [20, 16 ,1],
      [20, 14],
      [17.6, 12.5],
      [15, 15, 2],
      [20, 16, 3]
    ]
  ]
}

Envelope

An envelope (specified as esriGeometryEnvelope) is a rectangle defined by a range of values for each coordinate and attribute. It also has a 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>
  }
}

{
  "xmin": -109.55,
  "ymin": 25.76,
  "xmax": -86.39,
  "ymax": 49.94,
  "spatialReference": {
    "wkid": 4326
  }
}

{
  "xmin": -109.55,
  "ymin": 25.76,
  "xmax": -86.39,
  "ymax": 49.94, 
  "zmin": -12.0,
  "zmax": 13.3, 
  "spatialReference": {
    "wkid": 4326
  }
}

//Example one
{
  "xmin": null,
  "spatialReference": {
    "wkid": 4326
  }
}

//Example two
{
  "xmin": "NaN"
}