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, 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). In this case, use INALocationObject.getNALocation property 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) 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.getDataLayerByNAClassName.
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.getClassDefinition. 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.

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. If the NAClass contains NALocationObjects or NALocationFeatures, the loader makes use of an NALocator which contains NALocatorFeatureAgent and NALocatorLocationFieldsAgent  objects to find the position of the input point on the network. The position along the network is returned in an NALocation object which is stored on the feature using the INALocationObject.NALocation 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 on the network. 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.getID . 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. 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.
 
INALocator2.geocodeLocation returns an NALocation based on the input address and the address locator specified. INALocator2.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.

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:
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.setFindBestSequence for NARouteSolver, INAClosestFacilitySolver.setDefaultCutoff 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
    • Routes - output NAClass
  • NAClosestFacilitySolver
    • Incidents - input/output NAClass
    • Facilities - input/output NAClass
    • Barriers - input NAClass
    • CFRoutes - output NAClass
  • NAServiceAreaSolver
    • Facilities - input/output NAClass
    • Barriers - input NAClass
    • SALines - output NAClass
    • SAPolygons - output NAClass
  • NAODCostMatrixSolver
    • Origins - input/output NAClass
    • Destinations - input/output NAClass
    • Barriers - 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
    • DepotVisits - output NAClass
  • NALocationAllocationSolver
    • Facilities - input/output NAClass
    • DemandPoints - input/output NAClass
    • Barriers - input NAClass
    • PolygonBarriers - input NAClass
    • PolylineBarriers - input NAClass
    • LALines - output NAClass
       

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.setPopulateODLines has been set to 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.

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 is new at ArcGIS 9.3.  It 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.getAgents().getItemByName("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.getInternalRouteContext.
Next, use NAStreetDirectionsContainer obtained from INAStreetDirectionsAgent.getDirectionsContainer 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.getString (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.getInternalRouteContext.
Next, use NACompactStreetDirectionsContainer obtained from INACompactStreetDirectionsAgent.getDirectionsContainer 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.getCompressedGeometry to understand how to uncompress the geometry.

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:
  1. Get a reference to an NAServer object either through a MapServer that has an NAServer extension loaded or through an NAServer Web service.
  2. Call INAServer2.GetSolverParameters2 to get the NAServerSolverParams object holding the default parameters.
  3. Set properties on the NAServerSolverParams object to configure how you want the analysis to be performed.
  4. Set network locations (e.g., Stops) to use in the analysis.
  5. Call INAServer.Solve, passing in the NAServerSolverParams object.
  6. 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:
  1. Set properties which are different from default
  2. Set network locations.
  3. Make an HTTP request to the /Solve endpoint
  4. Use the returned JSON object to get the results of the analysis
For the JavaScript, Flex, and SilverLight APIs please refer to the documents below:
JavaScript API: Intro route overview
JavaScript Extension for Google Maps: gmaps route routetask
JavaScript Extension for Virtual Earth: route routetask
Flex API: routing
SilverLight API: routing

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.