Address Management

Getting started

Placing a Broadband One order requires two 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 using the fuzzy matching parameter.
  • To place a  Broadband One order , the GET request must return an Openreach address with a 'Gold' NAD key.
  • If there isn't a matching RoBT address and NAD key, use the POST request to create one. One way to do this is to use the Openreach address information to create a matching RoBT address.

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, click the diagram below.

Identifying end user address as NAD keys from Openreach and ROBT databases

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.

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

Additional support

Back to top