ArcGIS REST API - ArcGIS Services

URL:https://<utilitynetworkservice-url>/trace
Version Introduced:10.6

Description

A trace refers to a pre-configured algorithm that systematically travels a network to return results. Generalized traces allow you to trace across multiple types of domain networks. For example, running a Connected trace from your electric network through to your gas network. An assortment of options is provided with trace to support various analytic work flows. 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 utility network when dirty areas are present. The network topology must be validated to ensure it reflects the most recent edits or updates made to the network.

License:

The ArcGIS Utility Network Management extension is required to use these resources.

Request Parameters


Parameter	Details
f	Description: Optional parameter representing 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 (default is DEFAULT). Syntax: gdbVersion=<version>
sessionId	Description: Optional parameter representing 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 which holds the exclusive lock. Syntax: sessionId=<guid>
moment	Description: Optional parameter representing 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. Syntax: "connected " \| " subnetwork " \| " subnetworkController " \| " upstream " \| " downstream " \| " loops " \| " shortestPath " \| " isolation "
traceLocations	Description: The locations for starting and stopping points, as well as barriers. Optional parameter for subnetwork trace type, required parameter for all other trace types. Syntax: Syntax: `[ { "traceLocationType" : "startingPoint" \| "barrier" "globalId" : <guid>, "terminalId" : <long>, // optional } ]`
traceConfiguration	Description: Optional parameter representing the collection of trace configuration parameters (see below). Syntax: traceConfiguration=<traceConfiguration>
resultType	Description : Optional parameter representing the type of results to return. Values: "elements"

traceConfiguration Properties


Property	Details
includeContainers	Description: Optional parameter representing whether or not to include containers in the trace result (default is false). Values: "true" \| "false"
includeContent	Description: Optional parameter representing whether or not to include content in the trace result (default is false). Values: "true" \| "false"
includeStructures	Description: Optional parameter representing whether or not to include structures in the trace result (default is false). Values: "true" \| "false"
includeBarriers	Description: Optional parameter representing whether or not to include barrier features that stop a trace in the trace result (default is true). Values: "true" \| "false"
includeIsolated	Description: Optional parameter representing whether or not to include isolated features for an isolation trace (default is false). Values: "true" \| "false"
validateConsistency	Description: Optional parameter representing whether or not to validate the consistency of the trace results (default is false). Values: "true" \| "false"
domainNetworkName	Description: Optional parameter that specifies the name of the domain network where the trace is starting. Syntax: domainNetworkName=<string>
tierName	Description: Optional parameter that specifies the name of the tier where the trace is starting. Syntax: tierName=<string>
targetTierName	Description: Optional parameter representing the name of the tier where upstream or downstream trace ends. Syntax: targetTierName=<string>
subnetworkName	Description: Optional parameter representing the name of the subnetwork that will be traced - the starting points of the trace will be the controllers of this subnetwork . Syntax: subnetworkName=<string>
shortestPathNetworkAttributeName	Description: Required parameter for shortest path trace; optional otherwise. It represents the network attribute name used for determining cost when calculating the shortest path. Syntax: shortestPathNetworkAttributeName=<string>
filterBitsetNetworkAttributeName	Description: Optional parameter. Used during loops trace to only return loops with the same bit set all around the loop. Used during upstream/downstream traces to ensure that trace results include any bit that is set in the starting points for the network attribute. Syntax: filterBitsetNetworkAttributeName=<string>
traversabilityScope	Description: Optional parameters representing which network element types the condition, category, or function barriers apply to (default is junctionsAndEdges). values : "junctions" \| "edges" \| "junctionsAndEdges"
filterScope	Description: Optional parameters representing which network element types the filter barriers or filter function barriers apply to (default is junctionsAndEdges). values : "junctions" \| "edges" \| "junctionsAndEdges"
conditionBarriers	Description: Optional parameter containing an array of objects (representing network attribute conditions) that serve as barriers - default is null. If isTypeSpecificValue is true, the network attribute is being compared with a specific value; otherwise the network attribute is being compared with another network attribute. Syntax: `[ { "networkAttributeName" : <string> "operator" : "equal" \| "notEqual" \| "greaterThan" \| "greaterThanEqual" \| "lessThan" \| "lessThanEqual" \| "includesTheValues" \| "doesNotIncludeTheValues" \| "includesAny" \| "doesNotIncludeAny" "value" : <string> "combineUsingOr" : "true" \| "false" "isTypeSpecificValue" : "true" \| "false" } ]`
functionBarriers	Array of object; optional parameter. Syntax: `[ { "functionType" : "add" \| "subtract" \| "average" \| "count" \| "min" \| "max" "networkAttributeName" : <string> "operator" : "equal" \| "notEqual" \| "greaterThan" \| "greaterThanEqual" \| "lessThan" \| "lessThanEqual" \| "includesTheValues" \| "doesNotIncludeTheValues" \| "includesAny" \| "doesNotIncludeAny" "value" : <string> } ]`
filterBarriers	array of objects; optional parameter. Optional parameter containing an array of objects (representing network attribute conditions or categories) that serve as barriers - default is null. If isTypeSpecificValue is true, the network attribute is being compared with a specific value; otherwise the network attribute is being compared with another network attribute. `[ { "networkAttributeName" : <string> "operator" : "equal" \| "notEqual" \| "greaterThan" \| "greaterThanEqual" \| "lessThan" \| "lessThanEqual" \| "includesTheValues" \| "doesNotIncludeTheValues" \| "includesAny" \| "doesNotIncludeAny" "value" : string (numeric) "combineUsingOr" : "true" \| "false" "isTypeSpecificValue" : "true" \| "false" } ]`
filterFunctionBarriers	array of objects; optional parameter. `[ { "functionType" : "add" \| "subtract" \| "average" \| "count" \| "min" \| "max" "networkAttributeName" : <string> "operator" : "equal" \| "notEqual" \| "greaterThan" \| "greaterThanEqual" \| "lessThan" \| "lessThanEqual" \| "includesTheValues" \| "doesNotIncludeTheValues" \| "includesAny" \| "doesNotIncludeAny" "value" : string (numeric) } ]`
functions	Description: Optional parameter ; an array of objects representing functions. Each function may have an optional array of network attribute conditions. Syntax: Syntax: `[ { "functionType" : "add" \| "subtract" \| "average" \| "count" \| "min" \| "max" "networkAttributeName" : <string> [ { "networkAttributeName" : <string> "operator" : "equal" \| "notEqual" \| "greaterThan" \| "greaterThanEqual \| \| "lessThan" \| "lessThanEqual" \| "includesTheValues" \| "doesNotIncludeTheValues" \| "includesAny" \| "doesNotIncludeAny" "value" : <string> "combineUsingOr" : "true" \| "false" "isTypeSpecificValue" : "true" \| "false" } ] } ]`
nearestNeighbor	object This object specifies the parameters need for calculating nearest neighbors (default is null) ; optional parameter. `{ "count" : int "costNetworkAttributeName" : string "nearestCategories" : array of string "nearestAssets" [ { "sourceId" : int "assetGroup" : int "assetType" : int } ] }`
outputFilterCategories	array of string The categories associated with the output filter (default is none) ; optional parameter.
outputFilters	array of object (default is null) `[ { "sourceId" : int "assetGroup" : int "assetType" : int } ]`
propagators	array of object (default is null) ; optional parameter. `[ { "networkAttributeName" : string "functionType" : "bitwiseAnd" \| "min" \| "max" "operator : "equal" \| "notEqual" \| "bitwiseAnd" \| "greater" \| "greaterEqual" \| "less" \| "lessEqual" "value" : string (numeric) } ]`

JSON Response Syntax

JSON response syntax for trace

JSON Response:

{
  "traceResults" : {
    "elements" : [
      {
        "networkSourceId" : <long>,
        "globalId" : <guid>,
        "objectId" : <oid>
        "terminalId" : <long>,            // optional
        "networkAttributes" : [           // optional
          "<networkAttribute1>" : <long>, // optional
          "<networkAttribute2>" : <long>  // optional
        ],                                // optional
        "assetGroup" : <long>,            // optional
        "assetType" : <long>              // optional
      }
    ],
    "url" : "<url>",              // url of created connectivity file
    "diagramName" : <string>,
    "globalFunctionResults" : [
      {
        "functionType" : "add" | "average" | "count" | "max" | "min" | 
                         "subtract",
        "networkAttributeName" : <string>,
        "result" : <double>
      }
    ],
    "isConsistent" : <true | false>,
    "kFeaturesForKNNFount" : <true | false>,
    "startingPointsIgnored" : <true | false>,
    "warnings" : [ <string> ]
  }
  "success" : <true | false>,
  "error" : {                   // only if success is false
    "extendedCode" : <HRESULT>,
    "message" : <error message>,
    "details" : [ <detail> ]
  }
}

Connectivity file JSON format:

{ 
  "type" : "tabular",
  "sourceMapping" : { "<sourceId1>" : <sourceName1>, 
                      "<sourceId2>" : <sourceName2>, . . .
  }
  "rows" : [
    {
      "viaSourceId" : <long>, 
      "viaGlobalId" : <guid>, 
      "viaSubtypeName" : <name>, 
      "viaGeometry" : <geometry>,
      "fromSourceId" : <long>, 
      "fromGlobalId" : <guid>, 
      "fromSubtypeName" : <name>, 
      "fromTerminalId" : <long>, 
      "fromGeometry" : <geometry>
      "toSourceId" : <long>, 
      "toGlobalId" : <guid>, 
      "toSubtypeName" : <name>, 
      "toTerminalId" : <long>, 
      "toGeometry" : <geometry>
    }
  ]
}