GP service example: Finding nearby features over 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 |
|
Geoprocessing task |
Find Nearby Libraries |
Inputs |
One or more user-digitized points and the number of closest libraries to find. |
Outputs |
|
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 |
|
Of note |
Demonstrates how to use a solved network analysis layer for further analysis. |
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.
Data
The data for this example comes from C:\arcgis\ArcTutor\GP Service Examples\ClosestFacilities.
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.
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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.
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.
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.
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.
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.
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:
- In the Catalog window, right-click SanFranciscoBaseMap.mxd and click Publish to ArcGIS Server.
- Accept all defaults.
- 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.
- Click Next.
- 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.
- Click Next. From this point on, you can accept the default values provided by the wizard and create the service.
Using
- Start ArcMap with a blank document.
- Create a user connection to ArcGIS Server from the Catalog window if one does not exist.
- Add the SanFranciscoBaseMap map service to the ArcMap table of contents.
- 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:
- 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.
- 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.