Overview

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.

Spatial Reference

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.

wkid based syntax:

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

JSON Syntax

{
 "wkid" : <wkid>
 }

JSON Example

{
 "wkid" : 102100
 }

wkt based syntax:

JSON Syntax

{"wkt" : "<wkt>"}

JSON Example

{"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 contains x and y fields along with a spatialReference field. 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.

JSON Syntax

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

JSON Example

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

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

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

Multipoint

A multipoint contains an array of points, along with a spatialReference field. These fields control the interpretation of elements of the points array.

Each element of the points array is itself an array of 2 numbers. In all cases, the x coordinate is at index 0 of a point's array and the y coordinate is at index 1.

An empty multipoint has a points field with no elements. Empty points are ignored.

JSON Syntax

{

"points" : [ [ <x1>, <y1>] , [ <x2>, <y2>], ... ], 

"spatialReference" : {<spatialReference>}
}

JSON Example

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

"spatialReference" : {<spatialReference>}}

{
"points" : [  ],

"spatialReference" : {<spatialReference>}
}

Polyline

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.

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.

JSON Syntax

{


"paths" : [ 
  [ [<x11>, <y11>], [<x12>, <y12>] ], 
  [ [<x21>, <y21>], [<x22>, <y22>] ]
],
"spatialReference" : {<spatialReference>}
}

JSON Example

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

{
"paths" : [ ]
}

Polygon

A polygon contains an array of one or many exterior or interior 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. 

Rings can be embedded in the interior of other rings. Embedded rings define interior boundaries or holes within the polygon. Exterior rings are oriented in a clockwise direction while interior rings are oriented counter-clockwise. 

Polygons should have no self-intersections. This means that a segment belonging to one ring should not intersect a segment belonging to another ring. The rings of a polygon can touch each other at vertices but not along segments.     

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.

JSON Syntax

{


"rings" : [ 
  [ [<x11>, <y11>], [<x12>, <y12>], ..., [<x11>, <y11>] ], 
  [ [<x21>, <y21>], [<x22>, <y22>], ..., [<x21>, <y21>] ]
],
"spatialReference" : {<spatialReference>}
}

JSON Example

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

{
"rings" : [ ]
}

Envelope

JSON Syntax

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

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

"spatialReference" : {<spatialReference>}
}

JSON Example

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

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

{
"xmin" : "NaN"
}