ArcGIS Server Banner

GP Service example: Finding nearby features over a street network

GP Service example: Finding nearby features over a street network

Release 9.3 E-mail This TopicPrintable VersionGive Us feedback


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 route to each of the closest library, and generates driving directions in a text file.
Services SanFranciscoBaseMap (map service).

ClosestFacilitiesService (geoprocessing service).
Geoprocessing tasks Find Nearby Libraries.
Inputs User digitizes one or more points and provides the number of closest libraries to find.
Outputs

  1. The closest libraries
  2. The shortest routes between the user specified points and each of the closest library based on the travel time
  3. A text file containing driving directions for each route
Data This example 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 the network analysis layer after solve for further analysis.

Corresponding Folder

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

About this example

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

Example output from Find Nearby Libraries

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, DriveTime, which indicates the time taken to travel each street segment.

Basemap

The basemap for this example, 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

SanFranciscoBaseMap is published as a map service.

Toolbox and map document

The toolbox for the geoprocessing service is ClosestFacilitiesService.tbx, 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.

Model

Model overview

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

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, performs a solve to determine the routes to the closest libraries, generate driving directions, and finds only those libraries that are included in the routes from all the libraries that are loaded as facilities.


Element Type Description
Streets_ND 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 position of these points on the street network are already calculated as described in 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.
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.
Output Routes Symbology 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.
Select Data (Facilities) Tool Selects the Facilities sublayer from the closest facility layer.
Facilities Feature layer The facilities layer from Closest Facility (3) network analyst layer.
Join Field Tool Joins the FacilityID, FacilityRank, Total_DriveTime, and Total_Meters fields from the Routes layer to the Facilities layer.
Facilities (2) 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.
Closest Libraries Symbology Layer The symbology layer used to apply symbology to the Facilities_Layer.
Apply Symbology From Layer (1) Tool Applies symbology to the Facilities_layer from the ClosestLibrariesSymbology layer.
Closest Libraries Feature Layer, output parameter The Facilities_layer with appropriate symbology.
Directions Tool Generates the driving directions for the routes to the closest facilities.
Text Directions File, output parameter The text file containing driving directions.

Find Nearby Libraries model

Precalculating network locations for libraries

The library locations used in the closest facility analysis are not transient—their locations on the network remains 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, SideOfEdge. This information can then be used by 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 and then load them as facilities. For the Library layer, the network locations were determined based on Streets_ND network dataset layer using calculate locations tool.

Calculating network locations for libraries

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

Model Processes

The details about the model follow.

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, stores the input facilities and incidents, and the output routes. The network dataset has a network cost attribute called DriveTime, which specifies the travel time required to traverse each street segment. 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 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, 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 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 DriveTime 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.

Learn more about the Select Data tool.

The routes sublayer uses the symbology of the Network Analyst layer. In order 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 Output Routes Symbology 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 %ScratchWorkspace% in line variable.

The routes sublayer in the closest facility layer contains the 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_Minutes, and Total_Meters fields to the facilities sublayer based on the FacilityID in routes and ObjectID in facilities.

Join Field 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. So, 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 visibility for all the fields expect the Name field be set to False.

Make Feature Layer parameters

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

Tool layer

The Find Nearby Libraries layer is created by dragging and dropping 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 the 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 been already defined using Apply Symbology to Layer tools 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 ArcCatalog, right-click SanFranciscoBaseMap.mxd and click Publish to ArcGIS Server.
  2. Accept all defaults.
  3. In ArcCatalog, navigate to your server and right-click and choose Add New Service. Name the service ClosestFacilitiesService and choose Geoprocessing Service as the type.
  4. Click Next.
  5. In the next panel you choose Synchronous for Execution type. For the tools exposed by the Geoprocessing service are stored in option, select A map option and specify ClosestFacilitiesService.mxd for the Map Document. Since you will test your service, check Show Messages.
  6. Publishing the ClosestFacilitiesService

  7. 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. Optionally, change the background color for the data frame to light blue.
  3. Add the SanFranciscoBasemap map service to the ArcMap table of contents.
  4. Add the ClosestFacilitiesService geoprocessing service to ArcToolbox.
  5. Expand the ClosestFacilitiesService toolbox and open the Find Nearby Libraries tool. The illustration below shows the result of these steps.
  6. Find Nearby Libraries task in ArcMap session

  7. Add a point to create an input location. Specify 3 for number of libraries to find and click OK to run the task.
  8. After the task completes, the table of contents should have the Closest Libraries and Routes output layer, as illustrated below. The Input Locations layer can be added to the ArcMap display from the results tab.
  9. Completed task

  10. 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 tab.
  11. Viewing directions file

See Also

  • Guide to the geoprocessing service examples