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

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.

FTTx

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

Workflow diagram


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

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.


HTTP response headers

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

Standard response field name Description
sunset This field will be populated with the deprecation details. By default the value is n/a.
api-version Indicates the API version you have used.
quota-interval Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-limit Number of API calls an user can make within a given time period.
If this limit is exceeded, the user will be throttled and API requests will fail.
quota-reset-UTC All quota times are set to the Coordinated Universal Time (UTC) time zone.
quota-time-unit Used to specify the unit of time applicable to the quota.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-used Number of API calls made within the quota.
strict-transport-security The HTTP Strict-Transport-Security (HSTS) response header lets a website tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
Access control field name Description
access-control-allow-credentials Tells browsers whether to expose the response to frontend JavaScript when the request's credentials mode (Request.credentials) is include.
When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript if the Access-Control-Allow-Credentials value is true. Boolean.
access-control-allow-origin Indicates whether the response can be shared with requesting code from the given origin.
access-control-allow-headers Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.
access-control-max-age Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.
access-control-allow-methods Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.
For example: GET, PUT, POST, DELETE.
content-length The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient.
content-type The Content-Type entity header the client what the content type of the returned content actually is.

Mopinion feedback