duct and pole access web service r3450 - openreach · 2017-04-12 · duct and pole access web...

Duct and Pole Access Web Service Documentation for R3450

Version 1.0 Issued by Openreach © British Telecommunications plc 2017 of 14

Duct and Pole Access Web Service R3450 Version 1.0



Legal notice The contents contained in this document must not be forwarded or republished without the written consent of Openreach.

Copyright © British Telecommunications plc, 2017. All rights reserved. BT maintains that all reasonable care and skill has been used in the compilation of this publication. However, BT shall not be under any liability for loss or damage (including consequential loss) whatsoever or howsoever arising as a result of the use of this publication by the reader, his servants, agents or any third party. All third-party trademarks are hereby acknowledged.

Document history

Revision Author Date Notes

Version 1.0 Simon Foley 11/04/2017 First issue

Please note that changes from the previously published version of this document will be shown in highlighted text to enable easy identification. Changes to the previously published baseline for this service are highlighted in blue.



CONTENTS

1 Introduction .......................................................................................................................... 4

2 System overview .................................................................................................................. 4

3 Access to Openreach Web Services ................................................................................. 5

4 Request XML ........................................................................................................................ 6

5 Response XML ..................................................................................................................... 9

6 Error Messages ..................................................................................................................13



1 Introduction

The Duct and Pole Access Web Service provides Communications Providers with the ability to search for a location and view the Openreach duct and structures in that location. This is provided to Communications Providers on an ‘as is’ indicative basis to enable Communications Providers to understand what duct and poles can be used for their PIA build.

For example, you will be able to see Openreach duct routes and structures such as joint chambers and poles in the locations you intend to deploy your network. The information supplied is a view of the information we hold in our systems for our duct and pole network but it cannot reflect circumstances which may only be identified during planning and survey, for example recently silted duct, capacity restrictions, or wayleave requirements.

2 System overview

The Webs Service allows a CP to build their own solution for accessing the duct and structures information that Openreach holds. The CP system will pass a request to the Vordel Gateway which will in turn query and return results from the Geospatial Server. The response back to the CP will contain a block of standard GML containing the same features that are displayed on the Portal based map Duct and Pole Access tool. These can then be integrated into the CPs mapping tool of choice.



3 Access to Openreach Web Services

Please note that we will need to configure your secure access to the B2B Gateway and Web Services gateway. If you’re not PIA established or are set up and would like to access the Map Tool using this method, please email the Customer Establishment Team (CET) at: [email protected] You’ll need to provide the following information; 1. Full company registered name 2. Main establishment contact details i.e. name/ email address and telephone number The CET and your Customer Engagement Manager (CEM) will liaise with you throughout establishment and to completion of your set-up to ensure that commercial/contractual, information and activities required for live connectivity into Openreach has been fulfilled by both parties. As part of the set-up process you will be given access to the Customer Verification Facility (CVF), test platform. – You’ll need to carry out testing Further information on the Web Services framework please refer to the Openreach Web Services User Guide which can be found on the Openreach website. http://www.openreach.co.uk/orpg/home/helpandsupport/how-toguides/howtoguides.do This document also contains the WSDL and sample request/response XML’s for the service which is documented as the Passive Infrastructure Access Service.

http://www.openreach.co.uk/orpg/home/helpandsupport/how-toguides/howtoguides.do

4 Request XML

To query the Web Service the following XML should be submitted containing a valid DUNS ID and a valid search criteria. See example below. <soapenv:Envelope

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:soap="http://soapservice.piaquerymap.bt.com/">

<soapenv:Header/>

<soapenv:Body>

<soap:getSearchResult>

<arg0>

<DUNS_ID>974645345</DUNS_ID>



<AREA_SEARCH>384378,395169,385378,396169</AREA_SEARCH>



<GRID_REF></GRID_REF>



<GRID_TYPE>BNG</GRID_TYPE>



<LAT_LONG></LAT_LONG>



<NAD_KEY></NAD_KEY>



<POST_CODE></POST_CODE>



<UPRN></UPRN>

</arg0>

</soap:getSearchResult>

</soapenv:Body>

</soapenv:Envelope>



Request XML attributes and values

Request

Parameter

Name

Data Type Max Length Nullable? List of values / format

DUNS_ID string 60 N Valid Duns ID

AREA_SEARCH string NA Y

Four one metre precision x and y

grid coordinates, as integers or

decimals, comma-separated.

These represent the corners of a

polygon to define the bounding box

for the search. (minimum X,

minimum Y, maximum X,

maximum Y)

The derived size of the bounding

box generated by the coordinates

should not exceed 1km x 1km.

If the returned search results have

a DUCT count of greater than 2000

then the SEARCH_AREA

coordinates will be adjusted

accordingly

For example

384378,395169,385378,396169

GRID_REF string 50 Y

Pair of one metre precision x and y

grid coordinates, as integers or

decimals, comma-separated. For

example: 350000,350000

Postcode string 10 Y

Standard UK full unit postcode

string. For example IP4 1BF or

IP41BF

NAD_KEY string 12 Y Standard NAD key. For example

A00000003406

UPRN string 20 Y

Standard UK unique property

reference number (UPRN) from the

National Address Gazetteer. For

example 100090892761

LAT_LONG string 50 Y

Pair of latitude/longitude values, as

decimal degrees, comma-

separated. For example:

52.000000,1.000000, or

52.000000, -1.000000

GRID_TYPE string 5 Y “BNG”, “IG” or “NA”



Notes 1. If a NAD key or UPRN is used, these will be converted into a pair of coordinates on the

BT side by a query on the Openreach NAD system, which are then passed to GeoHUB to select the features.

2. If a postcode is used, this is queried against the latest copy of Ordnance Survey Code-Point data in GeoHUB to identify the coordinates. If no match is found in the GeoHUB table an error code is returned. Code-Point is updated approximately every 3 months in GeoHUB.

3. Postcodes may be with or without one space, but must be upper case.

4. LAT_LONG inputs are in the numerical form of decimal degrees. Negative numbers are required for longitude references to the west of the Greenwich Meridian.

5. The main purpose of the GRID_TYPE parameter is to support the input of Irish Grid coordinates. The values in GRID_REF will be interpreted as Irish Grid if GRID_TYPE is set to “IG”.

6. All plant data in GeoHUB is stored natively in British National Grid geometry. If WGS84 or Irish Grid coordinates are used these will be converted to British National Grid before selecting the features, so there will be some accuracy loss.

7. Search should be one of types: AREA_SEARCH, GRID_REF, Postcode, NAD_KEY, UPRN, LAT_LONG. If anything other than GRID_REF or AREA_SEARCH, GRID_TYPE should be “NA”.



5 Response XML

In response to a valid CP query the following XML will be returned. See example below. <?xml version='1.0' encoding='UTF-8'?>

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Body>

<ns0:getSearchResultResponse

xmlns:ns0="http://soapservice.piaquerymap.bt.com/">

<return>

<ALLOWED_RADIUS>500</ALLOWED_RADIUS>

<DATE_TIME_STAMP>2017-03-21_13:12:27</DATE_TIME_STAMP>

<GML_TAG>

<![CDATA[MAP DATA HERE]]>

</GML_TAG>

<GRID_REFERENCE>384878.0,395669.0</GRID_REFERENCE>

<INPUT_BOUNDINGBOX>384378,395169,385378,396169</INPUT_BOUNDINGBOX>

<REFACTORED_BOUNDINGBOX>384553.2150987692,395344.2150987692,385202.784

9012308,395993.7849012308</REFACTORED_BOUNDINGBOX>

<RESPONSE_CODE>203</RESPONSE_CODE>

<RESPONSE_MESSAGE>Success</RESPONSE_MESSAGE>

<SCALE_MAPPING>1:2834</SCALE_MAPPING>

<UNIQUE_MAP_REFERENCE>15776_2017-03-

21_13:12:27</UNIQUE_MAP_REFERENCE>

<ZOOM_LEVEL>12</ZOOM_LEVEL>

</return>

</ns0:getSearchResultResponse>

</S:Body>

</S:Envelope>



Response XML attributes and values

Response Parameter Name Data Type Max Length Nullable? List of values / format

GRID_REFERENCE string 50 N

The grid reference used for the

search as comma-separated

x,y pair in British National Grid

INPUT_BOUNDINGBOX string NA Y

The co-ordinates entered for

the SEARCH_AREA request.

For example

384378,395169,385378,396169

REFACTORED_BOUNDINGBOX string NA Y

If the returned search results

have a DUCT count of greater

than 2000 then the

SEARCH_AREA coordinates

will be adjusted and returned in

this attribute.

For example

384553.2150987692,

395344.2150987692,

385202.7849012308,

395993.7849012308

UNIQUE_MAP_REFERENCE string 20 N

Unique identifier for the

request, for example:

921_2015-03-08_00:42:05

SCALE_MAPPING string 20 N

Equivalent scale for WMS

response into map GUI – not

relevant to CP consumers of

the GML feed

ZOOM_LEVEL int 2 N

Equivalent zoom level for WMS

response into map GUI – not

relevant to CP consumers of

the GML feed

ALLOWED_RADIUS int 4 N 500 – the value in metres of the

radius of the spatial query

GML_TAG string 10000 N

GML v1 output in the CDATA

block representing the

Openreach plant features within

the spatial query extent

DATE_TIME_STAMP string 20 N For example: 2015-03-

08_00:42:05

RESPONSE_CODE int 4 N Numerical response code value



RESPONSE_MESSAGE string 200 N Textual response description



Notes 1. The features returned in the GML packet are the same as displayed on the Duct and Pole

Access map GUI: STRUCTURE: JOINT CHAMBER, POLE, CABINET, ECHCANGE, BURIED. DUCT: CAPACITY INDICATOR. Geometry is in British National Grid for all cases.

2. The maximum payload for the Web Service (XML gateway) is set to a pre-set limit up to a maximum of 15Mb; with a single configurable file limit within the 15Mb envelope currently set to 2Mb. The search radius will be reduced on searches that return results greater than the pre-set limit. CPs will need to run another search from a different starting position to view the wider area.



6 Error Messages

The following error messages will be returned to CPs in the event of a failed request:

Error Description GeoHUB Response Code

GeoHUB Response Message

GeoHUB does not have the postcode in the code point table

403 Unable to retrieve the data for the requested parameters.

Request timed out from Vordel to GeoHUB..

404 Time Out

Invalid NAD key in NAD response to GeoHUB

405 Unable to retrieve the data from NAD for the requested parameters.

NAD response timed out between NAD and GeoHUB

406 Request Time Out from NAD

Connectivity issue between NAD and GeoHUB

406 Request Time Out from NAD

UPRN, Lat-long failure 405 Unable to retrieve the data from NAD for the requested parameters.

407 Unable to convert the Lat, Long to corresponding Grid Co-ordinates.

All the Error Codes applicable for NAD Key will be applicable for UPRN.

408 Out of bound lat, long

Error in conversion from Irish to British Grid ref

409 Unable to convert the Co-ordinates from Irish to British Grid

Database connection error 401 Database connection error

An SQL exception has occurred 402 An SQL exception has occurred

Out of Bound Grid Reference 410 Out of Bound Grid Reference

More than 1 Type of search requested

2025 Size of parameter mismatch :

No Search Parameter found in search request

2026 Search type parameter mismatch :

The derived size of the bounding box generated by the coordinates entered exceed the 1km x 1km limit.

2029 The coordinates entered for the area search are out of bounds

Note: GeoHUB refers to the Geospatial server used to serve the map data. NAD refers to the National Address Database.



An example of a failed response is shown below: <?xml version='1.0' encoding='UTF-8'?>

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Body>

<ns0:getSearchResultResponse

xmlns:ns0="http://soapservice.piaquerymap.bt.com/">

<return>

<ALLOWED_RADIUS>500</ALLOWED_RADIUS>

<DATE_TIME_STAMP>2017-02-06_07:31:29</DATE_TIME_STAMP>

<GML_TAG>Coordinate are null</GML_TAG>

<RESPONSE_CODE>405</RESPONSE_CODE>

<RESPONSE_MESSAGE>Unable to retrieve the data from NAD for the

requested parameters</RESPONSE_MESSAGE>

<SCALE_MAPPING>1:2834</SCALE_MAPPING>

<UNIQUE_MAP_REFERENCE>7322_2017-02-

06_07:31:29</UNIQUE_MAP_REFERENCE>

<ZOOM_LEVEL>12</ZOOM_LEVEL>

</return>

</ns0:getSearchResultResponse>

</S:Body>

</S:Envelope>

Two HTTP status messages have also been configured and returned in the following scenarios.

1. If it is not possible to reduce the size of the returned file to less than the pre-set limit by reducing the search radius then the following message will be returned. HTTP Status Code = 500 The size of the response for the requested search is too large for the Web Service. Please run this request on the Portal based Duct and Pole Access Tool.

2. Each instance of Openreach’s Web Service Gateway can support 5 requests per minute. This allows for a maximum of 20 requests per minute. This maximum number of requests may be reduced depending on factors such as server load, but will not drop below 5. HTTP Status Code = 503 The server is currently processing the maximum number of allowed requests. Please try again after a few minutes

duct and pole access web service r3450 - openreach · 2017-04-12 · duct and pole access web...

Documents