Introduction

The High-Level Design FTTx API supports Fiber to the Home (FTTH) engineering jobs. It allows you to calculate the required work and costs 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. The 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

https://api-prd.kpn.com/network/kpn/ftth-engineering

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 customer's 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

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 the page 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.

Run the endpoints in this order

1. POST /startJobS3 to retrieve a signed URL for Amazon S3 bucket. Send this URL using the following endpoint.
2. PUT /s3url_uploads/{jsonFileNameAndExtension} to upload the job.
3. GET /jobStatus/{jobId} to retrieve the status of the job.
4. GET / jobResultS3/{jobId} to retrieve a signed URL for the Amazon Simple Storage Service (Amazon S3) bucket. Send this URL using the following endpoint.
5. GET /Output/{jsonFileNameAndExtension} to retrieve the results of the engineering job.

How to...

Start a job S3

POST /startJobS3

This endpoint submits a new engineering job identifier. The response is a signed URL for the Amazon Simple Storage Service (Amazon S3) bucket.

You need to upload the input data for the engineering job to the received signed URL location. See 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/{jsonFileNameAndExtension}

This endpoints uploads the following:

• The signed URL with the data of the new engineering job for calculation.
• A JSON body of an area for engineering.

You'll find the description of the path parameters and JSON body parameters on SwaggerHub.

When the input has been submitted, this is detected and the calculation starts.

Request

^^JSON body example^^
{
  "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": "string",
  "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\""
    }
  ]
}

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}

This endpoint retrieves the job status.

The calculation of the high-level design results can take up to one or more hours, depending on the size of the submitted area.

With this API request, you can check whether the calculation job has finished or not. It returns the current status of the job identified by jobId.

There is a rate limit of 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 /jobResultS3/{jobid}

This endpoint returns a signed URL from where the results of an engineering job can be retrieved.

When an engineering job is finished you can call this endpoint to retrieve a signed URL for the Amazon Simple Storage Service (Amazon S3) bucket where the results are stored.

Request

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

Response

The expected response is a signed URL for the Amazon Simple Storage Service (Amazon S3) bucket. This signed URL is then to be used to retrieve the engineering job results. See [Retrieve job data](#retrieve-job-data.

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

Retrieve job data

This endpoint returns the Amazon URL to retrieve the calculation results of the engineering job.

You need to send the signed URL from the Retrieve job result request in the path of the request.

GET /Output/{jsonFileNameAndExtension}

You'll find the description of the path parameters and JSON response on SwaggerHub.

^^Job data - excerpt^^
{
   "jobId":"e541a3d6-85c9-4150-9925-f97a43459c94",
   "cable7x14Costs":0.0,
   "cable2x14Costs":0.0,
   "cableDacCosts":0.0,
   "hasCosts":0.0,
   "dpCosts":0.0,
   "cable96vCosts":0.0,
   "bisCosts":0.0,
   "floorTiles":0.0,
   "klinkers":0.0,
   "pavement":0.0,
   "green":0.0,
   "asphalt":0.0,
   "treeDrilling":0.0,
   "sand":0.0,
   "peat":0.0,
   "clay":0.0,
   "loss":0.0,
   "projectSpecificCosts":0.0,
   "feesAndDegeneration":0.0,
   "backhaulCost":0.0,
   "contractor":"string",
   "depthPosition":"string",
   "miniPopCosts":0.0,
   "cityPopCosts":0.0,
   "inhouseP2pPopCosts":0.0,
   "areaPopCosts":0.0,
   "oapCosts":0.0,
   "inhousePonPopCosts":0.0,
   "areaPonPopCosts":0.0,
   "maxDpConnections":0.0,
   "networkType":"string",
   "pveVersion":"string",
   "popType":"string",
   "popLocation":{
      "x":96304.87959372203,
      "y":430059.76687507174
   },
   "addresses":[
      {
         "zipcode":"2991CG",
         "street":"Gebroken Meeldijk",
         "housenumber":161,
         "extension":"",
         "x":97200.5858053118,
         "y":429529.88896409835,
         "city":"Barendrecht",
         "bagGeometryIdentificatie":"0489100000194573",
         "usagegoals":[
            "WOONFUNCTIE"
         ]
      },
      {
         "zipcode":"2991DA",
         "street":"Aak",
         "housenumber":56,
         "extension":"",
         "x":97276.06761359164,
         "y":428911.09371787886,
         "city":"Barendrecht",
         "bagGeometryIdentificatie":"0489100000211991",
         "usagegoals":[
            "WOONFUNCTIE"
         ]
      },
      {
         "zipcode":"2991AB",
         "street":"Lekstraat",
         "housenumber":35,
         "extension":"",
         "x":96482.91574713835,
         "y":430209.09043137403,
         "city":"Barendrecht",
         "bagGeometryIdentificatie":"0489100000195651",
         "usagegoals":[
            "WOONFUNCTIE"
         ]
      },
      {
         "zipcode":"2991WS",
         "street":"Hooimeijerlaan",
         "housenumber":18,
         "extension":"",
         "x":96491.75574329619,
         "y":428780.2680244714,
         "city":"Barendrecht"
      }

Return codes

HTTP response headers

The following tables display the standard response headers that are returned with each API response: