Working with JSON

JavaScript Object Notation (JSON) has quickly become the preferred standard for exchanging data with web services.

JSON is easy for humans to read and write, and easy for machines to parse and generate. Most importantly, it is lightweight and compact, which has led to its widespread adoption over XML, which can be verbose.

ArcGIS Server provides both SOAP- and REST-based web services that expose mapping and geospatial capabilities to clients. Esri's web and mobile clients communicate with ArcGIS Server REST web services and exchange information with them using JSON.

JSON Library

The API uses the popular, open source json-framework to parse and generate JSON. Version 2.3 of json-framework is included with the ArcGIS library and available for you to use in your applications. You don't need to download any additional libraries to handle JSON. Simply import the ArcGIS framework, and start using the classes provided by json-framework.


The API classes, categories, and category methods of the json-framework library included with the ArcGIS library have been namespaced with an "AGS" prefix to prevent conflicts if additional libraries in your project also bundle json-framework.

Consider the following example describing a person entity in JSON:


The following code snippet shows how you can parse a JSON string to an NSDictionary and access its values:

//Quotes need to be escaped
let person:NSString = "{\"firstName\":\"Jane\",\"lastName\":\"Doe\",\"age\":27}"
//convert to json dictionary
let jsonDict = person.ags_JSONValue() as NSDictionary
let firstName = jsonDict.objectForKey("firstName") as String
let age = jsonDict.objectForKey("age") as String

The following code snippet shows how you can convert a dictionary into a JSON string:

//dictionary from above
let jsonDict = ...
//convert back to json string
let jsonStr = jsonDict.ags_JSONRepresentation()

ArcGIS classes are JSON friendly

Most classes in the API adopt the AGSCoding protocol. By doing so, they provide an easy way to decode their state from JSON and encode their state to JSON. The JSON syntax for these classes is defined by the ArcGIS Server REST API.

The following code snippet shows how to convert a JSON string for a point into an AGSPoint object, then back to a JSON string. The syntax for the JSON string is borrowed from the Geometry Objects section of the REST API documentation.

// from json to object
let jsonPointAsString:NSString = "{ \"x\" : -118.4 , \"y\" : -45.2 , \"spatialReference\" : {\"wkid\" : 4326} }"
let json:NSDictionary = jsonPointAsString.ags_JSONValue() as [NSObject:AnyObject]
let point = AGSPoint(JSON: json)
// from object to json
json = point.encodeToJSON()
jsonPointAsString = json.ags_JSONRepresentation()

Invoking REST web services

While building iOS applications, you will often need to use web services. You may need to invoke your custom web services or REST-based Server Object Extensions (SOEs) for ArcGIS Server to implement novel GIS capabilities in your application. Other times, you may rely on or third party web services such as Picasa or Yahoo to access photos, or retrieve weather information. Most of these web services are REST based and have the ability to return responses in JSON.

The API makes it convenient to invoke REST-based web services that use JSON to exchange information. All you need to do is initialize an object of AGSJSONRequestOperation with a URL to the web service, and optionally a dictionary of parameters to send. If the web service is secured, you can also specify the credentials that should be used to access the web service.

//The URL of the webservice
let url:NSURL = ...
//The parameter to pass to the webservice
let params:NSDictionary = ...
let jsonOp = AGSJSONRequestOperation(URL: url, queryParameters: params)
//The credentials to access the webservice with
jsonOp.credential = ...

Next, set the target-action pair so that a method on one of your objects is invoked when the web service returns a response. = self
jsonOp.action = "operation:didSucceedWithResponse:"

It is also a good practice to set errorAction so that your object is notified if an error is encountered while invoking the web service.

jsonOp.errorAction = "operation:didFailWithError:"

The following code is an example of how the action and error action methods can be implemented:

func operation(op:NSOperation, didSucceedWithResponse json:NSDictionary) {
func operation(op:NSOperation, didFailWithError error:NSError) {

Finally, add the AGSJSONRequestOperation object to an operation queue to invoke the web service request in the background.

let queue = NSOperationQueue()

Behind the scenes, the operation fires a request to the URL over an HTTP or HTTPS connection as specified in the URL. The operation automatically appends the query parameters to the URL and includes the authentication information, if provided, in the request header.


By default, the web service is invoked using HTTP GET semantics; however, if you want to use POST, you can do so by using the initWithURL:resource:queryParameters:doPOST: method while creating an AGSJSONRequestOperation object.

When the web service returns a response, the action method on the target object is invoked and the response JSON payload is passed along. If the web service encounters an error, the errorAction method is invoked along with the error information.