Query (Circuits) | ArcGIS REST APIs

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 lastUnit parameters are ignored. When returning the circuits that start or stop at a specified trace location (i.e., using sourceId, globalId, terminalId, firstUnit, and lastUnit 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`. Values: `html` \| `json` \| `pjson`
`gdbVersion` (Optional)	Specifies the name of the geodatabase version. The default is 'sde.DEFAULT'. Syntax: Use dark colors for code blocksCopy `1 2 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: Use dark colors for code blocksCopy `1 2 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: Use dark colors for code blocksCopy `1 2 moment=<Epoch time in seconds>` Example: Use dark colors for code blocksCopy `1 2 moment=1730456642`
`domainNetworkName` (Required)	Specifies the name of the telecom domain network containing the circuits to be queried. Syntax: Use dark colors for code blocksCopy `1 2 domainNetworkName=<string>` Example: Use dark colors for code blocksCopy `1 2 domainNetworkName=Telco`
`circuits` (Optional)	The names of the circuit or circuits to be returned. Syntax: Use dark colors for code blocksCopy `1 2 circuits=[<string>]` Example: Use dark colors for code blocksCopy `1 2 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: Use dark colors for code blocksCopy `1 2 sourceId=<short>` Example: Use dark colors for code blocksCopy `1 2 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: Use dark colors for code blocksCopy `1 2 globalId=<guid>` Example: Use dark colors for code blocksCopy `1 2 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: Use dark colors for code blocksCopy `1 2 terminalId=<short>` Example: Use dark colors for code blocksCopy `1 2 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: Use dark colors for code blocksCopy `1 2 firstUnit=<short>` Example: Use dark colors for code blocksCopy `1 2 firstUnit=1`
`lastUnit` (Optional)	The last unit identifier for the starting or stopping point. This is required when trace location parameters are used instead of `circuit`. Syntax: Use dark colors for code blocksCopy `1 2 lastUnit=<short>` Example: Use dark colors for code blocksCopy `1 2 lastUnit=3`
`locationType` (Optional)	The type of trace location in the circuit to query (starting location, stopping location, or both). The default is `all`. Values: `start` \| `stop` \| `all` Syntax: Use dark colors for code blocksCopy `1 2 locationType=<string>` Example: Use dark colors for code blocksCopy `1 2 locationType=start`
`returnConsumerCircuits` (Optional)	Specifies whether to return the names of all consumer circuits. The default is `false`. Values: `true` \| `false` Syntax: Use dark colors for code blocksCopy `1 2 returnConsumerCircuits=<boolean>` Example: Use dark colors for code blocksCopy `1 2 returnConsumerCircuits=false`
`resultTypes` (Optional)	The type of information to return about the circuit. Use `circuit` to return all information that defines a circuit including the 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`. Values: `name` \| `circuit` Syntax: Use dark colors for code blocksCopy `1 2 resultTypes=[<resultType>]` Example: Use dark colors for code blocksCopy `1 2 resultTypes=[name, circuit]`

f

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

Values: html | json | pjson

gdbVersion

(Optional)

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

Syntax:

Use dark colors for code blocksCopy

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:

Use dark colors for code blocksCopy

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:

Use dark colors for code blocksCopy

moment=<Epoch time in seconds>

Example:

Use dark colors for code blocksCopy

moment=1730456642

domainNetworkName

(Required)

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

Syntax:

Use dark colors for code blocksCopy

domainNetworkName=<string>

Example:

Use dark colors for code blocksCopy

domainNetworkName=Telco

circuits

(Optional)

The names of the circuit or circuits to be returned.

Syntax:

Use dark colors for code blocksCopy

circuits=[<string>]

Example:

Use dark colors for code blocksCopy

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:

Use dark colors for code blocksCopy

sourceId=<short>

Example:

Use dark colors for code blocksCopy

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:

Use dark colors for code blocksCopy

globalId=<guid>

Example:

Use dark colors for code blocksCopy

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:

Use dark colors for code blocksCopy

terminalId=<short>

Example:

Use dark colors for code blocksCopy

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:

Use dark colors for code blocksCopy

firstUnit=<short>

Example:

Use dark colors for code blocksCopy

firstUnit=1

lastUnit

(Optional)

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

Syntax:

Use dark colors for code blocksCopy

lastUnit=<short>

Example:

Use dark colors for code blocksCopy

lastUnit=3

locationType

(Optional)

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

Values: start | stop | all

Syntax:

Use dark colors for code blocksCopy

locationType=<string>

Example:

Use dark colors for code blocksCopy

locationType=start

returnConsumerCircuits

(Optional)

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

Values: true | false

Syntax:

Use dark colors for code blocksCopy

returnConsumerCircuits=<boolean>

Example:

Use dark colors for code blocksCopy

returnConsumerCircuits=false

resultTypes

(Optional)

The type of information to return about the circuit. Use circuit to return all information that defines a circuit including the 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.

Values: name | circuit

Syntax:

Use dark colors for code blocksCopy

resultTypes=[<resultType>]

Example:

Use dark colors for code blocksCopy

resultTypes=[name, circuit]

JSON Response syntax

JSON response when circuit is specified for resultTypes:

Use dark colors for code blocksCopy
{
  "circuits":[
    {
      "name" : <string>,
      "globalId" : <guid>,
      "status" : <string>,
      "isSectioned" : <boolean>,
      "sectionOrder" : <string>, //when isSectioned is true
      "circuitType" : "Physical" | "Virtual",
      "startLocation" : //when isSectioned is false
        {
          "sourceId"   : <short>,
          "globalId"   : <guid>,
          "terminalId" : <short>,
          "firstUnit"  : <short>,
          "lastUnit"   : <short>
        },
      "stopLocation" : //when isSectioned is false
        {
          "sourceId"   : <short>,
          "globalId"   : <guid>,
          "terminalId" : <short>,
          "firstUnit"  : <short>,
          "lastUnit"   : <short>
        },
      "sections" :  //when isSectioned is true
        {
          "sectionId" : <long>,
          "role" : "Start and end" | "Start" | "End" | "Midspan",
          "sectionType" : "Physical" | "Virtual",
          "startLocation" :
            {
              "sourceId"   : <short>,
              "globalId"   : <guid>,
              "terminalId" : <short>,
              "firstUnit"  : <short>,
              "lastUnit"   : <short>
            },
          "stopLocation" :
            {
              "sourceId"   : <short>,
              "globalId"   : <guid>,
              "terminalId" : <short>,
              "firstUnit"  : <short>,
              "lastUnit"   : <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 resultTypes 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:

Use dark colors for code blocksCopy

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"]
resultTypes=[circuit]

JSON response:

Use dark colors for code blocksCopy
{
  "circuits": [
  {
    "name": "79/EDU/322454/000/E3",
    "globalId": "{4EFBBE6D-0ED9-42F1-9D78-D38186B0CF85}",
    "isSectioned": false,
    "circuitType": "Physical",
    "startLocation": {
      "sourceId": 20,
      "globalId": "{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}",
      "terminalId": 1,
      "firstUnit": 1,
      "lastUnit": 4
    },
    "stopLocation": {
      "sourceId": 20,
      "globalId": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
      "terminalId": 1,
      "firstUnit": 3,
      "lastUnit": 7
    },
    "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"]
resultTypes=[circuit]

JSON response:

Use dark colors for code blocksCopy
{
 "circuits": [
  {
   "name": "A33/T3U/79233987/64456498",
   "globalId": "{4C7153F9-AF75-4838-B489-6B34946F7B1F}",
   "isSectioned": true,
   "sectionOrder": {
     "1": [2],
     "2": [3],
     "3": []
    },
   "circuitType": "Physical",
   "sections": [
    {
     "sectionID": 1,
     "role": "Start",
     "sectionType": "Physical",
     "startLocation": {
      "sourceId": 20,
      "globalId": "{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}",
      "terminalId": 1,
      "firstUnit": 1,
      "lastUnit": 1
     },
     "stopLocation": {
      "sourceId": 20,
      "globalId": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
      "terminalId": 1,
      "firstUnit": 1,
      "lastUnit": 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",
     "startLocation": {
      "sourceId": 20,
      "globalId": "{5C179F2F-6F70-4B82-AE02-25FEFB457860}",
      "terminalId": 1,
      "firstUnit": 1,
      "lastUnit": 1
     },
     "stopLocation": {
      "sourceId": 20,
      "globalId": "{6EF3FE96-61C2-498A-B336-BA3E85F0D39E}",
      "terminalId": 1,
      "firstUnit": 1,
      "lastUnit": 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
lastUnit=1
locationType=stop
returnConsumerCircuits=false
resultTypes=[name]

JSON response:

Use dark colors for code blocksCopy

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