PT EN

Topologia: Percursos

URL base: $BUSINESS_API

Seguir a rede a montante

Registos

GET /topology/trace/upstream

Walks against the flow direction from a start node to find what feeds it, returning each reached node with its depth in links and the links traversed; the start node itself is not listed. By default closed links and inactive nodes stop the trace. Responds 400 when node_id is missing and 404 when it is not a topology node; requires network read access.

Parâmetros

node_idstring · consulta · obrigatório

Required ID of the topology node to trace back from.

include_closedboolean · consulta · opcional

Boolean (true or false, default false); when true the trace also passes through closed links and continues past inactive nodes.

Devolve

200 Trace

Mostrar atributos
start_node_idstring · opcional
directionstring · opcional

um de upstream, downstream

include_closedboolean · opcional
nodesarray of object · opcional
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
node_codestring · obrigatório
namestring · obrigatório
node_typestring · obrigatório

um de source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · obrigatório
storage_capacity_m3integer (int64) · obrigatório
latitudenumber · obrigatório
longitudenumber · obrigatório
activeboolean · obrigatório
service_area_idstring · opcional
dma_idstring · opcional
device_idstring · opcional

Level or flow device reporting measurements

meter_idstring · opcional

Customer meter attributed to a customer_tap

meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
depthinteger · opcional
linksarray of TopologyLink · opcional
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
link_codestring · obrigatório
from_node_idstring · obrigatório
to_node_idstring · obrigatório
link_typestring · obrigatório

um de gravity_main, pumping_main, distribution_pipe, control_valve

length_metersnumber · obrigatório
diameter_mminteger · obrigatório
roughness_coefficientinteger · obrigatório

Hazen-Williams C

statusstring · obrigatório

um de open, closed, throttled

asset_idstring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Permissões network:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/trace/upstream" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "start_node_id": "sta_2r9QwjrYCzhCIxhykbbmgFLiy1J",
  "direction": "upstream",
  "include_closed": true,
  "nodes": [
    {
      "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_code": "NOD-2026-000142",
      "name": "Ana Matsinhe",
      "node_type": "source_river",
      "elevation_meters": 1,
      "storage_capacity_m3": 1,
      "latitude": -25.9653,
      "longitude": 32.5892,
      "active": true,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z",
      "depth": 1
    }
  ],
  "links": [
    {
      "id": "top_26ATL6Y7Pm2ppeMTl60jhySNHae",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "link_code": "LIN-2026-000142",
      "from_node_id": "fro_2b3GWtBsQPTMCF5SOjDUUp7QKHr",
      "to_node_id": "ton_2qKn74u1zmYRZmiRFqqbFqoplME",
      "link_type": "gravity_main",
      "length_meters": 1,
      "diameter_mm": 1,
      "roughness_coefficient": 1,
      "status": "open",
      "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Seguir a rede a jusante

Registos

GET /topology/trace/downstream

Follows the flow direction from a start node and returns every node it reaches with its depth in links from the start, plus the links traversed; the start node itself is not listed. By default closed links and inactive nodes stop the trace. Responds 400 when node_id is missing and 404 when it is not a topology node; requires network read access.

Parâmetros

node_idstring · consulta · obrigatório

Required ID of the topology node to start the trace from.

include_closedboolean · consulta · opcional

Boolean (true or false, default false); when true the trace also passes through closed links and continues past inactive nodes, showing what the network reaches once valves are opened.

Devolve

200 Trace

Mostrar atributos
start_node_idstring · opcional
directionstring · opcional

um de upstream, downstream

include_closedboolean · opcional
nodesarray of object · opcional
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
node_codestring · obrigatório
namestring · obrigatório
node_typestring · obrigatório

um de source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · obrigatório
storage_capacity_m3integer (int64) · obrigatório
latitudenumber · obrigatório
longitudenumber · obrigatório
activeboolean · obrigatório
service_area_idstring · opcional
dma_idstring · opcional
device_idstring · opcional

Level or flow device reporting measurements

meter_idstring · opcional

Customer meter attributed to a customer_tap

meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
depthinteger · opcional
linksarray of TopologyLink · opcional
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
link_codestring · obrigatório
from_node_idstring · obrigatório
to_node_idstring · obrigatório
link_typestring · obrigatório

um de gravity_main, pumping_main, distribution_pipe, control_valve

length_metersnumber · obrigatório
diameter_mminteger · obrigatório
roughness_coefficientinteger · obrigatório

Hazen-Williams C

statusstring · obrigatório

um de open, closed, throttled

asset_idstring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Permissões network:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/trace/downstream" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "start_node_id": "sta_2r9QwjrYCzhCIxhykbbmgFLiy1J",
  "direction": "upstream",
  "include_closed": true,
  "nodes": [
    {
      "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_code": "NOD-2026-000142",
      "name": "Ana Matsinhe",
      "node_type": "source_river",
      "elevation_meters": 1,
      "storage_capacity_m3": 1,
      "latitude": -25.9653,
      "longitude": 32.5892,
      "active": true,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z",
      "depth": 1
    }
  ],
  "links": [
    {
      "id": "top_26ATL6Y7Pm2ppeMTl60jhySNHae",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "link_code": "LIN-2026-000142",
      "from_node_id": "fro_2b3GWtBsQPTMCF5SOjDUUp7QKHr",
      "to_node_id": "ton_2qKn74u1zmYRZmiRFqqbFqoplME",
      "link_type": "gravity_main",
      "length_meters": 1,
      "diameter_mm": 1,
      "roughness_coefficient": 1,
      "status": "open",
      "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Encontrar as válvulas a fechar

Registos

GET /topology/trace/valve-isolation

Which valves take a link out of service and what loses supply

Compares network-wide supply before and after, so a node fed by another path is not reported isolated.

Parâmetros

link_idstring · consulta · obrigatório

Required ID of the topology link to take out of service; the response lists the valves to close (the link itself when it is a valve), the nodes that lose supply and those still fed by another path.

Devolve

200 Isolation analysis

Mostrar atributos
link_idstring · opcional
closed_valvesarray of TopologyLink · opcional
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
link_codestring · obrigatório
from_node_idstring · obrigatório
to_node_idstring · obrigatório
link_typestring · obrigatório

um de gravity_main, pumping_main, distribution_pipe, control_valve

length_metersnumber · obrigatório
diameter_mminteger · obrigatório
roughness_coefficientinteger · obrigatório

Hazen-Williams C

statusstring · obrigatório

um de open, closed, throttled

asset_idstring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
isolated_nodesarray of TopologyNode · opcional
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
node_codestring · obrigatório
namestring · obrigatório
node_typestring · obrigatório

um de source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · obrigatório
storage_capacity_m3integer (int64) · obrigatório
latitudenumber · obrigatório
longitudenumber · obrigatório
activeboolean · obrigatório
service_area_idstring · opcional
dma_idstring · opcional
device_idstring · opcional

Level or flow device reporting measurements

meter_idstring · opcional

Customer meter attributed to a customer_tap

meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
still_supplied_nodesarray of TopologyNode · opcional
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
node_codestring · obrigatório
namestring · obrigatório
node_typestring · obrigatório

um de source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · obrigatório
storage_capacity_m3integer (int64) · obrigatório
latitudenumber · obrigatório
longitudenumber · obrigatório
activeboolean · obrigatório
service_area_idstring · opcional
dma_idstring · opcional
device_idstring · opcional

Level or flow device reporting measurements

meter_idstring · opcional

Customer meter attributed to a customer_tap

meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
affected_customer_tapsinteger · opcional
unisolableboolean · opcional

A pipe has an upstream path to a source with no valve

already_closedboolean · opcional

Permissões network:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/trace/valve-isolation" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "link_id": "lin_2QKtDAGrlWKVjKUX5USfBwe1zSi",
  "closed_valves": [
    {
      "id": "top_26ATL6Y7Pm2ppeMTl60jhySNHae",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "link_code": "LIN-2026-000142",
      "from_node_id": "fro_2b3GWtBsQPTMCF5SOjDUUp7QKHr",
      "to_node_id": "ton_2qKn74u1zmYRZmiRFqqbFqoplME",
      "link_type": "gravity_main",
      "length_meters": 1,
      "diameter_mm": 1,
      "roughness_coefficient": 1,
      "status": "open",
      "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "isolated_nodes": [
    {
      "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_code": "NOD-2026-000142",
      "name": "Ana Matsinhe",
      "node_type": "source_river",
      "elevation_meters": 1,
      "storage_capacity_m3": 1,
      "latitude": -25.9653,
      "longitude": 32.5892,
      "active": true,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "still_supplied_nodes": [
    {
      "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_code": "NOD-2026-000142",
      "name": "Ana Matsinhe",
      "node_type": "source_river",
      "elevation_meters": 1,
      "storage_capacity_m3": 1,
      "latitude": -25.9653,
      "longitude": 32.5892,
      "active": true,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "affected_customer_taps": 1,
  "unisolable": true,
  "already_closed": true
}