GP service example: Finding nearby features over a street network

Complexity: Advanced Data Requirement: ArcGIS Tutorial Data Setup Data Path: C:\ArcGIS\ArcTutor\GP Service Examples\ClosestFacilities Goal: Author, publish, and use a geoprocessing service that finds features closest to a given location based on shortest route on a street network.

Folder	ClosestFacilities
Purpose	Finds a given number of closest libraries from a starting location based on the travel time along a street network, calculates the shortest route to each of the closest library, and generates driving directions in a text file.
Services	SanFranciscoBaseMap (map service) ClosestFacilitiesService (geoprocessing service)
Geoprocessing task	Find Nearby Libraries
Inputs	One or more user-digitized points and the number of closest libraries to find.
Outputs	The closest libraries. The shortest routes between the user-specified points and each of the closest libraries based on the travel time. A text file containing driving directions for each route.
Data	Uses a street network dataset and a feature class containing all the library locations in the San Francisco area provided in the ToolData folder.
Extensions	Network Analyst
Of note	Demonstrates how to use a solved network analysis layer for further analysis.

About this example

Corresponding folder

C:\arcgis\ArcTutor\GP Service Examples\ClosestFacilities contains the completed models and data.

About this example

The ClosestFacilitiesService service created in this example shows you how to publish a geoprocessing task that performs a closest facility analysis on a street network. The Find Nearby Libraries task determines the shortest routes to a user-specified number of closest libraries from the given points based on travel time along the street network. The task outputs the routes and driving directions to the closest libraries.

Example output from Find Nearby Libraries task

Data

The data for this example comes from C:\arcgis\ArcTutor\GP Service Examples\ClosestFacilities.

ClosestFacilities folder contents

Network dataset

The ToolData folder contains a file geodatabase, SanFrancisco.gdb. This geodatabase contains a network dataset, Streets_ND, within the Transportation feature dataset. This network dataset models the street network for the San Francisco area. It provides a network attribute, TravelTime, which indicates the time taken to travel each street segment.

Basemap

The basemap layer within SanFranciscoBaseMap.mxd has a layer, Streets, as illustrated below. This layer shows the extent of the network dataset. This means that this task can be used to determine the nearby libraries only in this extent.

San Francisco basemap showing the network dataset extent

SanFranciscoBaseMap is published as a map service.

Toolbox and map document

The toolbox for the geoprocessing service is ClosestFacilitiesService, and the source map document for the service is ClosestFacilitiesService.mxd. ClosestFacilitiesService.mxd contains the following four source data layers and the Find Nearby Libraries tool layer:

• Streets_ND—The network dataset.
• Library—Feature layer containing the locations of all the libraries in the San Francisco area
• ClosestLibrariesSymbology—Feature layer that defines the symbology for the output libraries
• OutputRoutesSymbology—Feature layer that defines the symbology for the output routes

Model

Model overview

The Find Nearby Libraries model is illustrated below. There are two input variables:

• Input Locations, which are the user-specified points from which the closest libraries are found
• Number of libraries to find

The model creates a closest facility network analysis layer; adds the library locations from the library feature layer as facilities; adds the user-specified locations as incidents; and performs a solve to determine the routes to the closest libraries, generate driving directions, and find only those libraries that are included in the routes from all the libraries that are loaded as facilities.

Element	Type	Description
Street Network	Network dataset layer	The network dataset layer.
Number of libraries to find	Long, input parameter	The number of libraries to find for each input location.
Make Closest Facility Layer	Tool	Creates a closest facility network analysis layer. This layer contains both data and properties that determine how the closest facilities will be calculated, along with the results of the calculation.
Closest Facility	Network Analyst layer	Closest facility layer.
Library	Feature Layer	The point feature class containing all the library locations. The positions of these points on the street network are already calculated as described in the section Precalculating network locations for libraries.
Add Locations (Libraries)	Tool	Adds the library locations as facilities to the closest facility layer.
Closest Facility (1)	Network Analyst layer	Closest facility layer with facilities.
Input Locations	Feature set (points), input parameter	Point features from which the closest libraries are determined.
Add Locations	Tool	Adds the input locations as incidents to the closest facility layer.
Closest Facility (2)	Network Analyst layer	Closest facility layer with facilities and incidents.
Solve	Tool	Calculates the closest facilities and determines the shortest route to each facility.
Closest Facility (3)	Network Analyst layer	Closest facility layer containing all the facilities and the shortest route to the closest facilities.
SolveSucceeded	Boolean	The derived output from the Solve tool that indicates if the solve was successful.
Directions	Tool	Generates the driving directions for the routes to the closest facilities.
Text Directions	File, output parameter	The text file containing driving directions.
Closest Facility (4)	Network Analyst layer	Closest facility layer containing all the facilities and the shortest route to the closest facilities.
Select Data	Tool	Selects the Routes sublayer from the closest facility layer.
Routes	Feature layer	The routes layer from Closest Facility (3) Network Analyst layer.
OutputRoutesSymbology	Layer	The symbology layer used to apply symbology to the Routes feature layer.
Apply Symbology From Layer	Tool	Applies symbology to the Routes layer from the OutputRoutesSymbology layer.
Closest Routes	Feature layer, output parameter	The Routes layer with appropriate symbology.
Select Data (Facilities)	Tool	Selects the facilities sublayer from the closest facility layer.
Facilities	Feature layer	The facilities layer from the Closest Facility (3) Network Analyst layer.
Join Field	Tool	Joins the FacilityID, FacilityRank, Total_TravelTime, and Total_Meters fields from the Routes layer to the Facilities layer.
Facilities (3)	Table view	The derived facilities layer containing the joined fields.
Make Feature Layer	Tool	Selects only the facilities for which the FacilityID value is not null. Only the fields required in the output facilities are set to be visible.
Facilities_Layer	Feature layer	The facilities feature layer containing only the facilities that are included in the routes.
ClosestLibrariesSymbology	Layer	The symbology layer used to apply symbology to Facilities_Layer.
Apply Symbology From Layer (1)	Tool	Applies symbology to Facilities_layer from the ClosestLibrariesSymbology layer.
Closest Libraries	Feature layer, output parameter	The Facilities_Layer with appropriate symbology.

Model elements

Precalculating network locations for libraries

The library locations used in the closest facility analysis are not transient—their locations on the network remain constant. Hence it is more efficient to calculate their network locations only once instead of calculating them every time they are added as facilities.

The Calculate Locations tool can be used to determine the network locations for the libraries and store the information in the fields SourceID, SourceOID, PosAlong, and SideOfEdge. This information can then be used by the Add Locations tool to load the libraries as facilities in the new closest facility layer. This is considerably faster than using Add Locations to first determine the network locations for libraries, then load them as facilities. For the Library layer, the network locations were determined based on the Streets_ND network dataset layer using the Calculate Locations tool.

Calculating network locations for libraries

Note that if in another scenario the facilities are transient, their network locations will have to be determined every time they are added as facilities. So precalculating their network locations using the Calculate Locations tool will not provide any performance benefit.

Model processes

The Make Closest Facility Layer tool creates a new Network Analyst layer, Closest Facility, that stores the analysis properties, references the Streets_ND network dataset layer used for the analysis, and stores the input facilities and incidents and the output routes. The network dataset has a network cost attribute called TravelTime, which specifies the travel time required to traverse each street segment in minutes. This attribute is used as an impedance attribute. The Number of libraries to find variable specifies the number of facilities to find.

Make Closest Facility Layer tool parameters

The Add Locations (Libraries) tool adds the library locations as facilities to the closest facility layer. Since the network locations for the libraries were already calculated using the Calculate Locations tool, the Use Network Location fields instead of geometry option was checked.

Using network location fields to add facilities

The Add Locations tool adds the user-digitized points as incidents to the closest facility layer. The Input Locations parameter is a feature set data type so that the model can interactively accept the user-digitized points as incidents. The schema and symbology for the feature set are derived from the InputLocations.lyr file found within the ToolData folder.

The Solve tool searches the given number of closest facilities from each incident and calculates a shortest route to each facility based on the TravelTime network attribute. The calculated routes are written to the Routes sublayer in the output closest facility layer.

The Network Analyst layer is not a supported output parameter data type for ArcGIS Server clients. So the Select Data tool is used to get the Routes sublayer from the Closest Facility Network Analyst layer.

The Routes sublayer uses the symbology of the Network Analyst layer. To apply a different symbology such that each route has a unique color, the Apply Symbology From Layer tool is used to apply symbology to the Routes sublayer from the OutputRoutesSymbology layer.

The Directions tool is used to generate the driving directions and output them to a text file. The output text file containing driving directions is created in the jobs directory on the server using the%scratchworkspace% inline variable.

The Routes sublayer in the Closest Facility layer contains a FacilityID field that indicates the object ID of the facility visited by the route. This information can be used to select only the facilities that are visited by routes from all the facilities. The Join Field tool joins the Routes sublayer to the facilities layer using the FacilityID field. The tool joins the FacilityID, FacilityRank, Total_TravelTime, and Total_Meters fields to the facilities sublayer based on FacilityID in routes and ObjectID in facilities.

Join Field tool parameters

The output of the Join Field tool contains the FacilityID field in the facilities sublayer. This field has a value of null for all the facilities that are not visited by the routes. Using the Make Feature Layer tool, only those facilities for which the value of the FacilityID field is not null are selected and output to a new layer.

Make Feature Layer tool parameters

The symbology for the facilities layer is set from the OutputLibrariesSymbology layer using the Apply Symbology From Layer tool.

Tool layer

The Find Nearby Libraries tool layer is created by dragging the Find Nearby Libraries model into the ArcMap table of contents.

Since the model outputs are in-memory feature layers, the Closest Libraries and Routes sublayer within the tool layer will have a broken data source when you first open ClosestFacilitiesService.mxd. The map document will publish as is. However, you should rerun the tool layer and verify that the model works before publishing the service.

Note that if you change the symbology for any of the output layers in the tool layer, the new symbology will not be used. This is because the outputs of this model are feature layers and their symbologies have already been defined using the Apply Symbology To Layer tool in the model.

Publishing

SanFranciscoBaseMap.mxd is published as a map service. ClosestFacilitiesService.mxd is published as a geoprocessing service with no result map service, as follows:

1. In the Catalog window, right-click SanFranciscoBaseMap.mxd and click Publish to ArcGIS Server.
2. Accept all defaults.
3. In the Catalog window, navigate to your server administrative connection under the GIS Servers node, right-click, then choose Add New Service. Name the service ClosestFacilitiesService and choose Geoprocessing Service as the type.
4. Click Next.
5. In the next panel, choose Synchronous for Execution type. For The tools exposed by the Geoprocessing service are stored in option, choose A map and specify ClosestFacilitiesService.mxd for Map Document. Since you will test your service, check Show Messages.

   Publishing the ClosestFacilitiesService

6. Click Next. From this point on, you can accept the default values provided by the wizard and create the service.

Using

1. Start ArcMap with a blank document.
2. Create a user connection to ArcGIS Server from the Catalog window if one does not exist.
3. Add the SanFranciscoBaseMap map service to the ArcMap table of contents.
4. In the Catalog window, under your GIS Servers user connection node, expand the ClosestFacilitiesService toolbox and open the Find Nearby Libraries tool. The illustration below shows the result of these steps:
5. Add a point to create an input location. Specify 3 for number of libraries to find and click OK to run the task.

   After the task completes, the table of contents contains the Closest Libraries and Routes output layer, as illustrated below. The input locations are not output from the task but are added to the table of contents from the Inputs node in the Results window.

   Completed task

6. The text file containing the directions is copied from the jobs directory on the server to the scratch workspace for the current ArcMap session. This file can be viewed by double-clicking it in the Results window.

   Viewing the directions file