ArcGIS REST API - ArcGIS Services

URL:https://<tracenetworkservice-url>/trace
Version Introduced:10.9

Description

A trace refers to a preconfigured algorithm that systematically travels a network to return results. Multiple parameters and properties are provided with the trace operation that support various analytic workflows. All traces use the network topology to read cached information about network features. This can improve performance of complex traces on large networks. Trace results are not guaranteed to accurately represent a trace network when dirty areas are present. The network topology must be validated to ensure that it reflects the most recent edits or updates made to the network.

Learn more about trace network trace types

License:

The active portal account must be licensed with the ArcGIS Trace Network user type extension to use this operation.

Request parameters


Parameter	Details
f	Description: Optional parameter specifying the output format of the response. The default response format is html. Values: html \| json
gdbVersion	Description: Optional parameter specifying the name of the geodatabase version. The default is DEFAULT. Syntax: gdbVersion=<version>
sessionId	Description: Optional parameter specifying the token (GUID) used to lock the version. If the calling client has previously started a service session (editing) and holds an exclusive lock on the specified version, the request will fail if the sessionId is not provided. If the specified version is currently locked by any other session, the request will fail if the sessionId is not provided or does not match the sessionId that holds the exclusive lock. Syntax: sessionId=<guid>
moment	Description: Optional parameter specifying the session moment. The default is the version current moment. This should only be specified by the client when they do not want to use the current moment.
traceType	Description: The trace type. This required parameter specifies the core algorithm that will be executed to analyze the network. Trace types can be configured using the traceConfiguration properties. Values: <connected \| upstream \| downstream \| shortestPath> Syntax: traceType=<traceType> Example: traceType=shortestPath
traceLocations	Description: The locations for starting points and barriers. The trace location will be ignored by the trace if the percentAlong value is not provided for trace locations on edge features. Syntax: `[ { "traceLocationType" : "startingPoint" \| "barrier", "globalId" : <guid>, “percentAlong” : <double>, // optional } ]`
traceConfiguration	Description: Optional parameter specifying the collection of trace configuration parameters. Depending on the trace type, some of the trace configuration properties are required. To reference the collection of trace configuration properties, see the traceConfiguration properties section below. Syntax: traceConfiguration=<traceConfiguration>
traceConfigurationGlobalId	Description: Optional parameter specifying the global ID of a named trace configuration. When specified, this configuration is used instead of the traceConfiguration parameter. Additionally, trace configurations are persisted with their own trace type so the traceType parameter is ignored. Syntax: traceConfigurationglobalId=<guid>
resultTypes	Description: Optional parameter specifying the types of results to return. Note: ArcGIS Enterprise 10.9.1 or later is required when using the connectivity type. Syntax : `[ { "type" : "elements" \| "aggregatedGeometry" \| "connectivity", "includeGeometry" : true \| false, "includePropagatedValues": true \| false, "networkAttributeNames" :["attribute1Name","attribute2Name",...], "diagramTemplateName": <value>, "resultTypeFields":[{"networkSourceId":<long>,"fieldname":<value>},...] },... ]`
async	Description: If true, the request is processed as an asynchronous job, and a URL is returned that a client can visit to check the status of the job. The default is false. Values: true \| false This parameter was introduced at ArcGIS Enterprise 10.9.1

traceConfiguration properties

The traceConfiguration parameter is a collection of trace configuration properties that includes basic properties for a trace and control trace settings for traversability, functions, and outputs.


Property	Details
includeBarriers	Description: Optional property specifying whether to include barrier features that stop a trace in the trace result. The default is true. Values: <true \| false>
validateConsistency	Description: Optional property specifying whether to validate the consistency of the trace results. The default is true. Values: <true \| false>
ignoreBarriersAtStartingPoints	Description: Optional property specifying whether to ignore barriers at starting points. The default is false. Values: <true \| false>
shortestPathNetworkAttributeName	Description: Required property for a shortest path trace; otherwise, it's optional. It specifies the network attribute name used for determining cost when calculating the shortest path. Syntax: shortestPathNetworkAttributeName=<string>
allowIndeterminateFlow	Description: Optional property specifying whether features with indeterminate flow stop traversability and are included in the trace results. This property is only honored when running an upstream or downstream trace. Values: <true \| false>
traversabilityScope	Description: Optional property specifying which network element types the condition barriers or function barriers apply to. The default is junctionsAndEdges. values : "junctions" \| "edges" \| "junctionsAndEdges"
conditionBarriers	Description: Optional property containing an array of objects that serve as barriers. The default is null. Each condition in the array of conditionBarriers is a Boolean expression based on network attributes; if true, they indicate where a trace should stop (for example, stop at closed valves or line features of a certain type). The conditionBarriers property impacts traversability. The “type” indicates whether the condition is based on a network attribute or a category. If isTypeSpecificValue is true, the network attribute is compared with a specific value; otherwise, the network attribute is compared with another network attribute. Syntax: `[ { “name” : <string> “type” : “networkAttribute” \| “operator”: “equal” \| “notEqual” \| “greaterThan” \| “greaterThanEqual \| \| “lessThan” \| “lessThanEqual” \| “includesTheValues” \| “doesNotIncludeTheValues” \| “includesAny” \| “doesNotIncludeAny” “value” : <string> “combineUsingOr” : “true” \| “false” “isTypeSpecificValue” : “true” \| “false” } ]`
functionBarriers	Description: An optional array of Boolean expressions that are conditions based on function results; if true, they indicate where a trace should stop (for example, ‘add “Shape length” “greaterThan” 2000 true’ indicates that the trace should stop after traversing a shape length of 2000 in any direction). functionType is the type of the function, networkAttributeName is the network attribute that will serve as the first operand of the expression, operator indicates which operator will be used in the function (note that includesTheValues, doesNotIncludeTheValues, includesAny, and doesNotIncludeAny are all bitwise operators), value is the second operand, and useLocalValues indicates whether the trace should stop based on the function result at a particular network element (for example, local) or a global function result. Syntax: `[ { "functionType" : "add" \| "subtract" \| "average" \| "count" \| "min" \| "max", "networkAttributeName" : <string>, "operator" : "equal" \| "notEqual" \| "greaterThan" \| "greaterThanEqual" \| "lessThan" \| "lessThanEqual" \| "includesTheValues" \| "doesNotIncludeTheValues" \| "includesAny" \| "doesNotIncludeAny", "value" : <string> "useLocalValues" : "true" \| "false" } ]`
functions	Description: Optional property. This is an array of objects representing functions. Each function can have an optional array of network attribute conditions. Syntax: `[ { "functionType" : "add" \| "subtract" \| "average" \| "count" \| "min" \| "max", "networkAttributeName" : <string>, "conditions": [ { "name" : <string>, "type" : "networkAttribute" \| "category", "operator" : "equal" \| "notEqual" \| "greaterThan" \| "greaterThanEqual \| \| "lessThan" \| "lessThanEqual" \| "includesTheValues" \| "doesNotIncludeTheValues" \| "includesAny" \| "doesNotIncludeAny", "value" : <string>, "combineUsingOr" : <true \| false>, "isSpecificValue" : <true \| false> } ] } ]` Learn more about using multiple conditional expressions
outputConditions	Description: Optional property specifying the type of features returned based on a network attribute. Each condition in the array of outputConditions is a Boolean expression based on network attributes; if true, they indicate which features should be returned with the trace. If this parameter is null, all features in the trace results are returned. The “type” indicates whether the condition is based on a network attribute or a category. If isTypeSpecificValue is true, the network attribute is compared with a specific value; otherwise, the network attribute is compared with another network attribute. `[ { "name": "<string>", "type": "networkAttribute", "operator": "equal" \| "notEqual" \| "greaterThan" \| "greaterThanEqual" \| "lessThan" \| "lessThanEqual" \| "includesTheValues" \| "doesNotIncludeTheValues" \| "includesAny" \| "doesNotIncludeAny", "value": <string>, "combineUsingOr": <true \| false>, "isSpecificValue": <true \| false> } ]` Example: `[ { "name": "Sinuosity Index", "type": "networkAttribute", "operator": "greaterThanEqual", "value": 1, "combineUsingOr": false, "isSpecificValue": true } ]`

JSON Response syntax

JSON response (when async = false):

{
  "traceResults" : {
    "elements" : [
      {
        "networkSourceId" : <long>,
        "globalId" : <guid>,
        "objectId" : <oid>
        "networkAttributes" : [           // optional
          "<networkAttribute1>" : <long>, // optional
          "<networkAttribute2>" : <long>  // optional
        ],                                // optional
        "positionFrom" : <double>,        // optional 
        "positionTo" : <double>           // optional
      }
    ],
    "aggregatedGeometry" : { 
      "point" : <aggregated point geometry>, 
      "line" : <aggregated line geometry>
    }, 
    "globalFunctionResults" : [
      {
        "functionType" : "add" | "average" | "count" | "max" | "min" | 
                         "subtract",
        "networkAttributeName" : <string>,
        "result" : <double>
      }
    ],
    "isConsistent" : <true | false>,
    "startingPointsIgnored" : <true | false>,
    "warnings" : [ <string> ]
  }
  "success" : <true | false>,
  "error" : {                   // only if success is false
    "extendedCode" : <HRESULT>,
    "message" : <error message>,
    "details" : [ <detail> ]
  }
}

JSON response (when async = true):

{
  "statusUrl" : 
}

JSON response to the status URL (when pending or in progress):

{
  "status" : "",
  "submissionTime" : ,
  "lastUpdatedTime" : 
 }

Example usage

Perform a subnetwork trace for the ElectricDistribution domain network Medium Voltage Radial tier. The trace operation request includes the traceConfiguration parameter.

Request URL and parameters:

https://myserver.esri.com/server/rest/services/LandUse/traceNetworkServer/trace

f=json
gdbVersion=SDE.DEFAULT
sessionID={55DCF5E1-4DB9-478A-8B0C-65E5F37F5D16}
moment=1554214441244
traceType=connected
traceLocations=
[
 {
  "traceLocationType": "startingPoint",
  "globalId": "{BBF88249-6BAD-438F-9DBB-0E48DD89EECA}",
  "percentAlong": 0.5805425412252266	
 }
]
traceConfiguration=
{
 "includeBarriers": true,
 "validateConsistency": true,
 "ignoreBarriersAtStartingPoints": false,
 "traversabilityScope": "junctionsAndEdges",
 "conditionBarriers": [
		{
			"name": "FCode",
			"type": "networkAttribute",
			"operator": "equal",
			"value": 55800,
			"combineUsingOr": false,
			"isSpecificValue": true
		}
 ],
 "functionBarriers": [],
 "functions": [],
 "outputConditions": []
}
async=false

JSON response:

{
  "traceResults": {
		"elements": [
			{
				"networkSourceId": 5,
				"globalId": "{54E80EBF-343E-4CAB-89F7-89712E653F05}",
				"objectId": 1,
			},
			{
				"networkSourceId": 3,
				"globalId": "{89ADD4A3-EB2B-451C-AA6F-0AE94C6A9198}",
				"objectId": 1245,
			},
			{<more network elements>}
		],
		"diagramName": "<placeholder>",
		"globalFunctionResults": [],
		"startingPointsIgnored": false,
		"warnings": []	
  },
  "success": true
}