Query (Circuits) | ArcGIS REST APIs

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

The query operation on the circuits resource returns circuits from a telecom domain network that satisfy a specified query. You can provide an array of circuit names or global Ids as the input or provide information for a trace location from which the circuits either start or stop to return circuit information.

The query operates in two different modes, depending on whether you provide the circuit name or global Id, or information for the circuit's stop or stop location.

When a circuit name is provided for the circuits parameter, the circuitIds parameter is ignored.
When a circuit name or globalId is provided for either the circuits or circuitIds parameters, the locations parameter is ignored.
When returning the circuits that start or stop at a specified trace location using the locations parameter, if circuitHierarchy is empty, only the immediate circuits that are pass through the specified feature 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 milliseconds>` 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"]`
`circuitIds` (Optional)	The global Id of the circuit or circuits to be returned. Syntax: Use dark colors for code blocksCopy `1 2 circuitIds=[<guid>]` Example: Use dark colors for code blocksCopy `1 2 circuitIds=["{951B86D2-0614-4104-9756-9247093B5D49}","{0CB55402-05BC-447C-8800-E4EA64853E38}"]`
`locations` (Optional)	Specifies the location information for the feature associated with a circuit's starting or stopping point. The results can be filtered further when used with the `locationType` parameter. `locations` is ignored if the `circuits` or `circuitIds` parameters are used for the query operation. Syntax: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 [ { "sourceId": <long>, "globalId": <guid>, "firstUnit": <short>, "lastUnit": <short> } ]` Example: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 [ { "sourceId": 20, "globalId": "{92B8C364-EB5E-4BCA-A88B-4498B7BEE99D}", "firstUnit": 2, "lastUnit": 2 } ]`
`locationType` (Optional)	The type of trace location in the circuit to query (start location, stop location, or both). The default is `all`. This can be used to filter the results when using `locations` to return circuit information. 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`
`circuitHierarchy` (Optional)	Specifies whether to return the associated consumer and provider circuits with the queried circuit. The default is `None`. Values: `consumers` \| `providers` \| `consumers and providers` \| `none` Syntax: Use dark colors for code blocksCopy `1 2 circuitHierarchy=<string>` Example: Use dark colors for code blocksCopy `1 2 circuitHierarchy=consumers`
`circuitStatus` (Optional)	Specifies whether to filter the result of the query to return only circuits of a certain status. This filter also applies to any circuits returned using the `circuitHierarchy` parameter. `circuitStatus` is empty by default with no filter applied. Note Deleted circuits may only be returned using the default `resultTypes` parameter option of `name`. Values: `clean` \| `dirty` \| `invalid` \| `deleted` Syntax: Use dark colors for code blocksCopy `1 2 circuitStatus=<string>` Example: Use dark colors for code blocksCopy `1 2 circuitStatus=dirty`
`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., 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 milliseconds>

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

circuitIds

(Optional)

The global Id of the circuit or circuits to be returned.

Syntax:

Use dark colors for code blocksCopy

circuitIds=[<guid>]

Example:

Use dark colors for code blocksCopy

circuitIds=["{951B86D2-0614-4104-9756-9247093B5D49}","{0CB55402-05BC-447C-8800-E4EA64853E38}"]

locations

(Optional)

Specifies the location information for the feature associated with a circuit's starting or stopping point. The results can be filtered further when used with the locationType parameter. locations is ignored if the circuits or circuitIds parameters are used for the query operation.

Syntax:

Use dark colors for code blocksCopy

[
  {
    "sourceId": <long>,
    "globalId": <guid>,
    "firstUnit": <short>,
    "lastUnit": <short>
  }
]

Example:

Use dark colors for code blocksCopy

[
  {
    "sourceId": 20,
    "globalId": "{92B8C364-EB5E-4BCA-A88B-4498B7BEE99D}",
    "firstUnit": 2,
    "lastUnit": 2
  }
]

locationType

(Optional)

The type of trace location in the circuit to query (start location, stop location, or both). The default is all. This can be used to filter the results when using locations to return circuit information.

Values: start | stop | all

Syntax:

Use dark colors for code blocksCopy

locationType=<string>

Example:

Use dark colors for code blocksCopy

locationType=start

circuitHierarchy

(Optional)

Specifies whether to return the associated consumer and provider circuits with the queried circuit. The default is None.

Values: consumers | providers | consumers and providers | none

Syntax:

Use dark colors for code blocksCopy

circuitHierarchy=<string>

Example:

Use dark colors for code blocksCopy

circuitHierarchy=consumers

circuitStatus

(Optional)

Specifies whether to filter the result of the query to return only circuits of a certain status. This filter also applies to any circuits returned using the circuitHierarchy parameter. circuitStatus is empty by default with no filter applied.

Values: clean | dirty | invalid | deleted

Syntax:

Use dark colors for code blocksCopy

circuitStatus=<string>

Example:

Use dark colors for code blocksCopy

circuitStatus=dirty

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., 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>,
          "firstUnit"  : <short>,
          "lastUnit"   : <short>
        },
      "stopLocation" : //when isSectioned is false
        {
          "sourceId"   : <short>,
          "globalId"   : <guid>,
          "firstUnit"  : <short>,
          "lastUnit"   : <short>
        },
      "sections" :  //when isSectioned is true
        {
          "sectionId" : <long>,
          "globalId" : <guid>,
          "role" : "Start and end" | "Start" | "End" | "Midspan",
          "sectionType" : "Physical" | "Virtual",
          "startLocation" :
            {
              "sourceId"   : <short>,
              "globalId"   : <guid>,
              "firstUnit"  : <short>,
              "lastUnit"   : <short>
            },
          "stopLocation" :
            {
              "sourceId"   : <short>,
              "globalId"   : <guid>,
              "firstUnit"  : <short>,
              "lastUnit"   : <short>
            }
        },
        "attributes":{}
        },
      "subcircuits" : [
        {
             "name" : <string>,
             "globalId": <guid>,
             "providerId" : <guid>,
             "consumerId" : <guid>,
             "state": "Consumed" | "Reserved" | "Available",               // Default is Available
             "attributes": {}
        }
      ],
      "attributes": {}
    }
  ],
  "success": <boolean>,
  "error" : {                   // only if success is false
    "extendedCode" : <HRESULT>,
    "message" : <string>,
    "details" : [ <string> ]
}

JSON response when name is specified for resultTypes:

Use dark colors for code blocksCopy
{
  "circuitNames": [<string>],
  "success": <boolean>
}
  "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 with a subcircuit.

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": "{117F6890-A8B4-4DFF-97EB-D9D6A4C5C8B8}",
      "status": "Clean",
      "isSectioned": false,
      "lastExportedTime": 1767630218000,
      "lastVerifiedTime": 1768589489000,
      "circuitType": "Physical",
      "startLocation": {
        "sourceId": 20,
        "globalId": "{B03E4786-2A0A-43E9-B800-C63A837E3525}",
        "firstUnit": 1,
        "lastUnit": 4
      },
      "stopLocation": {
        "sourceId": 20,
        "globalId": "{8A6CE597-EE12-4957-B05F-551692A41596}",
        "firstUnit": 3,
        "lastUnit": 7
      },
      "subcircuits": [
      {
        "name": "S_322454_E3",
        "globalId": "{4BCB013E-AD5A-4598-AA51-256D9C84C145}",
        "providerId": "{117F6890-A8B4-4DFF-97EB-D9D6A4C5C8B8}",
        "consumerId": "{4C7153F9-AF75-4838-B489-6B34946F7B1F}",
        "state": "Consumed",
        "attributes": {}
      }
    ],
      "attributes": {
        "Bandwidth": null
      }
    }
  ],
  "success": true
}

Providing a circuit name for the circuits parameter in a telecom domain network called "Telco" to return circuit information for a 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
circuitIds=["{4C7153F9-AF75-4838-B489-6B34946F7B1F}"]
resultTypes=[circuit]

JSON response:

Use dark colors for code blocksCopy
{
  "circuits": [
    {
      "name": "A33/T3U/79233987/64456498",
      "globalId": "{4C7153F9-AF75-4838-B489-6B34946F7B1F}",
      "status": "Clean",
      "isSectioned": true,
      "lastExportedTime": 1769376298000,
      "lastVerifiedTime": 1769376252000,
      "sectionOrder": {
        "1": [2],
        "2": [3],
        "3": []
      },
      "circuitType": "Physical",
      "sections": [
        {
          "sectionId": 1,
          "globalId": "{B444C8D8-11C3-42B9-8A0A-07EC6B5AE23F}",
          "role": "Start",
          "sectionType": "Physical",
          "startLocation": {
            "sourceId": 20,
            "globalId": "{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}",
            "firstUnit": 1,
            "lastUnit": 1
          },
          "stopLocation": {
            "sourceId": 20,
            "globalId": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
            "firstUnit": 1,
            "lastUnit": 1
          },
          "attributes": {}
        },
        {
          "sectionId": 2,
          "globalId": "{9ED4B0E2-CADA-4385-80D3-D4A999197FA8}",
          "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}",
            "state": "Consumed"
          },
          "attributes": {}
        },
        {
          "sectionId": 3,
          "globalId": "{F88413EB-7E88-4D9F-A005-C7E13422B82A}",
          "role": "End",
          "sectionType": "Physical",
          "startLocation": {
            "sourceId": 20,
            "globalId": "{5C179F2F-6F70-4B82-AE02-25FEFB457860}",
            "firstUnit": 1,
            "lastUnit": 1
          },
          "stopLocation": {
            "sourceId": 20,
            "globalId": "{6EF3FE96-61C2-498A-B336-BA3E85F0D39E}",
            "firstUnit": 1,
            "lastUnit": 1
          },
          "attributes": {}
        }
      ],
      "subcircuits": [],
      "attributes": {}
    }
  ],
  "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
locations=
[
  {
    "sourceId": 20,
    "globalId": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
    "firstUnit": 1,
    "lastUnit": 1
  }
]

locationType=stop
resultTypes=[name]

JSON response:

Use dark colors for code blocksCopy

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