ArcGIS REST API

Trace

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

ParameterDetails
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

PropertyDetails
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 parameter representing which network element types the condition, category, or function barriers apply to (default is junctionsAndEdges).

values : "junctions" | "edges" | "junctionsAndEdges"

filterScope

Description: Optional parameter 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

Description: Optional parameter; an array of objects representing function barriers.

Syntax:

[
  {
    "functionType" : "add" | "subtract" |
                   "average" | "count" |
                   "min" | "max"
    "networkAttributeName" : <string>
    "operator" : "equal" | "notEqual"
               | "greaterThan"
               | "greaterThanEqual"
               | "lessThan"
               | "lessThanEqual"
               | "includesTheValues"
               | "doesNotIncludeTheValues"
               | "includesAny"
               | "doesNotIncludeAny"
    "value" : <string>
  }
]

filterBarriers

Description: 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

Description: Optional parameter; an array of objects representing filter function barriers.

[
  {
    "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

Description: 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

Description: Optional parameter; an array of objects representing categories associated with the output filter (default is none).

outputFilters

Description: An array of objects (default is null).

[
  {
  "sourceId" : int
  "assetGroup" : int
  "assetType" : int
  }
]
propagators

Description: Optional parameter; an array of objects (default is null).

[
  {
    "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

{
  "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> ]
  }
}