ArcGIS Runtime SDK for iOS

Migrate from Google Maps to ArcGIS Runtime

If you are familiar with Google's Maps SDK for iOS and want to start using Esri's ArcGIS Runtime SDK for iOS, familiarize yourself with the differences described on this page.

Getting started

First, you can start working with the ArcGIS Runtime SDKs without having to obtain an API key. Sign up for a free developer account at developers.arcgis.com, download the SDK here and start developing.

Note:

Installation of the ArcGIS Runtime SDK for iOS via Cocoapods or manual install is covered in this guide topic.

Note:

A license key is required to deploy your application (see the deployment guide for more details).

Display a map

Here's how you display a simple map using Google's Maps SDK for iOS:

import UIKit
import GoogleMaps

class DemoViewController: UIViewController {
    override func loadView() {
        let camera = GMSCameraPosition.camera(withLatitude: 40.72, longitude: -74, zoom: 6.0)
        let mapView = GMSMapView.map(withFrame: .zero, camera: camera)
        view = mapView
    }
}

And here's the same map using the ArcGIS Runtime SDK for iOS:

import UIKit
import ArcGIS

class DemoViewController: UIViewController {
    override func loadView() {
        let mapView = AGSMapView(frame: .zero)
        mapView.map = AGSMap(basemapType: .navigationVector,
                             latitude: 40.72, longitude: -74, levelOfDetail: 6)
        view = mapView
    }
}

Key concepts:

  1. You specify the type of the map in the AGSMap constructor (and can change it later if needed). In ArcGIS this is known as your map's basemap. You can pick from the standard ArcGIS Online hosted basemaps or use custom basemap styles created with the Vector Tile Style Editor (you can also host or publish your own basemaps or make use of third party basemaps).
  2. In ArcGIS Runtime, you work with both a map (AGSMap) and a map view UI control (AGSMapView). The map defines the content to be displayed, in this case just the basemap, and the map view handles how that content is displayed and interacted with.
  3. The ArcGIS Runtime dispenses with the concept of a camera in 2D. Instead, you simply specify a geographic area to look at, top-down. You either provide a center point + scale, or an area of interest. ArcGIS Runtime refers to this specification as a viewpoint (AGSViewpoint) and there are numerous methods to set a viewpoint on a map view, with or without animation. In this case map view's viewpoint is implicitly set from the map's initial viewpoint.

Add a marker to the map

In Google's Maps SDK for iOS, you can add a marker:

class DemoViewController: UIViewController {
    override func loadView() {
        ...

        // Create and add a marker
        let marker = GMSMarker()
        marker.position = CLLocationCoordinate2D(latitude: 40.72, longitude: -74)
        marker.title = "New York"
        marker.snippet = "USA"
        marker.map = mapView

The ArcGIS Runtime SDK equivalent is to add a graphic:

class DemoViewController: UIViewController {

    // Create a graphics overlay to contain graphics.
    let overlay = AGSGraphicsOverlay()

    override func loadView() {
        ...

        // Add the graphics overlay to the map view.
        mapView.graphicsOverlays.add(overlay)

        // Create a graphic and add it to the graphics overlay.
        let graphic = AGSGraphic(geometry: AGSPointMakeWGS84(40.72, -74), 
                                 symbol: AGSSimpleMarkerSymbol(style: .circle, 
                                                               color: .red, 
                                                               size: 10),
                                 attributes: [ "city": "New York",
                                               "country": "USA" ])
        overlay.graphics.add(graphic)

Key concepts:

  1. ArcGIS Runtime uses graphics (AGSGraphic) to display ad-hoc items. A graphic is a combination of geometry (in this case a point), attribute content, and a display style (known as a symbol in ArcGIS Runtime).

    Graphics are more flexible than Google's markers. A Google marker is roughly analogous to a simple instance of a graphic with a point geometry, a simple symbol, and two attributes.

    In addition to points, polylines (AGSPolyline) and polygons (AGSPolygon) are also first class geometry types in ArcGIS and can be used to define graphics.

  2. ArcGIS Runtime does not assume that every map view needs to display graphics, hence you prepare the map view for displaying graphics by adding a graphics overlay (AGSGraphicsOverlay). Note: You add multiple graphics to a single overlay (in this case we're just adding one).
  3. In ArcGIS Runtime, items displayed on a map are grouped into collections, either graphics overlays (which we use here) or layers. This is in contrast to Google's approach of setting the map view as a property of the marker. Layers and graphics overlays provide a much more powerful model for data access and displaying data from various sources. For more on this, see the guide topics on Maps and scenes and on Layers and tables.
  4. Geometries in ArcGIS can be represented in any one of thousands of spatial references, so ArcGIS Runtime defines its own AGSPoint rather than using CLLocationCoordinate2D (which represents a point in a specific spatial reference, WGS 84). AGSPointMakeWGS84() is a helper function to create a WGS 84 AGSPoint from a latitude & longitude.

Display Information

In ArcGIS Runtime, you display information associated with a map location with a callout (AGSCallout), and you must explicitly display or dismiss it.

To show a callout when tapping a graphic:

  1. Make sure that the DemoViewController can respond to map view interactions by declaring conformance to AGSGeoViewTouchDelegate and setting the AGSMapView.touchDelegate appropriately.
  2. Implement the geoView(didTapAtScreenPoint:mapPoint) delegate handler.
  3. Tell ArcGIS Runtime to identify any graphics where the user tapped the map.
  4. Display a suitable callout if necessary.
class DemoViewController: UIViewController, AGSGeoViewTouchDelegate {
    override func loadView() {
        ...

        // Set the map view's touch delegate.
        mapView.touchDelegate = self
    }

    // Handle the AGSGeoViewTouchDelegate tap event.
    func geoView(_ geoView: AGSGeoView, didTapAtScreenPoint screenPoint: CGPoint, mapPoint: AGSPoint) {

        // Identify which graphic, if any, the user tapped on.
        geoView.identify(overlay, screenPoint: screenPoint, tolerance: 20, returnPopupsOnly: false) { result in

            if let tappedGraphic = result.graphics.first {
                // Populate the configure the callout.
                geoView.callout.title = tappedGraphic.attributes["city"] as? String
                geoView.callout.detail = tappedGraphic.attributes["country"] as? String
                geoView.callout.isAccessoryButtonHidden = true

                // Show the callout.
                geoView.callout.show(for: tappedGraphic, tapLocation: mapPoint, animated: true)
            } else {
                // The user didn't tap on a graphic, so dismiss any existing callout.
                geoView.callout.dismiss()
            }
        }
    }

Key concepts:

  1. ArcGIS Runtime makes no assumptions about how you want to handle interactions with the contents of the map. When you are notified of an interaction by the touch delegate, it's up to you to interpret it.
  2. ArcGIS Runtime does provide convenient APIs for chaining parameters from delegate events into actions commonly triggered by those events. In this case, we want to identify what was tapped.
  3. Since a graphic is generic, we need to inspect its attributes dictionary to populate the callout's display fields.
  4. You might wonder why the delegate is not AGSMapViewTouchDelegate. ArcGIS Runtime provides both 2D support though AGSMapView and 3D support through AGSSceneView. Both respond to the same interactions and both are derived from AGSGeoView, hence the touch delegate name.

More info

To learn more about working with ArcGIS Runtime, check out theGuides, Reference Documentation, Samples App and DevLabs, in particular the following: