- 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
Parameter | Details |
---|---|
| The output format of the response. The default response format is
|
(Optional) | Specifies the name of the geodatabase version. The default is Syntax: |
(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 Syntax: |
(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: Example: |
(Required) | The Values: Syntax: Example: |
(Required) | The locations for starting points and barriers. The trace location will be ignored by the trace if the Syntax:
|
(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: |
(Optional) | Specifies the global ID of a named trace configuration. When provided, this configuration is used instead of the Syntax: |
(Optional) | Specifies the types of results to return. The Syntax :
|
traceConfiguration properties
The trace
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 |
---|---|
(Optional) | Property specifying whether barrier features that stop a trace will be included in the trace result. The default is
|
(Optional) | Property specifying whether the consistency of the trace results will be validated. The default is
|
(Optional) | Property specifying whether barriers will be ignored at starting points. The default is
|
(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: |
(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.
|
(Optional) | Property specifying which network element types the condition barriers or function barriers will apply to. The default is
|
(Optional) | Property containing an array of objects that serve as barriers. Each condition in the array of Syntax:
|
(Optional) | An array of Boolean expressions that are conditions based on function results. If true, they indicate where a trace will stop (for example, Syntax:
|
(Optional) | This is an array of objects representing functions. Each function can have an optional array of network attribute conditions. Syntax:
|
(Optional) | Property specifying the type of features that will be returned based on a network attribute. Each condition in the array of
Example:
|
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" : <url>
}
JSON response to the status URL (when pending or in progress):
{
"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 trace
parameter.
Request URL and parameters:
https
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:
{
"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
}