NetworkAnalyst

Supported with:
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, Geodatabase, GISClient, ArcWeb, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, DataSourcesNetCDF, GeoDatabaseDistributed, GeoDatabaseExtensions, Carto, NetworkAnalysis, Location, GeoAnalyst, Animation, Maplex, Geoprocessing

Additional library information: Contents, Object Model Diagram

The Network Analyst library provides objects for working with network datasets. These objects allow you to perform network analysis in your applications. The following diagram gives you an overview of some of the objects in the Network Analyst library.
 

The objects that implement this functionality are grouped into a number of library subsystems. These library subsystems are:

The network analysis layer
The network analysis layer (NALayer) contains the problem you're trying to solve. It is responsible for holding the problem definition used during analysis. The main objects include NALayer, NAContext, NAClass, NALocationObject, and NAClassDefinition.
 
NALayer is the topmost object in this set of objects. It is a true layer, capable of being persisted in ArcMap or on disk and accessed through ArcMap, ArcCatalog, Engine, or Server. NALayer is initially created by a solver through a call to INASolver.CreateLayer. NALayer is the handle that other subsystems (ArcMap, Geoprocessing, ArcCatalog, Engine) use to reference a network analysis problem. From NALayer, it is possible to get NAContext and to NALayer's sub-layers that reference NAClass held by NAContext.
 
NAContext object is the most important object in this set of objects. As its name implies, it is the context that everything goes to for information. It has references to everything else that is used as part of the analysis. A context is generally created by calling INASolver.CreateContext on a solver, then binding the context to a network dataset. The three main interfaces are as follows:
 
NAClass is a specialized feature class. It holds features representing things such as Stops, Barriers, Incidents, Facilities, Routes, CFRoutes, SALines, SAPolygons, ODLines, and so on. NAClass's workspace is NAContext and as such they are considered “in-memory” feature classes since they do not have a persistent source on disk other than when persisted within a layer file on disk. They can be retrieved in ways such as INALayer.LayerByNAClassName(“Stops”).FeatureClass or by INAContext.NAClasses.ItemByName(“Stops”).
 
NAClasses serve up NALocationObject and NALocationFeature, which are rows and features that can implement an additional interface, INALocationObject, which specifies the position where it is located on the network.
 
The NAClassDefinition object has additional information about the class that is useful to the extension. It is initially set up by the solver when it creates NAContext and the contained NAClasses. It can be retrieved from NAClass by calling INAClass.ClassDefinition. INAClassDefinition has methods to determine the minimum and maximum number of rows required by the solver. It also specifies each field type, which can be any combination of input, output, not visible, and not editable.
 
You should not modify INAClassDefinition properties except CandidateFieldNames.

Locating and loading
This subsystem represents objects used to load NAClasses representing NALocation such as Stops, Barriers, and so on. Loading network locations entails starting with an input point, locating its position on the network by identifying the side and position along a feature in the network dataset, and creating a new feature in NAClass with this network position information. There are objects that do the locating (NALocator, NALocatorFeatureAgent, NALocatorLocationFieldsAgent) and objects that bulk load into NAClass based on NALocator (NAClassLoader, NAClassFieldMap).
 
If you have your own method for locating features and populating NAClass with the appropriate location information, you do not need to utilize the objects in this subsystem to load objects for you.
 
The NALocation object simply holds the place on the network where it’s located. The network location fields are as follows:
 
A default NALocator is created on NAContext by the solver when it creates NAContext. You can access and change the default locator for NAContext by setting the NALocator property on the INAContextEdit interface.
 
NALocator has a series of locator agents. It is the job of NALocator to iterate through the agents and determine which agent returned the best location. Most likely the agents will be NALocatorFeatureAgents. By default, NALocatorFeatureAgents are created for each network dataset source. Currently, only esriGeometryPartBoundary, esriGeometryPartMidpoint, and esriGeometryPartEndpoint are supported. The SnapType property specifies where to snap along the geometry.
 
NALocator has a property, SnapTolerance, that specifies the minimum search tolerance used when searching for network locations. If nothing is found within this tolerance, the search tolerance is doubled until a network location is found or the maximum search tolerance specified by MaxSnapTolerance is reached.
 
INALocator2.GeocodeLocation returns NALocation based on the input address and the address locator specified. INALocator2.ReverseGeocodeLocation returns the text address of NALocation based on the address locator specified.
 
The NALocatorLocationFieldsAgent object can be used if the source class already has location fields populated and you want to use these instead of spatially searching for the location on the network. Using precomputed network location fields significantly speeds up the loading process.
 
The NAClassLoader and NAClassFieldMap objects are used together to bulk load INALocationObject into NAClass from an input feature class using NALocator.

Solvers
A solver is an object that performs the actual network analysis. The four solvers distributed with ArcGIS are as follows:
 
Since it is the solver that knows what it requires to perform analysis (what type of network locations, what input properties, and so forth), it is the job of the solver to create NAContext and NALayer and to update them if any properties are changed. The general pattern to follow when creating a new analysis is to call INASolver.CreateContext, INASolver.Bind, and INASolver.CreateLayer.
 
General solver properties, such as impedance attribute, restriction attributes, and so forth, can be set through the INASolverSettings interface. There are specific properties that can be set on each solver to configure how the analysis is performed such as INARouteSolver.FindBestSequence for NARouteSolver, INAClosestFacilitySolver.DefaultCutoff for NAClosestFacilitySolver, and so forth.
 
INASolver.Solve() performs network analysis based on the general and specific solver properties and network locations in NAContext. It returns:
 
Additionally, INASolver.Solve(NAContext, GPMessages, TrackCancel) returns informational messages in the GPMessages object. Each GPMessage contains a description and may have naError code. esriGPMessageTypes returned are:
 
As output, the solver populates output NAClasses that contain the results of the analysis. The following output NAClasses are populated by the solver when a partial or complete solution is found:
 
The solver can also create a NATraversalResult object accessed through INAResult that holds information about the network elements traversed during analysis. This information is necessary to perform post-processes such as generating driving directions after the route has been computed.

Traversal results
NARouteSolver, NAClosestFacilitySolver, and NAServiceAreaSolver output an NATraversalResult object that holds the results of the analysis. At its base level, the traversal result can be viewed as three feature classes that hold all the connectivity information about how the network elements were traversed:
 
These three feature classes return specific types of features that also implement the INATraversalResultElement interface in addition to the IFeature and IRow interfaces.
 
The INAResult interface has methods to get the output properties and the context. There is a level of indirection in the NATraversalResult. Because of this, you must use methods on the INATraversalResult interface to find the mapping between sources in the traversal result and the corresponding geodatabase or NAClass source.
 
INATraversalResultQuery is used to traverse from one traversal result element to another. You can call SearchConnected to find the NATraversalResultElement connected to a specific TraversalResultElement. Or, since these are feature classes, you can get the feature class for all the traversal result elements of a specific type (e.g., edges) and open a search cursor on it.
 
NATraversalResult is not persisted with NAContext, and it is your responsibility to persist it to an external data structure if this is required.

Directions
Directions read NATraversalResults to construct driving directions as a post process to solving the route. You can retrieve NAStreetDirectionsAgent from INAContext.get_Agents.get_ItemByName("StreetDirectionsAgent"). Once you have the agent, call INAStreetDirectionsAgent.Execute passing in a set of the routes you want directions for, and it will generate directions.
 
Once complete, use NAStreetDirectionsContainer obtained from INAStreetDirectionsAgent.DirectionsContainer to get the computed directions. Each NAStreetDirections in INAStreetDirectionsContainer holds the directions for one of the routes specified. You can use INAStreetDirection.String(index) to get the tokenized strings for that direction.
 
Driving directions can be saved in an XML file by calling INAStreetDirectionsContainer.SaveAsXML(XMLfilename).

Server objects
The Network Analyst objects all work within the server environment. There are a couple of additional objects and interfaces designed specifically for the server environment. The Network Analyst server objects can be accessed though the GIS Server application programming interface (API), GIS Client, and through a Web Service using Web Service Description Language (WSDL).
 
The NAServer object is a MapServer server object extension that is capable of performing network analysis through a single stateless method call. It is used in conjunction with various INAServerSolverParams and INAServerSolverResults objects.
 
The general pattern when working with the server objects is as follows:
 
All NAServerSolverParams objects support INAServerSolverParams and INASolverSettings. The INAServerSolverParams interface allows you to specify general properties such as the MaxSnapTolerance, ReturnMap, and OutputSpatialReference. There are also specific interfaces for each type of solver. For example, NAServerRouteParams also supports INAServerRouteParams and INARouteSolver.
 
The network location properties on the various NAServerSolverParams objects (for example, Stops, Barriers, Facilities, and Incidents) are of type INAServerLocations. The INAServerLocations interface is the base interface of two other more specialized interfaces:
 
INAServer.Solve performs network analysis based on the NAServerSolverParams object (NAServerRouteParams, NAServerClosestFacilityParams, NAServerServiceAreaParams) that was passed in and returns its output through a NAServerSolverResults object (NAServerRouteResults, NAServerClosestFacilityResults, NAServerServiceAreaResults). INAServerSolverResults provides methods on an NAServerSolverResults object (NAServerRouteResults, NAServerClosestFacilityResults, NAServerServiceAreaResults) returned by the Solve method on INAServer to retrieve the results of the network analysis. For example, there is a method to get MapImage that will be populated if INAServerSolverParams.ReturnMap was set to True.
 
Different solvers return different NAServerSolverResults objects. For example, the results of route analysis will be an NAServerRouteResults object that supports the INAServerSolverResults and INAServerRouteResults interfaces.

Using Network Analyst in a server environment without NAServer

It is possible to create an application that bypasses NAServer and accesses the fine-grained Network Analyst objects on the server directly. When doing so, it is important to manage the state of the Network Analyst objects so other sessions aren't affected by changes to the objects. NAContext can be serialized to store all Network Analyst state information from one request to the other. For example, once you have a route displayed on the map, you will want to continue to display that route even after the map has been panned or zoomed. For each request to your application, a process occurs to retrieve, store, copy or apply, serialize, and finally restore NAContext, which has this information. Typically, during each use of a map server object (i.e., each request from the Web browser) the following steps take place for each Network Analyst layer with which you are working.
 
There is an INALayer2 interface on the NALayer object that can be used in server applications to help manage the state of NALayer between sessions if it is necessary to use the fine grain network analyst objects. You do not need to use this if you are using NAServer. The general pattern is as follows: