NetworkAnalyst

Supported with:
  • Engine with Network
  • ArcView with Network Analyst
  • ArcEditor with Network Analyst
  • ArcInfo with Network Analyst
  • Server with Network
Library dependencies: System, SystemUI, Geometry, GraphicsCore, Display, Server, Output, Geodatabase, GISClient, 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 on undirected networks in your applications. The following diagram gives an overview of some of the objects in the Network Analyst library:
 
 
 

See the following sections for more information about this namespace:

Network Analysis Layer
The network analysis layer (NALayer) contains the problem you are trying to solve. It is responsible for holding the problem definition used during analysis. The main objects include NALayer, NAContext, NAClass, NALocationObject, and NAClassDefinition.
The 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, ArcGIS Engine, or ArcGIS Server. An NALayer is initially created by a solver through a call to INASolver.CreateLayer. The NALayer is the handle that other subsystems (ArcMap, Geoprocessing, ArcCatalog, Engine) use to reference a network analysis problem. From the NALayer, it is possible to get the NAContext and the NALayer's sublayers that reference NAClasses held by the NAContext.
The NAContext object is the most important object in this set. 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 implemented are as follows:
An NAClass holds features or rows used as input and written as output during network analysis. Some NAClasses will contain NALocationFeature objects that reference locations on the network (Stops, Barriers, Incidents, Facilities, Origins, Destinations, Orders, Depots, DemandPoints). In this case, use INALocationObject.NALocation to access the network location. Other NAClasses may instead contain features that do not reference locations on the network (Routes, CFRoutes, SALines, SAPolygons, ODLines, DepotVisits, RouteSeedPoints, RouteZones, LALines) or objects that do not have a geometry (Specialties, Breaks, RouteRenewal, OrderPairs). To access an NAClass, use INAContext.NAClasses.ItemByName or access its containing FeatureLayer or StandaloneTable using INALayer2.DataLayerByNAClassName.
The workspace containing the schema and data for the NAClasses is stored within the NAContext. Data may be swapped to temporary files on disk, but there is not a persistent data source on disk except when the NAContext is persisted within a layer file or map document on disk.
The NAClassDefinition object has additional information about the class that is useful to the extension. It is initially set up when the solver creates the NAContext and the contained NAClasses. It can be retrieved from the NAClass by calling INAClass.ClassDefinition. The NAClassDefinition has methods to determine the minimum and maximum number of rows required by the solver. It also specifies a type for each field, which can be any combination of input, output, not visible, and/or not editable.
You should not modify the NAClassDefinition properties except the CandidateFieldNames.

For further information see:

How to setup, solve, and save a network analysis problem
How to set up a Network Analyst solve to work with the undo/redo stack
Sample: Route layer
Sample: Add a traversal result to the map
Sample: Export any network analysis class to a text file
Sample: Using the traversal result to select source features

Locating and Loading
The NAClassLoader is used to load data into an NAClass from any object that can return a cursor (e.g. FeatureClass, Table, RecordSet, TableSort, NAClass, etc). It makes use of an NAClassFieldMap object that provides a mapping between the input cursor fields and the output NAClass fields. You can also specify a default value to use for fields that aren't mapped or contain null values. The loader also makes use of an NALocator object, which contains NALocatorFeatureAgent and NALocatorLocationFieldsAgent objects, to determine position information for input geometries relative to the network dataset source features or network elements.
If the NAClass contains NALocationObjects or NALocationFeatures, the loader uses the NALocator to find the position of the input point along the network. This position is returned in an NALocation object which is stored on the feature using the INALocationObject.NALocation property. 
If the NAClass contains NALocationRangesObjects or NALocationRangesFeatures, the loader uses the NALocator to find the ranges of positions that the input geometry covers along the network. These position ranges are returned in an NALocationRanges object which is stored on the feature using the INALocationRangesObject.NALocationRanges property. 
If you have your own method for locating features and populating the NAClass with the appropriate location information, you do not need to use the objects in this subsystem to load objects for you.
The NALocation object specifies a position along the network, relative to the network dataset source features. The network location properties are:
  • SourceID—The source ID of the feature class in the network dataset that the location is on. You can get this ID from INetworkSource.ID. This property corresponds to the SourceID field on NALocation-based NAClasses.
  • SourceOID—The ObjectID of the feature that the location is on. This property corresponds to the SourceOID field on NALocation-based NAClasses.
  • Side—The side of the feature that the location is on. This property corresponds to the SideOfEdge field on NALocation-based NAClasses.
  • SourcePosition—Specifies how far along the source feature (in the digitized direction) the network location is located. This property corresponds to the PosAlong field on NALocation-based NAClasses.
The NALocationRanges object specifies a set of position ranges along the network, relative to the network dataset elements. The network location ranges properties are:
  • EdgeRangeCount—The number of network edges included in this set of location ranges.  An edge range can be added to the NALocationRanges object using the INALocationRanges.AddEdgeRange method.  The edge ranges that are currently a part of the location ranges can be retrieved via the INALocationRanges.QueryEdgeRange method.
  • JunctionCount—The number of network junctions included in this set of location ranges.  A junction can be added to the NALocationRanges object using the INALocationRanges.AddJunction method. The junctions that are currently a part of the location ranges can be retrieved via the INALocationRanges.QueryJunction method.
A default NALocator is created on the NAContext by the solver when it creates the NAContext. You can access and change the default locator for the NAContext by setting the Locator property on the INAContextEdit interface.
The 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. By default, NALocatorFeatureAgents are created for each network dataset source. The SnapType property specifies where along the geometry to snap to when searching for network locations. Currently, only the following enumeration values are supported: esriGeometryPartBoundary, esriGeometryPartMidpoint, and esriGeometryPartEndpoint.
The NALocator has a property, SnapTolerance, which 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.
 
INALocator3.GeocodeLocation returns an NALocation based on the input address and the address locator specified. INALocator3.ReverseGeocodeLocation returns the text address of an 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 pre-computed network location fields significantly speeds up the loading process.
To set the INALocator location queries to not return network locations that fall on restricted network elements, INALocator3.ExcludeRestrictedElements should be set to true, and INALocator3.CacheRestrictedElements should be called before using the class loader or any of the location queries.  When using the class loader and loading barriers, the ExcludeRestrictedElements setting will be ignored.

For further information see:

How to load data into a network analysis problem
Sample: Closest facility solver
Sample: Route layer
Sample: Service area solver
Sample: Origin-destination cost matrix solver
Sample: Vehicle routing problem solver
Sample: Location-allocation solver
Sample: Network Analyst barrier location editor

Solvers
A solver is a term used to describe an object that performs the actual network analysis. There are currently five solvers distributed with ArcGIS:
  • NARouteSolver—Finds the least-cost route between multiple stops
  • NAClosestFacilitySolver—Finds the least-cost route between incidents and their closest facilities
  • NAServiceAreaSolver—Finds the area of accessibility within a specified cutoff from a set of facilities
  • NAODCostMatrixSolver—Finds the minimum cost to travel between a set of origins and destinations
  • NAVRPSolver—Optimizes multiple routes intended to service a given set of orders 
  • NALocationAllocationSolver—Finds the optimal location of facilities to serve a set of demand locations
Since each solver has its own requirements to perform an analysis (e.g., the type of network locations it needs, the input properties it needs, etc.), it is the solver's job to create the NAContext and NALayer and to update them if any properties change. The general pattern to follow when creating a new analysis is to call INASolver.CreateContext, INAContextEdit.Bind, and INASolver.CreateLayer.
General solver properties, such as the impedance attribute, restriction attributes, etc., can be set through the INASolverSettings interface for each solver. There are also solver-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, etc.
INASolver.Solve (INAContext, IGPMessages, ITrackCancel) performs network analysis based on the general and specific solver properties and network locations in the NAContext. It returns:
  • True if a partial solution is found (e.g., some stops are unreachable, but a partial route exists).
  • False if a complete solution is found.
Additionally, INASolver.Solve returns informational messages in the GPMessages object. Each GPMessage contains a description and may have an naError code. Message types returned are:
  • esriGPMessageTypeError is returned when the solve fails (e.g., the analysis problem is incorrectly defined or the problem is unsolvable).
  • esriGPMessageTypeWarning is returned when a partial solution is found.
  • esriGPMessageTypeAbort is returned when the user aborts the analysis by pressing the Esc key.
The solver relies on input from the input and input/output NAClasses within the NAContext, which must be populated prior to calling INASolver.Solve. In addition to providing input for the Solve operation, input/output NAClasses may also be updated by the solver when a partial or complete solution is found. As output, the solver populates output NAClasses which contain the results of the analysis when a partial or complete solution is found. The following lists all NAClasses along with their associated solver:
  • NARouteSolver
    • Stops - input/output NAClass
    • Barriers - input NAClass
    • PolygonBarriers - input NAClass
    • PolylineBarriers - input NAClass
    • Routes - output NAClass
  • NAClosestFacilitySolver
    • Incidents - input/output NAClass
    • Facilities - input/output NAClass
    • Barriers - input NAClass
    • PolygonBarriers - input NAClass
    • PolylineBarriers - input NAClass
    • CFRoutes - output NAClass
  • NAServiceAreaSolver
    • Facilities - input/output NAClass
    • Barriers - input NAClass
    • PolygonBarriers - input NAClass
    • PolylineBarriers - input NAClass
    • SALines - output NAClass
    • SAPolygons - output NAClass
  • NAODCostMatrixSolver
    • Origins - input/output NAClass
    • Destinations - input/output NAClass
    • Barriers - input NAClass
    • PolygonBarriers - input NAClass
    • PolylineBarriers - input NAClass
    • ODLines - output NAClass
  • NAVRPSolver
    • Orders - input/output NAClass
    • Depots - input/output NAClass
    • Routes - input/output NAClass
    • Breaks - input/output NAClass
    • RouteRenewals - input/output NAClass
    • RouteSeedPoints - input/output NAClass
    • RouteZones - input NAClass
    • OrderPairs - input NAClass
    • Specialties - input NAClass
    • Barriers - input NAClass
    • PolygonBarriers - input NAClass
    • PolylineBarriers - input NAClass
    • DepotVisits - output NAClass
  • NALocationAllocationSolver
    • Facilities - input/output NAClass
    • DemandPoints - input/output NAClass
    • Barriers - input NAClass
    • PolygonBarriers - input NAClass
    • PolylineBarriers - input NAClass
    • LALines - output NAClass

For further information see:

How to setup, solve, and save a network analysis problem
How to speed up VRP solves
How to set up a Network Analyst solve to work with the undo/redo stack
How to load data into a network analysis problem
Sample: Closest facility solver
Sample: Route layer
Sample: Service area solver
Sample: Origin-destination cost matrix solver
Sample: Vehicle routing problem solver
Sample: Location-allocation solver
Sample: Export any network analysis class to a text file
Sample: Network Analyst barrier location editor
Sample: Network Analyst Engine application

Network Analysis Results
In addition to the output produced by the solver within the output NAClasses, solvers may also produce ancillary data objects to be stored on their associated NAContext instances. Such ancillary data objects are called NAResults and can be accessed through the INAContext.Result property on the NAContext. NAResults hold additional information about the solution produced during analysis. This information can be used to perform various post-processing tasks such as generating driving directions for a route after it is generated.
Each NAResult object must support the INAResult2 interface, which has methods to access the output properties of the NAResult, as well as its associated NAContext. There are currently three different types of NAResult objects within the Network Analyst framework:
  • NATraversalResult—Exposes access to information regarding the network elements traversed to produce the output solution associated with a given NAContext. NATraversalResults are produced by the NARouteSolver, NAClosestFacilitySolver, and NAServiceAreaSolver.
  • NAODCostMatrixResult—Exposes access to individual origin-destination cost matrix entries produced by the NAODCostMatrixSolver.
  • NAVRPResult—Exposes access to the internal NAODCostMatrixResult and route NAContext objects created by the NAVRPSolver during analysis.

Traversal results
At its base level, the traversal result can be viewed as a container for three feature classes that hold all of the connectivity information about how the network elements are traversed to produce a particular route, closest facility, or service area solution:
  • Edges—Includes each edge traversed during analysis. There are fields specifying the FromJunction and the ToJunction.
  • Junctions—Includes each junction and input network location traversed.
  • Turns—Includes each turn traversed.
These three feature classes return specific types of features that also implement the INATraversalResultElement interface, in addition to the IFeature and IRow interfaces.
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 network dataset source feature class 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. Alternatively, since these are feature classes, you can get the feature class for all of the traversal result elements of a specific type (e.g., edges) and open a search cursor on it.
The features contained within the NATraversalResult feature classes are not persisted when the NATraversalResult object is persisted. It is your responsibility to persist this information to an external data structure if this is required.

OD Cost Matrix results
The NAODCostMatrixResult object is created by the NAODCostMatrixSolver after a successful Solve operation only when INAODCostMatrixSolver2.PopulateODLines is False. This object may be used to access origin-destination cost information associated with the NALocation instances currently populated within the associated OD NAContext instance.

VRP Results

The NAVRPResult object is created by the NAVRPSolver to provide access to the results of the analysis. It holds the internally-managed NAODCostMatrixResult object used by the NAVRPSolver during analysis. If the INAVRPSolver.GenerateInternalRouteContext property on the NAVRPSolver object is true, then it will also contain a reference to a route NAContext that is used for generating the true shapes for the route's geometry and for generating driving directions.

For further information see:

Sample: Add a traversal result to the map
Sample: Using the traversal result to select source features

Directions
Directions read NATraversalResults to construct driving directions after solving the route. There are two agents that can be used to generate directions. One is the NAStreetDirectionsAgent, and the other is the NACompactStreetDirectionsAgent. The NAStreetDirectionsAgent is used by the ArcMap directions controls to generate directions. The NACompactStreetDirectionsAgent generates compact directions that are more efficiently passed across the network from ArcGIS Server.
To use NAStreetDirectionsAgent and its related objects, you must first retrieve it from the context's collection of agents using INAContext.get_Agents.get_ItemByName("StreetDirectionsAgent"). Once you have the agent, pass in a set of routes to NAStreetDirectionsAgent.Execute, and it will generate directions. To generate directions from the results of the NAVRPSolver, you must use the agent from the NAContext, which is accessed through INAVRPResult.InternalRouteContext.
Next, use NAStreetDirectionsContainer obtained from INAStreetDirectionsAgent.DirectionsContainer to get the computed directions. Each NAStreetDirections object in the NAStreetDirectionsContainer holds summary information and the directions for the routes specified. For each NAStreetDirection in NAStreetDirecitons, you can use INAStreetDirection.String(index) to get the tokenized strings for the direction.
These driving directions can be saved in an .xml file by calling INAStreetDirectionsContainer.SaveAsXML(<XMLfilename>).
The NACompactStreetDirectionsAgent and its related object can be used in a similar fashion.  You must first retrieve an instance of NACompactStreetDirectionsAgent from the context's collection of agents using INAContext.get_Agents.get_ItemByName("CompactStreetDirectionsAgent"). Once you have the agent, pass in a set of routes to NAStreetDirectionsAgent.Execute, and it will generate directions. To generate directions from the results of the NAVRPSolver, you must use the agent from the NAContext, which is accessed through INAVRPResult.InternalRouteContext.
Next, use NACompactStreetDirectionsContainer obtained from INACompactStreetDirectionsAgent.DirectionsContainer to get the computed directions. Each NACompactStreetDirections object in the NAStreetDirectionsContainer holds summary information and the directions for the routes specified.  For each NACompactStreetDirection in NACompactStreetDirections, you can get each direction's maneuver type and text by using the ManeuverType and Text properties.  Retrieve a compressed version of the direction's geometry using the CompressedGeometry property. Read the help on INACompactStreetDirection.CompressedGeometry to understand how to uncompress the geometry.

For further information see:

How to generate directions

Server Objects
All of the Network Analyst objects work within the server environment. In addition, there is another set of server-specific objects and interfaces designed specifically for use with ArcGIS Server. These objects can be used to perform routing, find the closest facility, generate service areas, solve Location-Allocation, and solve Vehicle Routing Problems. Accessed via the NAServer object, these server objects can be consumed using the GIS Server, GIS Client, ADF, or SOAP APIs.  Routing, Closest Facility, and Service Area solvers are also accessible through the REST and REST-based client APIs such as JavaScript API, Flex, and SilverLight. 
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 NAServerSolverParams and NAServerSolverResults objects.
For SOAP, ADF, GIS Server, and GIS Client APIs, the general pattern when working with server objects is:
  • Get a reference to an NAServer object either through a MapServer that has an NAServer extension loaded or through an NAServer Web service.
  • Call INAServer2.GetSolverParameters2 to get the NAServerSolverParams object holding the default parameters.
  • Set properties on the NAServerSolverParams object to configure how you want the analysis to be performed.
  • Set network locations (e.g., Stops) to use in the analysis.
  • Call INAServer.Solve, passing in the NAServerSolverParams object.
  • Use the returned NAServerSolverResults object to get at the results of the analysis.
For the REST API, the general pattern when working with server objects is:
  • Set properties which are different from default
  • Set network locations.
  • Make an HTTP request to the /Solve endpoint
  • Use the returned JSON object to get the results of the analysis

 

REST and WEB-APIs
If you are writing a light-weight Web application, you do not have to code against the NAServer REST endpoint from scratch. Instead, you can use the out-of-the-box client side libraries. Please refer to the documents below:
Flex: Routing tasks (see API Reference and Samples for more network analysis tasks)
JavaScript: An overview of routing (see Closest Facility, and Service Area tasks in the API Reference, and Samples for more details)
Silverlight : API's main page

 

SOAP, ADF, GIS Server, and GIS Client APIs
All NAServerSolverParams objects support INAServerSolverParams and INASolverSettings. The INAServerSolverParams interface allows you to specify general properties such as 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 (e.g., Stops, Barriers, Facilities, and Incidents) are of type INAServerLocations. The INAServerLocations interface is the base interface of two other more specialized interfaces:
  • The INAServerPropertySets interface provides access to an array of PropertySet objects. Each PropertySet represents a network location. Each property name and value represent a field name and value.
  • The INAServerRecordSet interface provides access to a RecordSet object representing network locations.
INAServer.Solve performs network analysis based on the NAServerSolverParams object (NAServerRouteParams, NAServerClosestFacilityParams, NAServerServiceAreaParams, NAServerODCostMatrixParams, NAServerVRPParams, NAServerLocationAllocationParams) that was passed in and returns its output through an NAServerSolverResults object (NAServerRouteResults, NAServerClosestFacilityResults, NAServerServiceAreaResults, NAServerODCostMatrixResults, NAServerVRPResults, NAServerLocationAllocationResults).
Different solvers return different NAServerSolverResults objects. For example, the results of route analysis will be an NAServerRouteResults object that supports the INAServerSolverResults, INAServerRouteResults, INAServerRouteResults2, and INAServerRouteResults3 interfaces.

Saving Network Analysis Layer on server

In cases when server solves large problems and there is a potential for consecutive requests with the same or similar input parameters, it might be worthwhile to preserve the whole network analysis on server as a layer (lyr) file. It might significantly reduce the size and response time of the consecutive requests. Please refer to the following interfaces and their members:
  • INAServer2
  • INAServerSolverParams2
  • INAServerSolverResults2

OutputGeometryPrecision

Resulting geometry is often the biggest payload on a client-server communication channel. In many cases, such load is undesirable and exact geometry is unnecessary. OutputGeometryPrecision provides the ability to generalize, and thereby reduce the size of, the output geometry. See IPolyCurve.Generalize for information on the generalization technique that is utilized by INASolverOutputGeneralization.

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 through the Distributed Component Object Model (DCOM). Any of the solvers can be used this way to perform network analysis.
When using the fine-grained objects, it is important to manage the state of the Network Analyst objects so other sessions aren't affected by changes to the objects. The NAContext can be serialized in order 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 the NAContext, which has this information. Typically, during each use of a map server object (i.e., each request from the Web browser), the steps below take place for each Network Analyst layer that you are working with.
The INALayer2 interface on the NALayer object can be used within server applications to help manage the state of an NALayer between sessions if it is necessary to use the fine-grained Network Analyst objects. You do not need to use this if you are using NAServer. The general pattern is as follows:
  • Use INALayer2.CopyContext to make a copy of the server's NALayer's NAContext. This is your local copy of the context that only your session will use.
  • Prior to performing any network analysis, apply your local NAContext using INALayer2.AttachContext. This will be used to attach the server's NALayer to the NAContext specified.
  • Set properties and call methods on any of the fine-grained Network Analyst objects. You can also call methods that draw, perform spatial searches, or anything else that requires your NAContext to be attached to the server's NALayer.
  • When done with the Web request, restore the NALayer's original NAContext by calling INALayer2.AttachContext, passing in the original NAContext.

For further information see:

Sample: Closest facility application using the NAServer extension in ArcGIS Server via a GIS server
Sample: Routing and geocoding application using the NAServer extension in ArcGIS Server via a Web service
Sample: Route application using the NAServer extension in ArcGIS Server via a GIS client
Sample: Route application using the NAServer extension in ArcGIS Server via a GIS server
Sample: Route application using the NAServer extension in ArcGIS Server via a Web service
Sample: Service area application using the NAServer extension in ArcGIS Server via a GIS server

See Also:

How to access source features referenced by a network dataset
How to open a network dataset
How to programmatically traverse a street network
How to create a network dataset
How to create a multimodal network dataset
Sample: Import signposts
Sample: Selection restriction evaluator
Sample: Subset network evaluators