Query (Circuits)

URL:: https://<root>/<serviceName>/UtilityNetworkServer/circuits/query
Methods:: GETPOST
Version Introduced:: 11.5

The query operation on the circuits resource returns circuits from a telecom domain network that satisfy a specified query. The query operates in two different modes, depending on whether a circuit name or trace location information is provided for the query. You can provide an array of circuit names as the input or provide information for a trace location from which the circuits either start or stop. When a circuit name is provided for the circuits parameter, the sourceId, globalId, terminalId,firstUnit, and numUnits parameters are ignored. When returning the circuits that start or stop at a specified trace location (i.e., using sourceId, globalId, terminalId, firstUnit, and numUnits parameters), if returnConsumingCircuits is false, only the immediate circuits that are pass through the specified feature are returned. Otherwise, all the circuits that consume the immediate circuits are returned.

Request parameters

Parameter Details

Parameter	Details
`f`	Specifies 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 a client has previously started an edit session and holds an exclusive lock on the version specified, 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` (Optional)	Specifies the session moment. The default value is the version's current moment. This should only be specified by the client when they do not want to use the current moment. Syntax: `moment=<Epoch time in milliseconds>` Example: `moment=1730456642`
`domainNetworkName` (Required)	Specifies the name of the telecom domain network containing the circuits to be queried. Syntax: `domainNetworkName=<string>` Example: `domainNetworkName=Telco`
`circuits` (Optional)	The names of the circuit or circuits to be returned. Syntax: `circuits=[<string>]` Example: `circuits=["CircuitA","CircuitB"]`
`sourceId` (Optional)	The source Id of the feature associated with the starting or stopping point for the circuit. This is required when the trace location parameters are used instead of `circuit`. Syntax: `sourceId=<short>` Example: `sourceId=20`
`globalId` (Optional)	The global Id of the feature associated with the starting or stopping point for the circuit. This is required when trace location parameters are used instead of `circuit`. Syntax: `globalId=<guid>` Example: `globalId={4EFBBE6D-0ED9-42F1-9D78-D38186B0CF85}`
`terminalId` (Optional)	The terminal Id of the feature associated with the starting or stopping point for the circuit. This is required when trace location parameters are used instead of `circuit` and can be -1 when no terminals are present. Syntax: `terminalId=<short>` Example: `terminalId=1`
`firstUnit` (Optional)	The first unit identifier for the starting or stopping point. This is required when trace location parameters are used instead of `circuit`. Syntax: `firstUnit=<short>` Example: `firstUnit=1`
`numUnits` (Optional)	The number of units in the contiguous group for the starting or stopping point. This is required when trace location parameters are used instead of `circuit`. Syntax: `numUnits=<short>` Example: `numUnits=3`
`pointType` (Optional)	The type of trace location in the circuit to query (starting point, stopping point, or both). The default is `all`. Use dark colors for code blocksCopy `1 pointType=start \| stop \| all` Syntax: `pointType=<string>` Example: `pointType=start`
`returnConsumerCircuits` (Optional)	Specifies whether to return the names of all consumer circuits. The default is `false`. Use dark colors for code blocksCopy `1 returnConsumerCircuits=true \| false` Syntax: `returnConsumerCircuits=<boolean>` Example: `returnConsumerCircuits=false`
`resultType` (Optional)	The type of information to return about the circuit. Use `circuit` to return all information about a circuit including section and subcircuit information. Partial information about a circuit (e.g., Status or Subcircuit name) can also be queried from the circuit management tables directly. The default is `name`. Use dark colors for code blocksCopy `1 resultType=name \| circuit` Syntax: `resultType=[<resultType>]` Example: `resultType=[circuit]`

f

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

Use dark colors for code blocksCopy
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 a client has previously started an edit session and holds an exclusive lock on the version specified, 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

(Optional)

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

Syntax: moment=<Epoch time in milliseconds>

Example: moment=1730456642

domainNetworkName

(Required)

Specifies the name of the telecom domain network containing the circuits to be queried.

Syntax: domainNetworkName=<string>

Example: domainNetworkName=Telco

circuits

(Optional)

The names of the circuit or circuits to be returned.

Syntax: circuits=[<string>]

Example: circuits=["CircuitA","CircuitB"]

sourceId

(Optional)

The source Id of the feature associated with the starting or stopping point for the circuit. This is required when the trace location parameters are used instead of circuit.

Syntax: sourceId=<short>

Example: sourceId=20

globalId

(Optional)

The global Id of the feature associated with the starting or stopping point for the circuit. This is required when trace location parameters are used instead of circuit.

Syntax: globalId=<guid>

Example: globalId={4EFBBE6D-0ED9-42F1-9D78-D38186B0CF85}

terminalId

(Optional)

The terminal Id of the feature associated with the starting or stopping point for the circuit. This is required when trace location parameters are used instead of circuit and can be -1 when no terminals are present.

Syntax: terminalId=<short>

Example: terminalId=1

firstUnit

(Optional)

The first unit identifier for the starting or stopping point. This is required when trace location parameters are used instead of circuit.

Syntax: firstUnit=<short>

Example: firstUnit=1

numUnits

(Optional)

The number of units in the contiguous group for the starting or stopping point. This is required when trace location parameters are used instead of circuit.

Syntax: numUnits=<short>

Example: numUnits=3

pointType

(Optional)

The type of trace location in the circuit to query (starting point, stopping point, or both). The default is all.

Use dark colors for code blocksCopy
pointType=start | stop | all

Syntax: pointType=<string>

Example: pointType=start

returnConsumerCircuits

(Optional)

Specifies whether to return the names of all consumer circuits. The default is false.

Use dark colors for code blocksCopy
returnConsumerCircuits=true | false

Syntax: returnConsumerCircuits=<boolean>

Example: returnConsumerCircuits=false

resultType

(Optional)

The type of information to return about the circuit. Use circuit to return all information about a circuit including section and subcircuit information. Partial information about a circuit (e.g., Status or Subcircuit name) can also be queried from the circuit management tables directly. The default is name.

Use dark colors for code blocksCopy
resultType=name | circuit

Syntax: resultType=[<resultType>]

Example: resultType=[circuit]

JSON Response syntax

JSON response when circuit is specified for resultType:

Use dark colors for code blocksCopy
{
	"circuits":	[
		{
			"name" : <string>,
			"globalId": <guid>,
			"isSectioned" : <boolean>,
			"sectionOrder" : <string>,
			"circuitType" : "Physical" | "Virtual",
			"startPoint" : //when isSectioned is false
				{
				   "sourceId"   : <short>,
				   "globalId"   : <guid>,
				   "terminalId" : <short>,
				   "firstUnit"  : <short>,
				   "numUnits"   : <short>
				},
			"stopPoint" : //when isSectioned is false
				{
				   "sourceId"   : <short>,
				   "globalId"   : <guid>,
				   "terminalId" : <short>,
				   "firstUnit"  : <short>,
				   "numUnits"   : <short>
				},
			"sections" :  //when isSectioned is true
				{
					"sectionId" : <long>,
					"role" : "Start and end" | "Start" | "End" | "Midspan",
					"sectionType" : "Physical" | "Virtual",
					"startPoint" :
					{
					   "sourceId"   : <short>,
					   "globalId"   : <guid>,
					   "terminalId" : <short>,
					   "firstUnit"  : <short>,
					   "numUnits"   : <short>
					},
					"stopPoint" :
					{
					   "sourceId"   : <short>,
					   "globalId"   : <guid>,
					   "terminalId" : <short>,
					   "firstUnit"  : <short>,
					   "numUnits"   : <short>
					}
				}
		},
		"subcircuits" : [
			{
				"name" : <string>,
				"globalId": <guid>,
				"providerId" : <guid>,
				"consumerId" : <guid>,
				"isReserved" : <boolean>
			}
		]
},
  "success" : <boolean>,
  "error" : {                   // only if success is false
    "extendedCode" : <HRESULT>,
    "message" : <string>,
    "details" : [ <string> ]
}

JSON response when name is specified for resultType with location info:

Use dark colors for code blocksCopy
{
  "f": "json",
  "moment" : <epochtime>,
  "circuits" : [<string>],
    "success" : <true | false>
}
  "error" : {                   // only if success is false
    "extendedCode" : <HRESULT>,
    "message" : <error message>,
    "details" : [ <detail> ]
  }
}

Example usage

Request URL and parameters:

https://myserver.esri.com/server/rest/services/Telco/UtilityNetworkServer/circuits/query

Providing a circuit name for the circuits parameter in a telecom domain network called "Telco" to return circuit information for the nonsectioned circuit.

Use dark colors for code blocksCopy
f=json
gdbVersion=sde.Default
domainNetworkName=Telco
circuits=["79/EDU/322454/000/E3"]
resultType=[circuit]

JSON response:

Use dark colors for code blocksCopy
{
	"circuits": [
		{
			"name": "79/EDU/322454/000/E3",
			"globalId": "{4EFBBE6D-0ED9-42F1-9D78-D38186B0CF85}",
			"isSectioned": false,
			"sectionOrder": "",
			"circuitType" : "Physical",
			"startPoint": {
				"sourceId": 20,
				"globalId": "{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}",
				"terminalId": 1,
				"firstUnit": 1,
				"numUnits": 4
			},
			"stopPoint": {
				"sourceId": 20,
				"globalId": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
				"terminalId": 1,
				"firstUnit": 3,
				"numUnits": 3
			},
			"subcircuits": [
				{
					"name": "S_322454_E3",
					"globalId": "{4BCB013E-AD5A-4598-AA51-256D9C84C145}",
					"providerId": "{4EFBBE6D-0ED9-42F1-9D78-D38186B0CF85}",
					"consumerId": "{4C7153F9-AF75-4838-B489-6B34946F7B1F}",
					"isReserved": false
				}
			]
		}
	],
	"success": true
}

Providing a circuit name for the circuits parameter in a telecom domain network called "Telco" to return circuit information for the sectioned circuit composed of three sections with a subcircuit serving the role of the midspan section.

Use dark colors for code blocksCopy
f=json
gdbVersion=sde.Default
domainNetworkName=Telco
circuits=["A33/T3U/79233987/64456498"]
resultType=[circuit]

JSON response:

Use dark colors for code blocksCopy
{
 "circuits": [
  {
   "name": "A33/T3U/79233987/64456498",
   "globalId": "{4C7153F9-AF75-4838-B489-6B34946F7B1F}",
   "isSectioned": true,
   "sectionOrder": "",
   "circuitType": "Physical",
   "sections": [
    {
     "sectionID": 1,
     "role": "Start",
     "sectionType": "Physical",
     "startPoint": {
      "sourceId": 20,
      "globalId": "{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}",
      "terminalId": 1,
      "firstUnit": 1,
      "numUnits": 1
     },
     "stopPoint": {
      "sourceId": 20,
      "globalId": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
      "terminalId": 1,
      "firstUnit": 1,
      "numUnits": 1
     }
    },
    {
     "sectionID": 2,
     "role": "Midspan",
     "sectionType": "Physical",
     "subcircuit": {
      "name": "S2",
      "globalId": "{4BCB013E-AD5A-4598-AA51-256D9C84C145}",
      "providerId": "{968FD9D8-7200-4311-84E6-76A13CB1AEC8}",
      "consumerId": "{4C7153F9-AF75-4838-B489-6B34946F7B1F}",
      "isReserved": false
     }
    },
    {
     "sectionID": 3,
     "role": "End",
     "sectionType": "Physical",
     "startPoint": {
      "sourceId": 20,
      "globalId": "{5C179F2F-6F70-4B82-AE02-25FEFB457860}",
      "terminalId": 1,
      "firstUnit": 1,
      "numUnits": 1
     },
     "stopPoint": {
      "sourceId": 20,
      "globalId": "{6EF3FE96-61C2-498A-B336-BA3E85F0D39E}",
      "terminalId": 1,
      "firstUnit": 1,
      "numUnits": 1
     }
    }
   ],
   "subcircuits": []
  }
 ],
 "success": true
}

Providing trace location information to return the names of the circuit or circuits associated with the stopping point specified:

Use dark colors for code blocksCopy

f=json
gdbVersion=sde.Default
domainNetworkName=Telco
circuits=
sourceId=20
globalId={F081B917-499E-43FC-AEC9-7C1B313BF128}
terminalId=1
firstUnit=1
NumUnits=1
pointType=stop
returnConsumerCircuits=false
resultType=[name]

JSON response:

Use dark colors for code blocksCopy

{
	"circuitNames": [
		"79/EDU/322454/000/E3"
	],
	"success": true
}