Obtain service areas

The ArcGIS Runtime SDK for Java enables you to obtain the areas serviced by various facilities by providing access to the 'solveServiceArea' REST operation on a Network Layer resource. This can be done through the ServiceAreaTask class, which takes among its inputs a set of facilities for which to find service areas, and returns these areas, which you can then display on the map as graphics or use for further analysis.

Create a service area task

The first step to obtaining service areas is to create a ServiceAreaTask instance, passing into its constructor the URL of a network analysis service REST endpoint. To find the URL, you can use the ArcGIS Services Directory. The following code example uses the Service Area layer of the ESRI_NA sample service:

ServiceAreaTask task = new ServiceAreaTask(
    "http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/" + 
    "Network/USA/NAServer/Service%20Area");

Note:

The service area task can only be used with online services such as the one in the above example. To perform network analysis operations against local data, for example to support calculating service areas offline, you can use local geoprocessing services based on geoprocessing packages that contain Network Analyst tools.

Specify the task's input parameters

The ServiceAreaTask's execution method, solve, takes a ServiceAreaParameters object as input. At a minimum, you need to specify the Facilities parameter, as this determines the locations from which an area will be calculated. Facilities can be defined as a list of graphics, a URL that defines a map service query that returns points, or a layer from the network analysis service's corresponding map service. You may also want to define the Barriers parameter, which defines locations the route from the facility must avoid. This parameter is defined using the same methods as Facilities and can also be defined as a list of StopGraphics. Other commonly used parameters include DefaultBreaks, which is a list of double values, and ImpedanceAttributeName, which represents the field whose values are accumulated and broken on during the analysis. For example, if ImpedanceAttributeName was DrivingMinutes and the DefaultBreaks were 5, 10, and 15, expect three service areas to be returned representing the three areas of streets that can be reached from the facility after driving for up to 5, 10, and 15 minutes respectively.

The following code sample is an example of initializing a ServiceAreaParameters object with facilities from a graphics layer; the solve method will return polygon geometries for the calculated areas.

// get facility graphics from graphics layer
List<Graphic> facilityLocations = new ArrayList<Graphic>();
int[] graphicIds = facilityGraphicsLayer.getGraphicIDs();
for (int i = 0; i < graphicIds.length; i++) {
  facilityLocations.add(facilityGraphicsLayer.getGraphic(graphicIds[i]));
}

// specify the input facilities spatial reference 
facilityLocations.setSpatialReference(map.getSpatialReference());
	
// create parameters
ServiceAreaParameters params = new ServiceAreaParameters();
params.setFacilities(facilityLocations);
params.setDefaultBreaks(new Double[]{5.0, 10.0, 15.0});
// specify the spatial reference in which to output areas
params.setOutSpatialReference(map.getSpatialReference());

Solve the task and handle the results

Once you've initialized a ServiceAreaParameters object with the desired input, finding the service areas simply requires a call to the solve method. The ServiceAreaTask passes its results to the onCallbackmethod, which is called whenever a service area task has finished executing. The operation's results are contained in a ServiceAreaResult object. The following code builds the callback:

task.solve(params, new CallbackListener<ServiceAreaResult>() {

  @Override
  public void onError(Throwable e) {
    // handle the error
  }

  @Override
  public void onCallback(ServiceAreaResult result) {
    // process the result
    ...
  }
});

Service areas are returned in by calling getServiceAreaPolygons() (or getServiceAreaPolylines() if you called params.setReturnPolylineBarriers(true)). The following code loops through the service area graphics, getting the geometry of each to create a new graphic with appropriate symbology and add it to a graphics layer:

FeatureSet polygons = result.getServiceAreaPolygons();
for (Graphic graphic : polygons.getGraphics()) {
  graphicsLayer.addGraphic(new Graphic(graphic.getGeometry(), symbol));
}

Examples of using the route, service area, and closest facility tasks can be found as fully interactive sample apps in the ArcGIS Runtime SDK for Java sample viewer application installed with the SDK.