Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 1 of 14
Duct and Pole Access Web Service R3450 Version 1.0
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 2 of 14
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.
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 3 of 14
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
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 4 of 14
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.
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 5 of 14
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.
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 6 of 14
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>
<!--Optional:-->
<AREA_SEARCH>384378,395169,385378,396169</AREA_SEARCH>
<!--Optional:-->
<GRID_REF></GRID_REF>
<!--Optional:-->
<GRID_TYPE>BNG</GRID_TYPE>
<!--Optional:-->
<LAT_LONG></LAT_LONG>
<!--Optional:-->
<NAD_KEY></NAD_KEY>
<!--Optional:-->
<POST_CODE></POST_CODE>
<!--Optional:-->
<UPRN></UPRN>
</arg0>
</soap:getSearchResult>
</soapenv:Body>
</soapenv:Envelope>
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 7 of 14
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”
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 8 of 14
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”.
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 9 of 14
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>
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 10 of 14
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
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 11 of 14
RESPONSE_MESSAGE string 200 N Textual response description
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 12 of 14
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.
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 13 of 14
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.
Duct and Pole Access Web Service Documentation for R3450
Version 1.0 Issued by Openreach © British Telecommunications plc 2017 Page 14 of 14
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