Address Management

Getting started

Placing a Broadband One order requires a pair of address keys identifying your customer's premises. One from the Openreach and a second from the BT (RoBT) Network Address Database (NAD).

The address management API supports a GET and a POST request. GET is used to search the  database(s) and POST to create a new site address and key:

• Make the GET request to check if suitable address records exist in both databases.  The most effective way is to provide one or more address elements and use the fuzzy matching parameter. The API will then attempt to pair up any returned Openreach and ROBT addresses.
• To place a  Broadband One order ,  it is best to use a gold Openreach address  key. In fact it is mandatory for any orders involving the provision of a new FTTP service. Silver and bronze keys can be used for SoGEA and SoADSL orders.
• If a matching RoBT address and NAD key is not shown for a returned Openreach  address record, use the POST request to create one . One way to do this is to copy the Openreach address information to create a matching RoBT address.
• If the desired Openreach address is qualified as Silver no  address key is returned. To create an Openreach silver address  key,  post the address details to the Openreach NAD database and a silver key will be returned.
• If the desired Openreach address is not shown at all, POST the address details to the Openreach NAD database and a bronze key is returned.

This tutorial shows you how to query both databases for those NAD keys. And, in the absence of a matching RoBT key, how to create one using the POST request.

To see how this API forms part of the wider Broadband One order process, see the diagram below.

 

Postman Collection

Explore the code.

Run in Postman

3-minute video overview

Learn how to make your first call and find matching NAD keys.

Prerequisites

To explore Broadband One APIs in our sandbox environment while working through this tutorial, you'll need to register on this portal and create an app.

You'll get a Consumer Key and Consumer Secret to generate an OAuth 2 bearer token - required for all API requests.

Base paths (sandbox and production) are shown in the address management reference documentation.

GET Address records

GET common/geographicAddressManagement/v1/geographicAddress?postcode=SW12 8NX&streetNr=81&isFuzzyMatch=true&isTechonologyMarkersRequired=true&isSiteClassificationRequired=true

Query parameters

Postcode and street number are used to identify the premises.

Additional parameters are submitted to ensure we select the correct NAD keys:

• isFuzzyMatch matches where possible Openreach and RoBT addresses and shows address keys as matched pairs.
• isTechonologyMarkersRequired shows access technologies associated with each Openreach NAD key. Multiple NAD keys with different technology markers may be assigned to the same premises, - so it's important to select the right one in order to obtain correct information during product offering qualification.

Parameter	Use	Notes
postcode	Required	Full UK postcode, with or without a space.
streetNr	Optional	Can be used to narrow the search if you already know the full address of the property. NB We haven’t included this parameter in the above example
isFuzzyMatch	Recommended	Setting this parameter to 'true' is used to find matching records across both the Openreach and BT (RoBT) databases. The response to this query parameter uses parsing and tokenisation to identify important commonalities and discard ‘false positives’. An identical address but for Rd and Road would be considered a match, for example, but street numbers of 18a and 18 would not. While this query parameter is optional, you should use it for Broadband One orders when the installation and delivery addresses are the same.
isTechonologyMarkersRequired	Recommended	There may be multiple NAD keys associated with a single address. In that scenario, there may be different access technologies (copper or fibre) associated with each key. By using this query parameter you will select the right key which will later be used to identify Broadband One product and bandwidth options. When multiple keys have been assigned to your customer's address, make sure to select that supporting their preferred access technology (copper or fibre). If there's more than one NAD key and you select the one for ADSL when your customer needs FTTP, you won't get fibre options in the Product and network availability API.
isSiteClassificationRequired	Recommended	Premises' registered use and status, shown in each address record of the response as siteClassificationCode and siteClassification values. Where there are multiple address records assigned with a single premises, this query parameter is useful in ensuring the correct instance is selected.

Example  cURL call with Headers and Path

Two header properties are required:

• APIGW-Tracking-Header
• Authorization

curl --location 'https://api-sandbox.wholesale.bt.com/common/geographicAddressManagement/v1/geographicAddress?geographicAddress?postcode=SW12 8NX&streetNr=81&isFuzzyMatch=true&isTechonologyMarkersRequired=true&isSiteClassificationRequired=true' \
--header 'Authorization: Bearer [YOUR_BEARER_TOKEN]' \
--header 'APIGW-Tracking-Header: test-client-address'

Response

With the referenced query parameters, this payload will include Openreach NAD keys and their associated access technology families.

More than one NAD key can be associated with an end user's address - and we'll show how to select the right one.

Part 1: Openreach NAD key and matching ROBT record

To place an order there shouldbe an Openreach Gold NAD key associated with the end user's address (this is mandatory for FTTP orders and optional but desired for SoGEA and SoADSL orders).

And in most cases there will also be a matching ROBT NAD key for this Openreach address.

Here are the properties and values confirming that for an Openreach address:

• This should include at least an Openreach Gold NAD key.  If the NAD key is missing a silver key can be created by POSTin the address fields.
• If there is not a matching ROBT NAD key, we can POST a temporary address record to create one.

So we're looking for:

Property	Value	Mandatory	Notes
id	A15104645377	N	Openreach NAD key.  Gold Openreach addresses will have this id. Silver addresses will not.
addressSource	Openreach	Y	Indication that this address record came from Openreach.  ROBT addresses will show the source as ROBT.
qualifier	Gold	Y	Indicates address is, or has historically been, on the Openreach network or has been added to the records as a result of a survey.  Gold for an Openreach address means there will be an address key (id).  Silver means that the address is known to Openreach but you will need to create an address key for it.
addressMatch	true	N	Confirms whether or not a matching ROBT address record has been found for the Openreach record in this query (and vice versa for ROBT addresses).
matchedId	[12-character alphanumeric string]	N	ROBT NAD key for the ROBT address matching the Openreach address. Or Openreach NAD key for the Openreach address matching the ROBT address.

From the above, the id and district code are typically needed for Openreach addresses along with the matchedId for the matching ROBT address. 

A typical response includes dozens of address records. For simplicity, we're going to look at just one record - and assume it matches the customer's details.

[{      "id": "A15104645377",
		"uprn": "100022674385",
		"parentUPRN": "121053761",
		"addressSource": "Openreach",
		"exchangeGroupCode": "CLPM",
		"districtCode": "LS",
		"qualifier": "Gold",
		"streetNr": "81",
		"streetName": "Nightingale Lane",
		"postcode": "SW12 8NX",
		"city": "London",
		"country": "United Kingdom",
		"@type": "BtGeographicAddress",
		"geographicLocationRefOrValue": {
			"geometry": [{"x": "51.4502756",
					      "y": "-.1570796"}]},
		"geographicSubAddress": [{
				"subBuilding": "Ground Floor",
				"@type": "BtGeographicSubAddress"}],
		"addressMatch": true,
		"matchedId": "R09761447276"},
{		"siteReference": {
			"siteClassificationCode": "RD06",
			"siteClassification": "Self Contained Flat (Includes Maisonette / Apartment)" }}

We can see that this record includes all four values shown in the table above.

Part 2: Associated access technologies

By including the isTechonologyMarkersRequired=true name value pair in your query parameters, each Openreach address record in the response indicates which access technologies are associated with the address record and whether any restrictions exist on ordering services which use those technologies. These associations are indicative of which products are likely to be found when performing a product offering qualification using that particular address key.

technologyName values

• Copper indicates presence of copper access network build as used for SOADSL and SOGEA
• PointToPointFibre is not relevant to Broadband One.
• FTTPBrownfield indicates presence of FTTP broadband overbuild where a pre-existing copper access network exists.
• FTTPGreenfield indicates presence  of "newbuild" PON fibre access network (FTTP).

The Broadband One product offering speeds and technologies available for any given the premises can be found using the Openreach address key with the product offering qualification API.

In locations served by "Fibre Priority" exchanges the Copper could be restricted to specific situations where the available FTTP broadband would not be suitable. In that case the technology restriction value for copper will be set to 'R'. This means where SoGEA/SoADSL and FTTP are available FTTP should be ordered.

["listOfTechnology": {"technology": [
					{	"technologyName": "Copper",
						"technologyValue": "Y"},
					{	"technologyName": "PointToPointFibre",
						"technologyValue": "N"},
					{	"technologyName": "FTTPBrownfield",
						"technologyValue": "Y"},
					{	"technologyName": "FTTPGreenfield",
						"technologyValue": "N"}	]},

"listOfTechnologyRestriction": {"technologyRestriction": [
					{	"technologyRestrictionName": "Copper",
						"technologyRestrictionValue": "U"},
					{	"technologyRestrictionName": "PointToPointFibre",
						"technologyRestrictionValue": "U"},
					{	"technologyRestrictionName": "FTTPBrownfield",
						"technologyRestrictionValue": "U"},
					{	"technologyRestrictionName": "FTTPGreenfield",
						"technologyRestrictionValue": "U"}]}

Why include isTechonologyMarkersRequired as a query parameter?

Several NAD keys may be assigned to the same address, and associated with different access technologies.

Without this parameter, the wrong NAD key (where there are multiple instances associated with an address) may be selected for the Broadband One product offering you are interested in.

Having identified NAD keys with the required access technologies, this step in the order process is complete.

Part 3: Non Served Premises & Non Standard Lines

Some locations have Openreach address entries which suggest that location is unusual in how Openreach would install a copper line for the likes of SoADSL or SoGEA.

Such premises are listed with a additionalAddressAttribute of type Location with one or more values from the following 

attributeValue	Meaning
Hot site	The location is in the proximity of a high voltage electrical installation where there is the possibility of a localised higher than zero earth potential. Lines in these locations need to be fitted with a line isolation unit to protect the network and equipment from possible damage. Hot site installs for SoGEA and SoADSL may  require appointments to install line isolation units. if suitable units are not already installed.
Temporary	Temporary structures are locations such as caravans or portacabins. Lines in such locations are often installed for shorter durations and line plant must be recovered when the service is ceased in order to protect the network from damage.
Uninhabitable	"Uninhabitable" premises are locations requiring service to support remote access, telemetry and other such services for street furniture and other structures like traffic lights and signals.

 Below is an example of a premises which is designated as a hot site by Openreach.

{
	"id": "A15105992231",
	"parentUPRN": "200000970353",
	"addressSource": "Openreach",
	"exchangeGroupCode": "PEN",
	"districtCode": "LV",
	"qualifier": "Gold",
	"streetName": "Widnes Road",
	"postcode": "WA5 2UT",
	"locality": "Cuerdley",
	"city": "Warrington",
	"country": "United Kingdom",
	"@type": "BtGeographicAddress",
	"geographicLocationRefOrValue": {
		"geometry": [
			{
				"x": "53.3722453",
				"y": "-2.6870578"
			}
		]
	},
	"geographicSubAddress": [
		{
			"buildingName": "Fiddlers Ferry Power Station",
			"subBuilding": "Gnd-Cam-Com Cab Shelf 2a",
			"@type": "BtGeographicSubAddress"
		}
	],
	"listOfAdditionalAddressAttributes": {
		"additionalAddressAttribute": [
			{
				"attributeType": "Location",
				"listOfAttributeValues": {
					"attributeValue": [
						"Hot site"
					]
				}
			}
		]
	}
}

 

If you've got this far, and read the introduction, you may be wondering - what happens if a matching ROBT NAD key wasn't available in the response or if the required Openreach address is not present or is a silver address?

POST Create address records

If a matching ROBT NAD key is not available, the selected Openreach Gold NAD key address record will include the following key/value pair:

		"addressMatch": false,

If this happens, you’ll need to submit an address record to create one.

Also if the required Openreach address is missing an id field (Silver address) or is missing altogether (Bronze address) you can create an address and key in the Openreach database using the same API with a different target database.

In the limit where there address is not present in either database you may need to create and Openreach AND ROBT address record.

Remember. Non Gold Openreach address keys will not work for FTTP orders.

Request Method & URI

POST common/geographicAddressManagement/v1/geographicAddress

Request Entity-Body

The address record must include the customer’s full address.

{	"streetNr": "97a",
	"streetName": "Nightingale Lane",
	"postcode": "SW12 8NX",
	"locality": "Balham",
	"city": "London",
	"country": "United Kingdom",
	"county": "London",
	"postalOrganisation": "Cavendish IT Solutions",
	"@type": "BtGeographicAddress",
	"geographicSubAddress": [{
			"buildingName": "The Nightingale",
			"subBuilding": "First Floor",
			"@type": "BtGeographicSubAddress"}]}

 Mandatory properties of this payload are:

• streetNr or buildingName
• postcode
• city
• country

Example  cURL call with Headers and Path

These headers are required:

• Authorization
• APIGW-Tracking-Header
• Content-Type
• target (for Broadband One orders, the value is Enterprise-ROBT for Openreach addresses the target is Openreach)

curl --location 'https://api-sandbox.wholesale.bt.com/common/geographicAddressManagement/v1/geographicAddress' \
--header 'Authorization: Bearer [YOUR BEARER TOKEN]' \
--header 'APIGW-Tracking-Header: 96bb97fa-b941-46bb-8c4e-86c616c28a13' \
--header 'Content-Type: application/json' \
--header 'target: Enterprise-ROBT' \

Response

The 201 Created response includes the ROBT NAD key (as shown below). This value must be included with the Openreach Gold NAD key (id) and district code (districtCode) values when placing the order.

{    "id": "X05000192647"}

Broadband One tutorial series

• Appointment management
• Product and network availability
• Order management and progress updates

Additional support

• Broadband One Product Handbook (BT Wholesale login required)
• Reference documentation
• Product catalogue
• Knowledge centre