KPN High-Level Design FTTx API

Introduction

The High-Level Design FTTx API supports Fiber to the Home (FTTH) engineering jobs. It allows you to calculate the required work and cost for Fiber rollout in a provided region.

The only input you need for this API is the addresses of an area that you want to design. This API makes use of Open Street Maps to determine possible trenches for your Fiber design. The output is in JSON format and contains all the information about cable lengths, digging lengths and lists of used devices and households connected.

API specification

Test the API on SwaggerHub

Base URL

``

Conceptual model

Definitions

Amazon S3

Amazon Simple Storage Service. Provides object storage through a web service interface.

FTTx

FTTx is the abbreviation of 'Fiber to the x', which is a general term for various fiber-optic communication networks, where x represents the destination of the fiber-optic line, for example 'Fiber to the Home' (FTTH).

Distribution Point (DP)

The Distribution Point is the junction box closest to the customers premises. For example a maximum of 48 houses can be connected by a 96v fiber optic cable. The fibers in this cable are each individually connected to the so-called FTUs (Fiber Termination Unit) in the houses.

Point of Presence (PoP)

A Point of Presence (PoP) in the context of FTTx is a central office location where fiber-optic access lines are connected to the KPN network. The other end of these fiber-optic access lines coming from the PoP locations are connected to the Distribution Points.

Pre-signed URL

A pre-signed URL gives you access to the object identified in the URL of Amazon S3 buckets. This API makes use of pre-signed urls to submit input data and retrieve calculation results. An S3 bucket is better suited for these, potentially large, data sets.

API workflow

Prerequirements

WIP [anything important: customer needs to be ...]

Features

Retrieves engineering details for rolling out fiber in the streets.

The High-Level Design FTTx API uses multiple algorithms to create the design. First, it needs a clustering algorithm to decide which household connects to which active device, this is called a distribution point. Secondly, the API uses routing algorithms to connect the households to the distribution points, splitter cabinets and to the POP (Point of Presence). Finally, a calculation is used to determine the total amount of cables and digging in the area.

Getting started

Make sure you've read What's in it for you for more info on how to register and start testing APIs.

Authentication

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

• Authenticate to an API using cURL.
• Authenticate to an API on Swaggerhub.
• Import Open API Specifications (OAS), also called Swagger files into Postman.

How to...

Start a job S3

POST /startJobS3

Submits a new engineering job identifier. The response is a signed URL for the Amazon Simple Storage Service (Amazon S3) bucket. The input data for the engineering job needs to be uploaded to the received signed URL location, see section Upload data.

Request

Header parameter	Type	Description
jsonFileName	string	The jobId of the S3 job. Creates an empty JSON file on Amazon S3 where job data is stored. For example KPN_FTTx_job_01 will result in: ...s3.amazonaws.com/s3url_uploads/KPN_FTTx_job_01.json?...

Response

The expected response returns a signed URL to the Amazon Simple Storage Service (Amazon S3).

^^Request response^^
{
  "signedUrl": "string"
}

Upload data

PUT /s3url

Uploads the data of the new engineering job for calculation. In the request body you need to specify an area for engineering. When the input has been submitted, this is detected and the calculation will start.

Request

^^Request body^^
{
  "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "cable7x14Costs": 0,
  "cable2x14Costs": 0,
  "cableDacCosts": 0,
  "hasCosts": 0,
  "dpCosts": 0,
  "cable96vCosts": 0,
  "bisCosts": 0,
  "miniPopCosts": 0,
  "cityPopCosts": 0,
  "floorTiles": 0,
  "klinkers": 0,
  "pavement": 0,
  "green": 0,
  "asphalt": 0,
  "treeDrilling": 0,
  "sand": 0,
  "peat": 0,
  "clay": 0,
  "loss": 0,
  "projectSpecificCosts": 0,
  "feesAndDegeneration": 0,
  "backhaulCost": 0,
  "contractor": "string",
  "depthPosition": "string",
  "areaPopCosts": 0,
  "maxDpConnections": 0,
  "networkType": "P2P",
  "popLocation": {
    "x": 0,
    "y": 0
  },
  "addresses": [
    {
      "zipcode": "string",
      "street": "string",
      "housenumber": 0,
      "extension": "string",
      "x": 0,
      "y": 0,
      "city": "string",
      "bagGeometryIdentificatie": "string",
      "usagegoals": "bijvoorbeeld \"woonfunctie\" of \"logiesfunctie\""
    }
  ]
}

Parameter	Type	Description
jobId	string($uuid)	Provide an unique UUID for this job. jsonfilename can be any file name
popLocation	array	Location of a point on a two-dimensional plane.
x	number($double)	x coordinates. National triangle coordinates (RD coordinates) in meters.
y	number($double)	y coordinates. National triangle coordinates (RD coordinates) in meters.
address	array	The addresses to include in the engineering process.
zipcode	string	The postal code.
street	string	The name of the street.
housenumber	integer	The number of the house.
extension	string	The extension of the house number, for example: a-c
x	number($double)	x coordinates.
y	number($double)	y coordinates.
city	string	The name of the city or town.
bagGeometryIdentificatie	string	Can be a Pand (non-residential/non-office building) or an addressable object (Pand or Ligplaats) with an Addresses and Buildings key register (BAG) id. It represents a contour.
usagegoals	string	For example: woonfunctie or logiesfunctie.

Response

The expected response is 200. The response code 400 signifies that a job with that jobId already exists.

Retrieve job status

GET ​/jobStatus​/{jobId} Retrieve the job status

The calculation of the high-level design results, can take some time, up to one or more hours, depending on the size of the submitted area. With this API call you can check whether the calculation job has finished or not. It returns the current status of the job identified by jobId. Rate limit - 1 call per minute per user.

Request

Header parameter	Type	Description
jobId	string($uuid)	The jobId of the job that was provided when calling startJob.

Response

The expected response is 200 with the status of the job request.

^^Request response^^
{
  "status": "string"
}

Retrieve job result

GET ​/jobResult​/{jobId}

REPLACED BY jobResultS3

ADDITIONAL ENDPOINT GET /s3Url

Returns the result of an engineering job. This method is called by the HLD front-end when a job is finished, so the results can be stored in the HLD front-end database.

Request

Header parameter	Type	Description
jobId	string($uuid)	The jobId of the job that was provided when calling startJob.

Response

The expected response is 200. The results of the engineering job in a compressed string format.

^^Request response^^
{
  "status": "eJztWsFuHDcS/RVD55hgFYsscm+2c0iAABskC+xhEQzG0"
}

Return codes

POST GetAccess token PROD Post start S3 Put Job S3 GET Job status s3 GET Job Result S3