> ## Documentation Index > Fetch the complete documentation index at: https://support.keypro.fi/llms.txt > Use this file to discover all available pages before exploring further. # Compare a TV observation against its snsewerduct > Operation is used to compare a TV (CCTV) observation's duct-attribute fields against a snsewerduct object: the duct confirmed for the observation's inspection when there is one, otherwise the nearest snsewerduct within tolerance, auto-matched by GIS proximity. The confirmed link wins because it is the duct the apply endpoint writes to. Form, material and dimension are compared, matched the way `/tv-inspection/apply-duct-diff/` resolves them: the form against the duct's DuctProfile text, material and dimension against its duct type. The other fields have no counterpart on the duct, so their `keyaqua_value` is null and they never differ. A field the inspection left empty never differs either: there is nothing to apply from it. A confirmed link to a duct that has since been deleted compares against nothing: the apply endpoint refuses it, so a nearby duct would only invite a write that cannot happen. `status` is what a duct graph colours the observation by: `disabled_from_update` when a user disabled it (whatever the comparison says); `not_compared` when no duct matched, or the observation records none of form, material and dimension (most defect observations); `needs_attention` when any field differs - also after a "Not update" review, which records a decision rather than a match; and `all_good` otherwise. ## OpenAPI ````json POST /tv-observation-comparison/ { "openapi": "3.0.4", "info": { "title": "Keyduct REST API", "termsOfService": "https://www.keypro.fi/en/terms-of-service", "contact": { "name": "Keypro Oy", "url": "https://keypro.fi/", "email": "keypro@keypro.fi" }, "license": { "name": "Copyright (C) Keypro Oy. All rights reserved.", "url": "https://www.keypro.fi/" }, "version": "2.0.0" }, "servers": [ { "url": "/api/v2" } ], "tags": [ { "name": "Task", "description": "Task related operations." }, { "name": "Subregion", "description": "Subregion related operations." }, { "name": "SAttribute", "description": "SAttribute related operations." }, { "name": "Fault", "description": "Fault related operations." }, { "name": "Maintenance history", "description": "Maintenance history related operations." }, { "name": "Deflection", "description": "Deflection related operations." }, { "name": "Fault Component", "description": "Fault Component related operations." }, { "name": "Task Comment", "description": "Task comment related operations." }, { "name": "FaultComponentFault", "description": "FaultComponentFault related operations." }, { "name": "Collections", "description": "Collection related operations." }, { "name": "Contact Person", "description": "ContactPerson related operations" }, { "name": "Contact Person Connection", "description": "ContactPersonConnection related operations" }, { "name": "Plan", "description": "Plan related operations." }, { "name": "FreeArea", "description": "FreeArea related operations." }, { "name": "Address", "description": "Building address related operations." }, { "name": "Apartment", "description": "Building apartments related operations." }, { "name": "Customer", "description": "Customer data related operations." }, { "name": "Customer Contract", "description": "Customer contract related operations." }, { "name": "Extra Attribute", "description": "Extra attributes related operations." }, { "name": "Extra Value", "description": "Extra attribute values related operations." }, { "name": "Consumer Point", "description": "Consumer point related operations." }, { "name": "Consumer Point Linked Address", "description": "Consumer point address link related operations." }, { "name": "Flow Meter", "description": "Flow Meter related operations." }, { "name": "Text Constant", "description": "Text Constant related operations." }, { "name": "Sn Constant", "description": "Sn Constant related operations." }, { "name": "Gas Meter", "description": "Gas Meter related operations." }, { "name": "Junction", "description": "Junction related operations." }, { "name": "Junction Connection", "description": "Junction Connection related operations." }, { "name": "External Document", "description": "External documents related operations." }, { "name": "Water Duct Renovation", "description": "Water duct renovation related operations." }, { "name": "Sewer Duct Renovation", "description": "Sewer duct renovation related operations." }, { "name": "Water Duct", "description": "Water duct related operations." }, { "name": "Water Other Node", "description": "Water other node related operations." }, { "name": "Water Hydrant", "description": "Water hydrant related operations." }, { "name": "Water Branch", "description": "Water branch related operations." }, { "name": "Water Measuring Point", "description": "Water measuring point related operations." }, { "name": "Fire Water Station", "description": "Fire water station related operations." }, { "name": "Water Fireplug", "description": "Water fireplug related operations." }, { "name": "Sewer Duct", "description": "Sewer duct related operations." }, { "name": "Flow Meter Reading", "description": "Flow Meter Reading related operations." }, { "name": "Gas Meter Reading", "description": "Gas meter reading related operations." }, { "name": "Gas Cable", "description": "Gas cable related operations." }, { "name": "Gas Other Node", "description": "Gas other node related operations." }, { "name": "Gas Valve", "description": "Gas valve related operations." }, { "name": "Water Node", "description": "Water node related operations." }, { "name": "Consumer Point Property", "description": "Consumer point property related operations." }, { "name": "Dh Manhole", "description": "Dh manhole related operations." }, { "name": "Dh Manhole Link Connection", "description": "Dh Manhole Link Connection related operations." }, { "name": "Dh Cable", "description": "Dh cable related operations." }, { "name": "Error Report", "description": "Error report related operations." }, { "name": "Failure Report", "description": "Failure report related operations." }, { "name": "DCCTV Comparison", "description": "DCCTV comparison (nearest object lookup + manual pick) related operations." }, { "name": "TV Inspection", "description": "CCTV TV inspection related operations." }, { "name": "Manhole Inspection", "description": "Manhole inspection related operations." }, { "name": "Dh Duct", "description": "Dh duct related operations." }, { "name": "Dh Conduit", "description": "Dh conduit related operations." }, { "name": "Dh Division", "description": "Dh division related operations." }, { "name": "Dh Valve", "description": "Dh valve related operations." }, { "name": "Consumer Point User", "description": "Consumer Point User related operations." }, { "name": "Consumer Point Real Estate", "description": "Consumer point real estate related operations." }, { "name": "Consumer Point User Email", "description": "Consumer point user email related operations." }, { "name": "Water Pumping Station", "description": "Water pumping station related operations." }, { "name": "Dh Meter Reading", "description": "Dh Meter Reading related operations." }, { "name": "Consumer Point Connection", "description": "Consumer point connection related operations." }, { "name": "Modeling Data", "description": "Modeling data related operations.\n\n*NOTE:* Contrary to what is described in chapter 1.5, the base path for all of these operations is `/keyaqua_modeling`\n" }, { "name": "Gas Manhole", "description": "Gas manhole related operations." }, { "name": "KeyDh Observation", "description": "KeyDh Observation related operations." }, { "name": "KeyDh Supply Interruption", "description": "KeyDh Supply Interruption related operations." }, { "name": "KeyDh Supply Interruption Connection", "description": "KeyDh Supply Interruption Connection related operations." }, { "name": "Keydh Node", "description": "Keydh Node related operations." }, { "name": "Keygas Duct", "description": "Keygas Duct related operations." }, { "name": "Real Estate", "description": "Real Estate related operations." }, { "name": "Keydh Connection", "description": "Keydh Connection related operations." }, { "name": "Water Tank", "description": "Water Tank related operations." }, { "name": "Water Valve", "description": "Water Valve related operations." }, { "name": "Point", "description": "Point related operations." }, { "name": "Sn Modeling", "description": "Sn Modeling related operations." }, { "name": "Sewer Manholes v2", "description": "Sewer Manholes v2 related operations." }, { "name": "Sewer Ducts", "description": "Sewer Ducts related operations." }, { "name": "Sewer Valves", "description": "Sewer Valves related operations." }, { "name": "Sewer Pumping Stations", "description": "Sewer Pumping Stations related operations." }, { "name": "Sewer Branches", "description": "Sewer Branches related operations." }, { "name": "Sewer Measuring Poins", "description": "Sewer Measuring Poins related operations." }, { "name": "Sewer Other Nodes", "description": "Sewer Other Nodes related operations." }, { "name": "Keydh Conduit Link", "description": "Keydh Conduit Link related operations." }, { "name": "Duct Condition Detail", "description": "Duct condition detail related operations." }, { "name": "KeyDh Conduit Error", "description": "KeyDh Conduit Error related operations." }, { "name": "AquaObjectType", "description": "AquaObjectType related operations." }, { "name": "AquaMeasuringPointTypes", "description": "AquaMeasuringPointTypes related operations." }, { "name": "AquaPumpType", "description": "AquaPumpType related operations." }, { "name": "AquaBranchType", "description": "AquaBranchType related operations." }, { "name": "AquaValveType", "description": "AquaValveType related operations." }, { "name": "AquaManholeType", "description": "AquaManholeType related operations." }, { "name": "AquaDuctType", "description": "AquaDuctType related operations." }, { "name": "SnDuctType", "description": "SnDuctType related operations." }, { "name": "SnManholeType", "description": "SnManholeType related operations." }, { "name": "SnLidType", "description": "SnLidType related operations." }, { "name": "Sewer Nodes", "description": "Sewer Node related operations." }, { "name": "Sn Control", "description": "Sn Control related operations." }, { "name": "KeyDh Shell Type", "description": "KeyDh Shell Type related operations." }, { "name": "Sewer Branch Type", "description": "Sewer Branch Type related operations." }, { "name": "Sewer Valve Type", "description": "Sewer Valve Type related operations." } ], "paths": { "/tv-observation-comparison/": { "post": { "tags": [ "DCCTV Comparison" ], "summary": "Compare a TV observation against its snsewerduct", "description": "Operation is used to compare a TV (CCTV) observation's duct-attribute\nfields against a snsewerduct object: the duct confirmed for the\nobservation's inspection when there is one, otherwise the nearest\nsnsewerduct within tolerance, auto-matched by GIS proximity. The confirmed\nlink wins because it is the duct the apply endpoint writes to.\n\nForm, material and dimension are compared, matched the way\n`/tv-inspection/apply-duct-diff/` resolves them: the form against the\nduct's DuctProfile text, material and dimension against its duct type. The\nother fields have no counterpart on the duct, so their `keyaqua_value` is\nnull and they never differ. A field the inspection left empty never\ndiffers either: there is nothing to apply from it.\n\nA confirmed link to a duct that has since been deleted compares against\nnothing: the apply endpoint refuses it, so a nearby duct would only invite a\nwrite that cannot happen.\n\n`status` is what a duct graph colours the observation by:\n`disabled_from_update` when a user disabled it (whatever the comparison\nsays); `not_compared` when no duct matched, or the observation records none\nof form, material and dimension (most defect observations); `needs_attention`\nwhen any field differs - also after a \"Not update\" review, which records a\ndecision rather than a match; and `all_good` otherwise.\n", "operationId": "postTvObservationComparison", "requestBody": { "content": { "application/json": { "schema": { "required": [ "tv_observation_id" ], "type": "object", "properties": { "tolerance": { "type": "number", "description": "Maximum auto-match distance in meters. Defaults to 0.2 (20 cm).", "format": "float" }, "tv_observation_id": { "type": "integer", "description": "Id of the TV observation to compare" } } } } }, "required": true, "x-bodyName": "comparison" }, "responses": { "200": { "description": "Comparison result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TvObservationComparisonResponse" } } } }, "400": { "description": "There was an error in request. Usually field validation failed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "description": "List of validation errors for this fieldname" }, "description": "Fields which failed validation" } } } }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "description": "The user may not view this TV inspection or the sewer ducts it is compared against.", "content": { "application/json": {} } }, "404": { "$ref": "#/components/responses/Http404" } }, "security": [ { "Token": [] } ] } } }, "components": { "schemas": { "TvObservationComparisonResponse": { "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ComparisonField" } }, "matched_snsewerduct_id": { "type": "integer", "description": "Id of the snsewerduct compared against - the inspection's confirmed duct, else the nearest within tolerance. Null if none." }, "review_state": { "enum": [ "updated", "reviewed", "disabled_from_update" ], "type": "string", "description": "The observation's review state. Null if nobody has judged it.", "nullable": true }, "status": { "enum": [ "disabled_from_update", "not_compared", "needs_attention", "all_good" ], "type": "string", "description": "What a duct graph colours the observation by" } } }, "ComparisonField": { "type": "object", "properties": { "differs": { "type": "boolean", "description": "Whether the two values disagree. Null when no verdict can be reached -\nthe inspector recorded nothing, or the comparison returns a placeholder -\nso \"not comparable\" is never rendered as agreement.\n" }, "field": { "type": "string", "description": "Field name being compared" }, "inspection_value": { "type": "object", "description": "Value from the inspection record. FK fields are shown as a nested {id, txt} object." }, "keyaqua_value": { "type": "object", "description": "Value from the matched KeyAqua network object. The connection comparison\nreturns the duct's own value here; the inspection and observation\ncomparisons still return a placeholder null.\n" } } }, "ErrorDetailsResponse": { "required": [ "details" ], "type": "object", "properties": { "details": { "type": "string", "description": "Detailed description of error" } }, "description": "Standard error response payload" } }, "responses": { "Http401": { "description": "Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailsResponse" }, "example": { "details": "Authentication credentials were not provided" } } } }, "Http404": { "description": "Object was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailsResponse" }, "example": { "details": "Not found." } } } } }, "securitySchemes": { "Token": { "type": "apiKey", "description": "Token issued for API consumer.", "name": "Authorization", "in": "header" } } } } ````