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
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
POST /startJobS3
to retrieve a signed URL for Amazon S3 bucket. Send this URL using the following endpoint.PUT /s3url_uploads/{jsonFileNameAndExtension}
to upload the job.GET /jobStatus/{jobId}
to retrieve the status of the job.GET / jobResultS3/{jobId}
to retrieve a signed URL for the Amazon Simple Storage Service (Amazon S3) bucket. Send this URL using the following endpoint.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. |