ArcGIS Runtime SDK for Android

Migrate from Google Maps to ArcGIS Runtime

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

Get started

First, you can start working with 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:

To install ArcGIS Runtime SDK for Android via Bintray or manual install, see Install the SDK.

Note:

After signing up for a free developer account, nothing else is required for you to start developing apps with the ArcGIS Runtime SDK for Android. A license key is required to deploy your ArcGIS Runtime app (see Deploy your app for details).

Display a map

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

import android.os.Bundle;
import android.support.v4.app.FragmentActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;

public class MapsActivity extends FragmentActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        LatLng newYork = new LatLng( 40.72, -74.00);
        mMap.moveCamera(CameraUpdateFactory.newLatLng(newYork));
    }
}

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

import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;
import com.esri.arcgisruntime.mapping.ArcGISMap;
import com.esri.arcgisruntime.mapping.Basemap;
import com.esri.arcgisruntime.mapping.view.MapView;

public class MapsActivity extends AppCompatActivity {

    private MapView mMapView;
  
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);

        mMapView = (MapView) findViewById(R.id.mapView);

        if (mMapView != null) {
            Basemap.Type basemapType = Basemap.Type.TOPOGRAPHIC_VECTOR;
            final ArcGISMap map = new ArcGISMap(basemapType, 40.72, -74.00, 11);
            mMapView.setMap(map);
        }
    }

}

The activity_maps.xml file for the ArcGIS Runtime app looks like this:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/activity_main"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    
    <com.esri.arcgisruntime.mapping.view.MapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" >
    </com.esri.arcgisruntime.mapping.view.MapView>
</RelativeLayout>

Key concepts:

  1. You specify the type of the map in the ArcGISMap 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 (ArcGISMap) and a map view UI control (MapView). 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. ArcGIS Runtime dispenses with the concept of a camera in 2D. Instead, you specify a geographic area to look at, top-down. You either provide a center point and scale or an area of interest. ArcGIS Runtime refers to this specification as a Viewpoint and there are numerous methods to set a viewpoint on a map view, with or without animation. In the above example, the 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 Android, you can add a marker in onMapReady:

@Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        LatLng newYork = new LatLng( 40.72, -74.00);
        mMap.addMarker(new MarkerOptions().position(newYork).title("Marker in New York"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(newYork));
    }

The ArcGIS Runtime SDK equivalent is to add a graphic to a graphic overlay

  1. Define a GraphicsOverlay as a member variable.
  2. After the ArcGISMap object is defined and before it is set to the MapView, add the following code.
public class MapsActivity extends AppCompatActivity {
        
        private MapView mMapView;
        private GraphicsOverlay graphicsOverlay = new GraphicsOverlay();
    
    ...
    
        Basemap.Type basemapType = Basemap.Type.TOPOGRAPHIC_VECTOR;
        final ArcGISMap map = new ArcGISMap(basemapType, 40.72, -74.00, 11);

        // Add the overlay to map view
        mMapView.getGraphicsOverlays().add(graphicsOverlay);

        // Create the geographic location for New York, New York, USA
        Point marker = new Point(-74, 40.72, SpatialReferences.getWgs84());

        // Create the marker symbol to be displayed at the location
        SimpleMarkerSymbol sms =
            new SimpleMarkerSymbol(SimpleMarkerSymbol.Style.CIRCLE,  Color.RED, 20);

        // Create attributes for the graphic
        Map attributes = new HashMap();
        attributes.put("city","New York");
        attributes.put("country","USA");


        // Add the point, symbol and attributes to the graphics overlay
        Graphic g = new Graphic(marker, attributes, sms );
        graphicsOverlay.getGraphics().add(g);

Key concepts:

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

    ArcGIS Runtime's 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 (Polyline) and polygons (Polygon) are also first class geometry types in ArcGIS and can be used to define graphics.

  2. ArcGIS Runtime doesn't assume that every map view needs to display graphics. As a result, you prepare the map view for displaying graphics by adding a graphics overlay (GraphicsOverlay). Note: You add multiple graphics to a single overlay (in this case we're adding only one graphic).
  3. In ArcGIS Runtime, content displayed on a map is grouped into collections, either graphics overlays in the map view (which we use here) or layers in a map. This approach is in contrast to Google's 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 information, see Maps and scenes and Layers and tables.

Display information

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

To show a callout when tapping a graphic:

  1. Make sure that the MapView can respond to touch events by setting an OnTouchListener to the MapView
  2. Override the onSingleTapConfirmed method on DefaultMapViewOnTouchListener
  3. Tell ArcGIS Runtime to identify any graphics where the user tapped the map
  4. Display a suitable callout if necessary

Just before the line of code that sets the ArcGISMap to the MapView, add the following:

mMapView.setOnTouchListener(new DefaultMapViewOnTouchListener(this,mMapView){
                public boolean onSingleTapConfirmed(MotionEvent e) {
                    final android.graphics.Point screenPoint = new android.graphics.Point((int) e.getX(), (int) e.getY());


                    // identify graphics on the graphics overlay
                    final ListenableFuture<IdentifyGraphicsOverlayResult> identifyGraphic = 
                             mMapView.identifyGraphicsOverlayAsync(graphicsOverlay, screenPoint, 10.0, false, 2);

                    identifyGraphic.addDoneListener(new Runnable() {

                        public void run() {
                            try {
                                IdentifyGraphicsOverlayResult grOverlayResult = identifyGraphic.get();
                                // get the list of graphics returned by identify graphic overlay
                                List<Graphic> graphics = grOverlayResult.getGraphics();
                                Callout mCallout = mMapView.getCallout();
                                
                                if (mCallout.isShowing()) {
                                    mCallout.dismiss();
                                }
                                
                                if (!graphics.isEmpty()) {
                                    // get callout, set content and show
                                    String city = graphics.get(0).getAttributes().get("city").toString();
                                    String country = graphics.get(0).getAttributes().get("country").toString();
                                    TextView calloutContent = new TextView(getApplicationContext());
                                    calloutContent.setText(city + ", " + country);
                                    Point mapPoint = mMapView.screenToLocation(screenPoint);

                                    mCallout.setLocation(mapPoint);
                                    mCallout.setContent(calloutContent);
                                    mCallout.show();

                                }
                            } catch (InterruptedException | ExecutionException ie) {
                                ie.printStackTrace();
                            }

                        }
                    });

                    return super.onSingleTapConfirmed(e);
                }
            });

Key concepts:

  1. ArcGIS Runtime makes no assumptions about how you want to handle interactions with the contents of the map. When you're notified of an interaction by the touch listener, it's up to you to interpret it
  2. Since a graphic is generic, we need to inspect its attribute dictionary to populate the callout's display fields

More info

For additional information about working with ArcGIS Runtime, see the developer guide, reference documentation, samples, and Tutorials, in particular the following: