Trace

URL:
https://<root>/<serviceName>/TraceNetworkServer/trace
Methods:
POST
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 may not 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

Request parameters

ParameterDetails

f

The output format of the response. The default response format is html.

Use dark colors for code blocksCopy
1
f=html | json | pjson

gdbVersion

(Optional)

Specifies the name of the geodatabase version. The default is sde.DEFAULT .

Syntax: gdbVersion=<version>

sessionId

(Optional)

Specifies 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 value is not provided. If the specified version is currently locked by any other session, the request will fail if the sessionId value is not provided or does not match the sessionId value that holds the exclusive lock.

Syntax: sessionId=<guid>

moment

(Optional)

Specifies the session moment. The default is the version current moment. This should only be provided by the client when they do not want to use the current moment.

Syntax: moment=<Epoch time in milliseconds>

Example: moment=1701505446

traceType

(Required)

The traceType specifies the core algorithm that will be used 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

(Required)

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:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
[
 {
  "traceLocationType" : "startingPoint" | "barrier",
  "globalId" : <guid>,
  “percentAlong” : <double>, // optional
 }
]

traceConfiguration

(Optional)

Specifies the collection of trace configuration properties. The required trace configuration properties are dependent on the trace type. To reference the collection of trace configuration properties, see the traceConfiguration properties section below.

Syntax: traceConfiguration=<traceConfiguration>

traceConfigurationGlobalId

(Optional)

Specifies the global ID of a named trace configuration. When provided, 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

(Optional)

Specifies the types of results to return. The connectivity type was introduced at ArcGIS Enterprise 10.9.1.

Syntax :

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
[
  {
    "type" : `elements` | `aggregatedGeometry` | `connectivity`,
    "includeGeometry" : true | false,
    "includePropagatedValues": true | false,
    "networkAttributeNames" :["attribute1Name","attribute2Name",...],
    "diagramTemplateName": <value>,
    "resultTypeFields":[{"networkSourceId":<long>,"fieldname":<value>},...]
  },...
]

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.

PropertyDetails

includeBarriers

(Optional)

Property specifying whether barrier features that stop a trace will be included in the trace result. The default is true.

Use dark colors for code blocksCopy
1
includeBarriers=true | false

validateConsistency

(Optional)

Property specifying whether the consistency of the trace results will be validated. The default is true.

Use dark colors for code blocksCopy
1
validateConsistency=true | false

ignoreBarriersAtStartingPoints

(Optional)

Property specifying whether barriers will be ignored at starting points. The default is false.

Use dark colors for code blocksCopy
1
ignoreBarriersAtStartingPoints=true | false

shortestPathNetworkAttributeName

(Optional)

Specifies the name of the network attribute used for determining cost when calculating the shortest path. This is a required property for a shortest path trace.

Syntax: shortestPathNetworkAttributeName=<string>

allowIndeterminateFlow

(Optional)

Property specifying whether features with indeterminate flow will stop traversability and be included in the trace results. This property is only honored when running an upstream or downstream trace.

Use dark colors for code blocksCopy
1
allowIndeterminateFlow=true | false

traversabilityScope

(Optional)

Property specifying which network element types the condition barriers or function barriers will apply to. The default is junctionsAndEdges.

Use dark colors for code blocksCopy
1
traversabilityScope=junctions | edges | junctionsAndEdges

conditionBarriers

(Optional)

Property containing an array of objects that serve as barriers. Each condition in the array of conditionBarriers is a Boolean expression based on network attributes. If true, they indicate where a trace will stop (for example, stop at line features of a certain type such as 'Artificial Path'). The conditionBarriers property impacts traversability. The type value indicates whether the condition is based on a network attribute. If isTypeSpecificValue is true, the network attribute is compared to a specific value; otherwise, the network attribute is compared to another network attribute. The default is null.

Syntax:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[
  {
  “name” : <string>
type: “networkAttribute”
  “operator”: “equal” | “notEqual”
             | “greaterThan”
             | “greaterThanEqual |
             | “lessThan”
             | “lessThanEqual”
             | “includesTheValues”
             | “doesNotIncludeTheValues”
             | “includesAny”
             | “doesNotIncludeAny”
  “value” : <string>
  “combineUsingOr” :true|false  “isTypeSpecificValue” :true|false  }
]

functionBarriers

(Optional)

An array of Boolean expressions that are conditions based on function results. If true, they indicate where a trace will stop (for example, ‘add' Shape length 'greaterThan' 2000 'true’ indicates that the trace will 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 (includesTheValues , doesNotIncludeTheValues , includesAny , and doesNotIncludeAny are all bitwise operators), value is the second operand, and useLocalValues indicates whether the trace will stop based on the function result at a particular network element (for example, local) or a global function result.

Syntax:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[
  {
    "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

(Optional)

This is an array of objects representing functions. Each function can have an optional array of network attribute conditions.

Syntax:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
[
  {
    "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>
     }
   ],
   "summaryAttributeName" : <string>
 }
]

Learn more about using multiple conditional expressions

outputConditions

(Optional)

Property specifying the type of features that will be 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 will be returned with the trace. If this property is null, all features in the trace results will be returned. The type value indicates whether the condition is based on a network attribute. If isSpecificValue is true, the network attribute is compared to a specific value; otherwise, the network attribute is compared to another network attribute.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[
 {
  "name": "<string>",
  "type": "networkAttribute",
  "operator": "equal" | "notEqual"
               | "greaterThan"
               | "greaterThanEqual"
               | "lessThan"
               | "lessThanEqual"
               | "includesTheValues"
               | "doesNotIncludeTheValues"
               | "includesAny"
               | "doesNotIncludeAny",
 	"value": <string>,
  "combineUsingOr": <true | false>,
  "isSpecificValue": <true | false>
 }
]

Example:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
[
 {
  "name": "Sinuosity Index",
  "type": "networkAttribute",
  "operator": "greaterThanEqual",
  "value": 1,
  "combineUsingOr": false,
  "isSpecificValue": true
 }
]

JSON Response syntax

JSON response (when async = false):

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "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):

Use dark colors for code blocksCopy
1
2
3
{
  "statusUrl" : <url>
}

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

Use dark colors for code blocksCopy
1
2
3
4
5
{
  "status" : "<Pending | InProgress>",
  "submissionTime" : <datetime>,
  "lastUpdatedTime" : <datetime>
 }

Example usage

Perform a downstream trace on a stream network to return a function result with the distance to the next artificial path. The trace operation request includes the traceConfiguration parameter.

Request URL and parameters:

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

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
f=json
gdbVersion=SDE.DEFAULT
sessionID={55DCF5E1-4DB9-478A-8B0C-65E5F37F5D16}
moment=1554214441244
traceType=downstream
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": [
		{
			"functionType": "add",
			"networkAttributeName": "Shape length",
			"conditions": [],
			"summaryAttributeName": ""
		}
	],
 "outputConditions": []
}
async=false

JSON response:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
	"traceResults": {
		"elements": [
			{
				"networkSourceId": 2,
				"globalId": "{88FAACB9-06F5-4DA1-B10A-C286CE522377}",
				"objectId": 81943
			},
			{
				"networkSourceId": 4,
				"globalId": "{315E6006-C818-481C-AF2F-3A64C6715AAE}",
				"objectId": 14305,
				"positionFrom": 0,
				"positionTo": 1
			}
		],
		"sourceMapping": {
			"1": "TN_5_Associations",
			"2": "TN_5_SystemJunctions",
			"3": "NHDPoint",
			"4": "NHDFlowline"
		},
		"resultTypes": [
			{
				"type": "elements",
				"includeGeometry": false,
				"includePropagatedValues": false,
				"includeDomainDescriptions": false,
				"networkAttributeNames": [],
				"diagramTemplateName": "",
				"resultTypeFields": []
			}
		]
	}
},
  "success": true
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.