diagnose()

Broadband Diagnostics API

The diagnose() function triggers a request with KPN to perform a diagnostic routine and return the results.

The KPN functions are allowed to process the request asynchronously. When they do, this function returns a uuid that can be used to poll for results.

When KPN processes the request immediately the result is directly returned by diagnose().

Regardless of the (a)synchronous behaviour of the function, diagnostic data produced by KPN is preserved during at least 30 days and can be fetched using the list_reports() and get_report() functions.

Method

diagnose

Important

The port_status diagnostic and the line_analysis check are restricted in the number of total and concurrent requests per day. When these limits are exceeded the both requests are rejected during the rest of the day.

As this impacts all users of the API constraint in requesting these diagnostics is advised.

Input

Diagnose request v1

https://api.nextpertise.nl/schemas/broadband/diagnostics/diagnose_request_v1.json
Requests a diagnostic report of a designated circuit.
type object
properties
  • kind
Defines the requested report type
type string
enum port_status, line_analysis
  • nid
Broadband NID
additionalProperties False

Currently there are two diagnostic function you can invoke:

port_status
Query the DSLAM for line properties
line_analysis
Perform a single-ended line test check for a particular service instance

Output

Example

port-status

Request

curl -s -u 'user:pass' https://api.nextpertise.nl/broadband/diagnostics/v1 -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "diagnose",
    "params": {
        "kind": "port_status",
        "nid": "2408ZE000100102"
    }
}' | jq .

Reply

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "kind": "port_status",
        "status": [
            {
                "operation": {
                    "stability": "STABLE",
                    "linesync": "true",
                    "laststatus": "20180129130244"
                },
                "configuration": {
                    "cpetype": "Unknown",
                    "dsltype": "non.shdsl.opermode vdsl2.g9932.profile.17a, line.type.pots,g.inp,sra,vectored"
                },
                "parameter": {
                    "lqd.parameter.power": {
                        "downstream": "12.9",
                        "unit": "dBm",
                        "upstream": "-8.2"
                    },
                    "lqd.parameter.actual.bitrate": {
                        "downstream": "51998.0",
                        "unit": "kb/s",
                        "upstream": "10448.0"
                    },
                    "lqd.parameter.actual.psd": {
                        "downstream": "-57.3",
                        "unit": "dBm/Hz",
                        "upstream": "-75.1"
                    },
                    "lqd.parameter.noise.margin": {
                        "downstream": "20.8",
                        "unit": "dB",
                        "upstream": "16.5"
                    },
                    "lqd.parameter.attainable.bitrate": {
                        "downstream": "103312.0",
                        "unit": "kb/s",
                        "upstream": "28027.0"
                    },
                    "lqd.parameter.attenuation": {
                        "downstream": "14.7",
                        "unit": "dB",
                        "upstream": "12.1"
                    },
                    "lqd.parameter.loop.attenuation": {
                        "downstream": "15.0",
                        "unit": "dB",
                        "upstream": "12.0"
                    },
                    "lqd.parameter.rel.capacity.occupation": {
                        "downstream": "52.0",
                        "unit": "%",
                        "upstream": "45.0"
                    }
                },
                "diagnostics": [
                    {
                        "explanation": "DEGRADED_CONTACT-NOK",
                        "probablecause": "xDSL"
                    }
                ]
            }
        ]
    }
}

line-analysis

Request

curl -s -u 'user:pass' https://api.nextpertise.nl/broadband/diagnostics/v1 -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "diagnose",
    "params": {
        "kind": "line_analysis",
        "nid": "2408ZE000100102"
    }
}' | jq .

Reply

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "status": {
            "TransactionDetails": "",
            "ScanDetails": {
                "ProgressId": "97494408982691864",
                "ScanName": "SELT"
            },
            "ScanResponses": [
                {
                    "Answer": "request received, processing asynchronous",
                    "ExitValue": "209",
                    "Detail": ""
                }
            ],
            "ErrorDetails": {
                    "ErrorDescription": "",
                    "ErrorCode": "0"
            }
        },
        "kind": "line_analysis"
    }
}