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.

Headers and cURL

We've used these headers:

• 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 must be an Openreach Gold NAD key associated with the end user's address.

And in most cases there will also be a matching ROBT NAD key.

Here are the properties and values confirming that:

• This must include at least an Openreach Gold NAD key.
• 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	Y	Openreach NAD key.
addressSource	Openreach	Y	Database. Can also be ROBT.
qualifier	Gold	Y	Indicated address is, or has historically been, on the Openreach network. Gold Openreach NAD key required to place a Broadband One order via API
addressMatch	true	N	Confirms whether or not there's a known matching ROBT address record.
matchedId	[12-character alphanumeric string]	N	ROBT NAD key.

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 address record in the response includes values indicating access technologies are associated with the address record. 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 any/all of ADSL, FTTC, and SOGEA
• PointToPointFibre is not relevant to Broadband One.
• FTTPBrownfield indicates presence of fibre broadband overbuild where a pre-existing copper access network exists.
• FTTPGreenfield indicates presence  of "newbuild" PON fibre access network (FTTP).

The exact list of Broadband One products speeds and technologies for the premises address is given in the product offering qualification API.

["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.

Data to be stored

There are three values required from this API response:

Property	Value (example)
id	A15104645377
districtCode	LS
matchedId	R09761447276

• id and districtCode values are required to check product availability at your end user's address.
• All values are required when placing the order.

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 may  require appointments to install line isolation units. SoADSL orders require standard or premium site visit appointments SoGEA orders require advanced site visit appointments.
Temporary	Temporary structures are locations such as caravans or portacabins. Lines in such locations are often installed for shorter durations and line plant need to 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?

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.

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:

• postcode
• city
• country

Headers and cURL

We've used these headers:

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

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": "S14084134555"}

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