Skip To Content

Geometry objects

In this topic

This API includes several lightweight geometry classes. These classes can be used to display a variety of geometric shapes on a map, or they can be sent to an ArcGIS Server to perform additional analysis. While ArcGIS for Desktop and ArcGIS for Server support three-dimensional geometries, the API only supports two-dimensional geometries with X and Y values for vertices. M (Measure) and Z values are not currently supported by the API.

The following five basic geometry types are available in the API:

  • Point
  • Multipoint
  • Polyline
  • Polygon
  • Envelope

Spatial reference

All geometry objects essentially define a location or a shape on the earth's surface using one or more pairs of (X,Y) coordinates. These coordinates represent the longitude and latitude values of that location. It's important for all geometry objects to use a common basis of specifying their position so that they can be displayed correctly on a map, as well as relative to each other. Just as the metric system provides a standard way to describe measurements, coordinate systems provide a framework for describing geographic positions. Describing a location using only its latitude and longitude values without specifying the coordinate system to which those values belong is similar to describing the length of a rope using only a number without specifying the unit of measurement (meters, inches, and so on).

Learn more about coordinate systems in the ArcGIS help.

All geometry objects in the API have a spatial reference property that defines the coordinate system being used. A coordinate system can be uniquely identified either by a well-known ID (WKID) or a well-known text (WKT). Different regions in the world use different coordinate systems for a variety of historical and scientific reasons.

See Spatial references for information about supported spatial references.

Mutable versus immutable objects

Objective-C classes representing the basic geometry types in the API come in two forms: mutable and immutable. Mutable geometry objects can be modified or altered after they're created. In contrast, immutable geometry objects cannot be altered. The following table lists the Objective-C classes for both immutable and mutable versions of the basic geometry types:

Geometry typeImmutable object Mutable object
















Mutable geometry objects are useful when creating new data or editing existing data. Immutable objects are better suited for all other purposes, as they are inherently thread-safe and safeguard against inadvertent modification. Apple's Foundation framework follows a similar pattern of having separate mutable and immutable versions. Examples of these include NSDictionary, NSArray, NSData, and so on.

Most of the geometric data returned by ArcGIS Server web services is exposed as immutable geometry objects in the API. However, you can easily retrieve a mutable version of an immutable geometry by following the Objective-C convention of invoking the mutableCopy method on the object.

AGSPoint* point = ...;
AGSMutablePoint* mutable = [point mutableCopy]; 
[mutable updateWithX:20 y:20];


Point geometries represent a single point, place, or location, for example, a house in a neighborhood or a sewer in a water utility network. Larger geographic entities, such as cities, can also be represented as points on small-scale maps. Point geometries contain only a single vertex defined by a pair of X and Y coordinates that represent the defining longitude and latitude of the location.

AGSPoint* point = [AGSPoint pointWithX:10 y:10 spatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];


Multipoint geometries represent an ordered collection of points. Multipoints are more efficient to store and analyze in a geodatabase when the data consists of a large number of points. For example, Lidar data can contain observations from billions of points, and storing each as an individual point feature in a geodatabase is not practical. Storing them as a multipoint geometry allows them to be regarded as a single feature and also enables them to share a common set of attributes.

AGSMutableMultipoint multiPoint = [[AGSMutableMultipoint alloc] initWithSpatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];
[multiPoint addPoint: [AGSPoint pointWithX:10 y:10 spatialReference:nil]]; 
[multiPoint addPoint: [AGSPoint pointWithX:20 y:20 spatialReference:nil]]; 
[multiPoint addPoint: [AGSPoint pointWithX:30 y:30 spatialReference:nil]];


Polyline geometries represent the shape and location of linear features, for example, a street in a road network or a pipeline in an oil refinery. Polylines are considered multipart geometries containing one or more paths. Each path is series of connected points (vertices). Paths in a polyline can be completely disjoint, for example, in a polyline representing a discontinuous highway that has an unfinished section. Paths can also coincide at one or more vertices, for example, in a polyline representing a river and its tributaries.

AGSMutablePolyline* poly = [[AGSMutablePolyline alloc] initWithSpatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];

[poly addPathToPolyline];
[poly addPointToPath:[AGSPoint pointWithX:10 y:10 spatialReference:nil]];
[poly addPointToPath:[AGSPoint pointWithX:30 y:10 spatialReference:nil]];
[poly addPointToPath:[AGSPoint pointWithX:30 y:30 spatialReference:nil]];

[poly addPathToPolyline];
[poly addPointToPath:[AGSPoint pointWithX:20 y:10 spatialReference:nil]];
[poly addPointToPath:[AGSPoint pointWithX:20 y:-10 spatialReference:nil]];


Polygon geometries represent the shape and location of areas, for example, a country or a lake. Polygons are considered multipart geometries containing one or more rings. Each ring is a series of connected points (vertices) that enclose an area. The starting and ending points of a ring must coincide. Rings in a polygon can be completely disjoint, for example, in a polygon representing the state of Hawaii made up of eight major islands. Or one ring can be completely within another ring thus representing a hole, for example, in a polygon representing the country of South Africa with the enclave of Lesotho. However, it is not permissible for a ring to touch or intersect another ring. In such cases, it's more appropriate to have a single, large ring covering the areas of both the rings.

AGSMutablePolygon* poly = [[AGSMutablePolygon alloc] initWithSpatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];

[poly addRingToPolygon]; 
[poly addPointToRing:[AGSPoint pointWithX:10 y:10 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:30 y:10 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:30 y:30 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:10 y:30 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:10 y:10 spatialReference:nil]];

[poly addRingToPolygon]; 
[poly addPointToRing:[AGSPoint pointWithX:-10 y:-10 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:-30 y:-10 spatialReference:nil]];
[poly addPointToRing:[AGSPoint pointWithX:-30 y:-30 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:-10 y:-30 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:-10 y:-10 spatialReference:nil]];


Envelope geometries represent the shape and location of perfectly rectangular areas, for example, a soccer field. Most commonly though, envelopes are used to represent the minimum bounding box (extent) for geometries such as polygons or polylines. Consequently, envelopes are usually used for map navigation, such as zooming in to a particular neighborhood, although they can also be displayed on a map.

AGSEnvelope env = [AGSEnvelope envelopeWithXmin:10 ymin:10 xmax:30 ymax:30 spatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];

JSON representation

The geometry classes provide a way to serialize their values to JSON and also deserialize values from JSON. The JSON representation is pursuant to the ArcGIS Server REST API specification. You can use this encoding and decoding mechanism to exchange geometries with custom REST web services or to store them in files on the device.

// from json to object 
NSString* jsonPointAsString = @"{ \"x\" : -118.4 , \"y\" : -45.2 , \"spatialReference\" : {\"wkid\" : 4326} }"; 
NSDictionary *json = [jsonPointAsString AGSJSONValue]; 
AGSPoint* point = [[AGSPoint alloc] initWithJSON:json];

// from object to json 
json = [point encodeToJSON]; 
jsonPointAsString = [json AGSJSONRepresentation];


The previous code snippet uses the JSON processing library from Version 2.3 of this library is included in the ArcGIS library. See Working with JSON for more information.