Obtaining service areas for facilities

The ArcGIS Runtime for Java API 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 Service Area task, 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 or use for further analysis.

Initializing a Service Area task

To initialize a Service Area task, declare a ServiceAreaTask object, instantiate it with the new keyword, and pass the URL of a network analysis service REST endpoint to the constructor. To find the URL, you can use the ArcGIS Services Directory. See the Discovering services topic for more information. This example uses the Service Area layer of the ESRI_NA service. The runtime local server does not support local network analysis services and therefore the Service Area task can only be used with online services. To perform routing operations against local data, for example to support offline or disconnected usage, you can use local geoprocessing services based on geoprocessing packages which contain Network Analyst tools.

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

Specifying a Service Area task's input parameters

The Service Area task's execution method, solveAsync, takes a ServiceAreaTaskParameters object as input. At a minimum, you will need to specify the Facilities parameter, as this determines the locations from which an area will be calculated. Facilities may be defined as a list of Graphics, a URL which defines a map service query that returns Points or a Layer from the network analysis service's corresponding map service. Often, you may also want to define the Barriers parameter, which defines locations 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, ImpedanceAttributeName was 'DrivingMinutes' and the DefaultBreaks were 5, 10 and 15, then you might 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.

Below is an example of initializing a ServiceAreaTaskParameters object with facilities from a GraphicsLayer, the solveAsync method will return polygon geometry 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 since it is different from that of the network analysis service
facilityLocations.setSpatialReference(map.getSpatialReference());
		
// create parameters
ServiceAreaTaskParameters params = new ServiceAreaTaskParameters();
params.setFacilities(facilityLocations);
params.setDefaultBreaks(new Double[]{5.0, 10.0, 15.0});
// specify the spatial reference in which to output areas since it is different from that of the network analysis service
parameters.setOutSpatialReference(map.getSpatialReference());

Executing a Service Area task and handling results

Once you have initialized a ServiceAreaTaskParameters object with the desired input, finding the service areas simply requires a call to the solveAsync method. The Service Area task passes its results to the onCallback method, which is called whenever a route operation completes. The operation's results are contained in a ServiceAreaResult object. The code below builds the callback:

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

            @Override
            public void onError(Throwable e) {
                e.printStackTrace();
            }

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

Service Areas are returned in the ServiceAreaPolygons (or ServiceAreaPolylines field if you have called params.setReturnPolylineBarriers(true)).The code below steps through the service area graphics, getting the geometry and adding a corresponding Graphic with a single symbol to a GraphicsLayer.

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 in the ArcGIS Runtime for Java Sample application.