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
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
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. |
POST GetAccess token PROD Post start S3 Put Job S3 GET Job status s3 GET Job Result S3