- Engine with Network Analyst
- ArcGIS for Desktop Basic with Network Analyst
- ArcGIS for Desktop Standard with Network Analyst
- ArcGIS for Desktop Advanced with Network Analyst
- Server with Network Analyst
Additional library information: Contents, Object Model Diagram
The ArcGIS Network Analyst extension 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 ArcGIS Network Analyst extension library:
See the following sections for more information about this namespace:
- Network analysis layer
- Locating and loading
- Solvers
- Network analysis results
- Directions
- Network Analysis in ArcGIS for Server
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 are as follows:
The NALayer is the uppermost 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 for Server. The NALayer is initially created by a solver through a call to INASolver.CreateLayer. The NALayer is the handle that other subsystems (such as ArcMap, geoprocessing, ArcCatalog, and Engine) use to reference a network analysis problem. From the NALayer, it's possible to get the NAContext and the NALayer sublayers that reference NAClasses held by 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:
- INAContext—Allows you to access the other important parts of the analysis, such as NAClasses, Solver, NALocator, NetworkDataset, and the results.
- INAContextEdit—Controls the initialization of NAContext and the transaction methods for editing NAClasses.
- INAContextEvents—Notifies clients listening to events when NAContext or results has been modified.
NAClass holds features or rows used as input and written as output during network analysis. Some NAClasses can contain NALocationFeature and NALocationRangesFeature objects that reference locations on the network (such as Stops, Point Barriers, Polygon Barriers, Line Barriers, Incidents, Facilities, Origins, Destinations, Orders, Depots, and DemandPoints). In this case, use INALocationObject.NALocation and INALocationRangesObject.NALocationRanges to access the network locations. Other NAClasses can contain features that do not reference locations on the network (such as Routes, CFRoutes, SALines, SAPolygons, ODLines, DepotVisits, RouteSeedPoints, RouteZones, and LALines) or objects that do not have a geometry (such as Specialties, Breaks, RouteRenewal, and 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 NAClasses is stored within NAContext. Data can be swapped to temporary files on disk, but there is no persistent data source on disk except when NAContext is persisted in a layer file on disk 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 NAContext and the contained NAClasses. It can be retrieved from NAClass by calling INAClass.ClassDefinition. INAClassDefinition has properties 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 not editable.
You should not modify the INAClassDefinition properties except the CandidateFieldNames.
For further information see:
How to setup, solve, and save a network analysis problemHow to set up an ArcGIS Network Analyst extension 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
Locating and loading
The NAClassLoader object is used to load data into an NAClass from any object that can return a cursor (for example, FeatureClass, Table, RecordSet, TableSort, NAClass, and so on). It uses an NAClassFieldMap object that provides a mapping between the input cursor fields and the output NAClass fields. You can also specify a default value for fields that are not mapped or that contain null values. The loader also uses 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 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 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 INALocation properties are as follows:
- Side—The side of the feature that the location is on. This property corresponds to the SideOfEdge field on NALocation-based NAClasses.
- 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.
- 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 other type of location object is the NALocationRanges object. NALocationRanges, instead of individual NALocation positions, specifies a set of position ranges along the network, relative to the network dataset elements. Use the query and count methods on INALocationRanges to iterate over and access the set of junctions and/or edge ranges contained in a NALocationRangesObject.
The network location ranges properties are as follows:
- 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 NAContext by the solver when it creates the NAContext. You can access and change the default locator for 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. The following enumeration values are supported: esriGeometryPartBoundary, esriGeometryPartMidpoint, and esriGeometryPartEndpoint.
The NALocator SnapTolerance property specifies the minimum search tolerance 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, set INALocator3.ExcludeRestrictedElements to true, and call INALocator3.CacheRestrictedElements before using the class loader or any of the location queries. When using the class loader and loading barriers, the ExcludeRestrictedElements setting is ignored.
For further information see:
How to load data into a network analysis problemSample: Closest facility solver
Sample: Service area solver
Sample: Origin-destination cost matrix solver
Sample: Vehicle routing problem solver
Sample: Location-allocation solver
Sample: ArcGIS Network Analyst extension barrier location editor
Solvers
A solver is a term used to describe an object that performs the actual network analysis. The following solvers are 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 (for example, the type of network locations it needs, the input properties it needs, and so on), 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 ImpedanceAttributeName and RestrictionAttributeNames, 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 and INAClosestFacilitySolver.DefaultCutoff for NAClosestFacilitySolver.
INASolver.Solve (INAContext, IGPMessages, ITrackCancel) performs network analysis based on the general and specific solver properties and network locations in the NAContext. It returns the following:
- True if a partial solution is found (for example, 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 can have an naError code. Message types returned are as follows:
- esriGPMessageTypeError—Returned when the solve fails (for example, when the analysis problem is incorrectly defined or the problem is unsolvable).
- esriGPMessageTypeWarning—Returned when a partial solution is found.
- esriGPMessageTypeAbort—Returned when the user aborts the analysis by pressing the Esc key.
The solver relies on input from the input and input/output NAClasses in the NAContext, which must be populated prior to calling INASolver.Solve. In addition to providing input for the Solve operation, input/output NAClasses can also be updated by the solver when a partial or complete solution is found. As output, the solver populates output NAClasses that 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 speed up VRP solvesHow to set up an ArcGIS Network Analyst extension solve to work with the undo/redo stack
Sample: Closest facility solver
Sample: Service area solver
Sample: Origin-destination cost matrix solver
Sample: Vehicle routing problem solver
Sample: Location-allocation solver
Sample: ArcGIS Network Analyst extension Engine application
Network analysis results
In addition to the output produced by the solver in the output NAClasses, solvers can 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 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 NAResult, as well as its associated NAContext. The following NAResult objects are available in the ArcGIS Network Analyst extension 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 NARouteSolver, NAClosestFacilitySolver, and NAServiceAreaSolver.
- NAODCostMatrixResult—Exposes access to individual origin-destination cost matrix entries produced by NAODCostMatrixSolver.
- NAVRPResult—Exposes access to the internal NAODCostMatrixResult and route NAContext objects created by NAVRPSolver during analysis.
Traversal results
At its base level, the traversal result can be viewed as a container for the following 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 (for example, edges) and open a search cursor on it.
The features contained in 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 can 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 NAVRPSolver to provide access to the results of the analysis. It holds the internally-managed NAODCostMatrixResult object used by 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 mapDirections
Directions read NATraversalResults to construct driving directions after solving the route. The two agents that can be used to generate directions are NAStreetDirectionsAgent and NACompactStreetDirectionsAgent. NAStreetDirectionsAgent is used by the ArcMap directions controls to generate directions. 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 specified routes. 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 Extensible Markup Language (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 specified routes. 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 directionsNetwork Analysis in ArcGIS for Server
REST
Routing, Closest Facility, and Service Area solvers are accessible through a set of REST endpoints located at http://<server>:6080/arcgis/rest/services.
The general pattern when working with Network Analysis through REST is as follows:
- Set properties that are different from the default.
- Set network locations.
- Make an HTTP request to the /Solve endpoint.
- Use the returned JSON object to get the results of the analysis.
More details can be found in the REST API.
REST and Web APIs
If you're 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. For more information, see the following:
- Flex
- JavaScript
- Silverlight
SOAP
Routing, Closest Facility, Service Area, Location-Allocation, Vehicle Routing Problem, and Origin-Destination Const Matrix solvers are accessible through a set of coarse grained stateless SOAP objects.
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.
The general pattern when working with server objects is as follows:
- Get a reference to an NAServer object either through a MapServer that has an NAServer extension loaded or through an NAServer Web service.
- Call NAServer.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 (for example, Stops) to use in the analysis.
- Call NAServer.Solve, passing in the NAServerSolverParams object.
- Use the returned NAServerSolverResults object to get at the results of the analysis.
See the SOAP SDK topics for more information.
For further information see:
Sample: Route application using the NAServer extension in ArcGIS for Server via a Web serviceSample: Routing and geocoding application using the NAServer extension in ArcGIS for Server via a Web service
See Also:
How to access source features referenced by a network datasetHow 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: Selection restriction evaluator
Sample: Subset network evaluators