Broadband Availability API

Introduction

thinkbroadband has been tracking broadband coverage across the UK since 2012 and to help the public when searching for broadband in our package search we have been developed our own API to filter the packages offered to people based on their postcode.

Other data services are described on our UK Broadband Data page.

The broadband availability API is available on a commercial basis to sites that offer broadband availability and related searches and is part of our desire to ensure that the public get accurate and up-to-date information (e.g. are not offered FTTC services when in reality FTTP is available) as available. The API does not control what retail broadband packages are shown to consumers, but provides the information those offering package recommendations can use to determine these.

The RESTful API returns a JSON object describing wholesale services available along with speed estimates where relevant, so that for example, you can decided to only show 40/10 FTTC services, where the user would not benefit from a faster but more expensive 80/20 FTTC package which may technically still be available, because their line is too long to get speeds above 40Mbps.

Key API features

• Restful API / JSON data output
• Designed for server-to-server communication
• Available on a commercial basis; prices on application but dependent on query volume
• One single call provides information about multiple services e.g. Openreach, Virgin Media, Hyperoptic, OFNL, KCom, Gigaclear, etc.
• Highlight availability of G.fast with minimum 100 Mbps speeds
• "Full fibre" (FTTH) provider availability
• Version control such that new fields/providers and methods to call are provided in a structured way
• Intended for single look-ups; for those wanting to visualise UK broadband infrastructure, contact us for details on our joint work with Point-Topic under the ThinkPoint brand for data which can be ingested into mapping/BI systems.

Calling the API

It is only possible to use the API when you have been issued with an authentication token (guid) and your IP addresses have been added to our systems. Once these are in place, you can access it via a simple HTTP GET request.

Example on how to access the API using PHP and curl function:

$html = curl_get_contents('https://api.thinkbroadband.com/inquiry.php?postcode='.$postcode.'&version=2.20&guid=[site_unique_guid]');
$data = json_decode($html);

Typical Response

The full response from a typical call is reproduced here:

{
 "api_version":2.2,
 "postcode":"L1 9DW",
 "latlng":"53.401277000000000,-2.974188000000000",
 "lat":"53.401277000000000",
 "lng":"-2.974188000000000",
 "exchange_code":"LVROY",
 "exchange_name":"ROYAL",
 "exchange_distance":219,
 "exchange_code_near_1":"LVCEN",
 "exchange_name_near_1":"LANCASTER HOUSE",
 "exchange_distance_near_1":1810,
 "exchange_code_near_2":"LVNOR",
 "exchange_name_near_2":"NORTH",
 "exchange_distance_near_2":1919,
 "exchange_code_near_3":"LVANF",
 "exchange_name_near_3":"ANFIELD",
 "exchange_distance_near_3":2609,
 "exchange_code_near_4":"LVSEF",
 "exchange_name_near_4":"SEFTON PARK",
 "exchange_distance_near_4":2806,
 "avail_retail_virginmedia":"NOT_AVAILABLE",
 "avail_infra_virginmedia_cable":"NOT_AVAILABLE",
 "avail_infra_openreach_fttc":"NOT_AVAILABLE",
 "avail_infra_openreach_fttp":"NOT_AVAILABLE",
 "avail_infra_openreach_gfast":"NOT_AVAILABLE",
 "avail_retail_bt_consumer":"AVAILABLE",
 "avail_retail_ee":"AVAILABLE",
 "avail_retail_plusnet":"AVAILABLE",
 "avail_infra_btwholesale_ipstream_max":"AVAILABLE",
 "avail_infra_btwholesale_adsl2plus_wbc":"AVAILABLE",
 "avail_retail_sky":"AVAILABLE",
 "avail_infra_sky_llu_adsl2plus":"AVAILABLE",
 "avail_retail_talktalk":"AVAILABLE",
 "avail_infra_talktalk_llu_adsl2plus":"AVAILABLE",
 "exchange_market":"B",
 "avail_infra_kc_adsl2plus":"NOT_AVAILABLE",
 "avail_infra_kc_fttp":"NOT_AVAILABLE",
 "avail_infra_hyperoptic_fttp":"NOT_AVAILABLE",
 "avail_infra_gigaclear_fttp":"NOT_AVAILABLE",
 "avail_infra_ifnl_fttp":"NOT_AVAILABLE",
 "avail_infra_b4rn_fttp":"NOT_AVAILABLE",
 "avail_infra_airband_wireless":"NOT_AVAILABLE",
 "avail_infra_vodafone_gigafast":"NOT_AVAILABLE",
 "avail_infra_community_fibre":"NOT_AVAILABLE",
 "avail_infra_truespeed":"NOT_AVAILABLE",
 "avail_infra_trooli":"NOT_AVAILABLE",
 "best_download_sub_24":"YES",
 "best_download_sub_10":"NO",
 "best_download_sub_2":"NO",
 "est_adsl2plus_download_postcode":"15 to 24 Mbps",
 "est_fttcp_download_postcode":"over 40 Mbps",
 "est_adsl2plus_download_within500m":"15 to 24 Mbps",
 "est_fttcp_download_within500m":"over 40 Mbps",
 "est_adsl2plus_download_within1000m":"10 to 20 Mbps",
 "est_fttcp_download_within1000m":"20 to 40 Mbps",
 "est_gfast_download_postcode":"UNKNOWN",
 "est_fttp_download_postcode":"UNKNOWN",
 "openreach_postcode_split":"SINGLE",
 "openreach_postcode_split_technology":"SAME",
 "est_raw_adsl2plus_download_postcode":24,
 "est_raw_fttcp_download_postcode":80,
 "est_raw_gfast_download_postcode":-1,
 "fastest":"15 to 24 Mbps",
 "tech":"ADSL2+",
 "openreach_waiter":"UNKNOWN"
}

This tells us that ADSL2+ is available, but no faster services appear to be available. The speed ranges are provided for FTTC services, even though it is not available at this time. This is to help you understand the likely speeds when cabinets serving the location are upgraded to FTTC. You should therefore filter such speed ranges by observing the "avail_infra_openreach_fttc" field.

Understanding and interpreting results

Broadband availability and ensuring you present the most appropriate products to users is more complicated than an an API lookup on postcode. Our aim is to provide you with as much information as possible, so that you can make the best decision for your user base. As such, you may see a DSL-based broadband service deliver a sub-2Mbps service, and wish to recommen satellite services as an option, even if we do not have information on that.

Some key considerations in building your logic are highlighted below.

Split Postcodes

The fields openreach_postcode_split and openreach_postcode_split_technology (available since v 2.1) are designed to help boost confidence in the result or allow a site to add a caution that a postcode-level search may not provide the full picture on availability to a particular premises. The majority of postcodes are served by a single Openreach cabinet (covering around 22 million premises), but some are split across multiple cabinets. We call these 'split postcodes' where some premises will get different ranges of services from others.

'Waiter List'

The openreach_waiter field (from v 2.3) indicates a postcode where we think FTTC based services are subject to capacity limirations (i.e. there is a waiting list). This field is not real-time as availability can change frequently as lines are provisioned and cancelled, so the purpose if to add a cautionary note which you may display, or use when selecting the recommended product based on other options available to the user.

The 'waiting' problem also impacts those looking to migrate between providers, which may seem illogical given an active VDSL2 line is already connected to a port, but it is thought that the equivalence of input rules have led to this scenario to avoid large wholesalers gaining an advantage over switching between two LLU operators.

Example postcodes

These few examples you may wish to consider using for testing and are correct at the time of writing. These are not a full set of permutations but should allow you to test the most common cases and how they should be interpreted.

• SM2 2BJ — A location with G.fast, Virgin Media, FTTC and ADSL2+ available
• SM5 4GD — A newish postcode where only Openreach FTTP is available, so no ADSL/ADSL2+ options
• BT23 4NW — An emerging trend with the Fibre First roll-out, Openreach FTTP and FTTC are both available at good speeds, and Virgin Media cable broadband is also available.
• NE36 0QS — FTTC is available but due to the distance from the cabinet our speed estimate is 17 Mbps versus a range of 12.5 to 23 Mbps.
• CB10 2DF — The postcode is split across two different cabinets, the majority of premises can get FTTC, but we do flag the cabinet as split across multiple postcodes and that not all of them have a FTTC based service.
• CB10 1DY — No FTTC available and is actually an exchange only line, but they do have Virgin Media cable available.
• MK10 8LD — OFNL (previously IFNL) and their full fibre service is available, usually these locations have no services from other operators.
• SW18 1HA — Hyperoptic Fibre to the Building service is available, alongside ADSL2+ services.

The ability to advise users that not all premises will be served by the same Openreach technology is useful as while there are around 22 million premises served by a single cabinet, warning others that when they check on a providers' sites for the full address may result in a different result means expectations have been managed.

The speed estimates for Openreach local loop technologies are based on own model of their network and the single figure estimate is usually towards to the lower end of the range that a full address lookup would provide. This is deliberate to allow for the fact that the estimate is based on the centroid of the postcode.

Frequently Asked Questions

How accurate is the data?

The dataset is dynamic and broadband roll-outs are on-going, so the data changes all the time. Over the years we have refined the accuracy and across the UK we believe the tolerance is +/- 0.1%; back in early 2016 this range was as wide as +/- 1%.

It is importasnt to note that even if a particular technology is available for a postcode, individual providers may have a temporary hold on new orders in an area, or there may be wholesale capacity issues but with waiting lists available to operators, although this may not always be communicated to customers.

We welcome feedback from users where they see issues ordering services that we show as being available and update the database daily based on reports we receive. We investigate any feedback from users, and also flagged by our systems both on the specific postcode, but also wider groups of postcoes which may be subject to similar constraints, so we believe that we are the most 'live' UK broadband availability data set available. In some cases, we feed back into wholesale operators where their data is incorrect as well.

Is the data availability as a 'flat data' file, so we do not have to use the API?

For the purposes of broadband availability searches to drive a comparison engine we do not recommend using a flat data set due to the dynamic nature of the broadband roll-outs which change daily or weekly. We do offer availability information in downloadable formats for appropriate uses through our ThinkPoint data set service. If you are looking to use data to for example target mailshots to customers who have registered with you, we can offer solutions for bulk queries for this purpose; please contact us for more details.

What can we do with the data?

This API is intended for websites which need to check availability for a user considering broadband options on a 'live' basis. We do log lookups for audit and quality control purposes but we do not store any personal data in relation to such lookups as these are proxied through your server at all times and we only communicate with your server. We do not use lookups for any marketing purposes ourselves.

Can a partial set of results be returned?

Since we know that not everyone will want all the fields the data is clustered into different groups and when subscribing to the API the initial setup involves defining which sets of data you want to receive.

The list of data groups and a synopsis of what it provides follows:

• District Information: Type of council the postcode falls within and average speeds seen within the council area. Version 1.2 added regional level speed test results for last quarter.
• Coordinates: Latitude and longitude for the postcode
• Demographics: Number of premises in the postcode (current) and population (2011 Census)
• Exchange Information: Detail of the Openreach exchange postcode is connected to and information on the four other closest exchanges.
• Coverage: Core broadband coverage fields on the technologies available to the postcode
• Estimated Speeds: Estimated speeds for ADSL/ADSL2+ and VDSL2/Gfast available as a preformated text field e.g. 45 to 76 Mbps or a single raw figure to allow for your own formatting. Estimates for the postcode itself and surrounding area are provided. We also include two fields to indicate if a postcode is served by a single or multiple Openreach cabinets, which can be used as a confidence indicator.
• Speed Tests: Analysis from our speed test data on speeds seen in the last 3 months in the postcode and nearby postcodes
• Fastest: To help with the logic on what services to show we can say which technology we think offers the fastest fixed line speeds in a postcode e.g. ADSL, FTTC, cable or FTTP.

The descriptions relate to versions 2.20 of the API, as new data fields are introduced these are only supplied to those who request the appropriate data version i.e. if version 2.30 introduced a new broadband provider those requesting a 2.30 version or higher would see this information.

Is the API available in other formats?

Other formats such as XML can be requested and served in response to the request, but core data set will remain the same. Unusual or custom formats may carry additional development costs on top of ongoing API access charges. 

Field Definitions

Grouped based on their grouping flag, the full list of fields is as follows:

Group	Field	Example and Notes
Always Present	api_version	2.3 floating point value confirming the version of the API call you made
Always Present	postcode	Postcode e.g. L1 9DW
District Info	country	England, Scotland, Wales or Nothern Ireland
District Info	region	East Midlands, East of England, London, North East England, North West England, Northern Ireland, Scotland, South East England, South West England, Wales, West Midlands or Yorkshire and Humber
District Info	district	Text name for the district council or local authority. One council name from a list of 208 possible ones.
District Info	is_london_borough	YES or NO
District Info	is_unitary_authority	YES or NO
District Info	is_metro_district	YES or NO
District Info	district_code	E08000012 i.e. the ONS code that corresponds to the council named in the 'district' field
District Info	mean_council_download_quarter	39.8 (in Mega bits per second to 1 decimal place - quarter is previous full quarter)
District Info	mean_council_upload_quarter	e.g. 6.8
District Info	median_council_download_quarter	e.g. 26.4
District Info	median_council_upload_quarter	e.g. 5.1
District Info	region_quarter	Name of UK region the quarter speed test results refer to.
District Info	mean_region_download_quarter	33.3
District Info	mean_region_upload_quarter	6.5
District Info	median_region_download_quarter	24.1
District Info	median_region_upload_quarter	4.8
District Info	mean_region_latency_quarter	49 (an integer in milliseconds)
District Info	median_region_quality_quarter	0.6 (floating point value used for comparing speed tests)
Coord	latlng	e.g. 53.401277000000000,-2.974188000000000
Coord	lat	e.g. 53.401277000000000
Coord	lng	e.g. -2.974188000000000
Demographics	households	20 (NOTE Field makes no distinction between residential and business premises - this is expected to change in a future version)
Demographics	population	0 (taken from Census 2011 data)
Exchange Info	exchange_code	LVROY (standard code name for Openreach exchange telephone line connects to)
Exchange Info	exchange_name	ROYAL
Exchange Info	exchange_distance	e.g. 219 (integer distance in metres from center of postcode to the exchange building)
Exchange Info	exchange_code_near_1, exchange_code_near_2, exchange_code_near_3, exchange_code_near_4	Code for the next nearest four exchanges
Exchange Info	exchange_name_near_1, exchange_name_near_2, exchange_name_near_3, exchange_name_near_4	Name of next nearest four exchanges
Exchange Info	exchange_latlng	e.g. 53.401074548615924,-2.9767674932372756
Exchange Info	exchange_lat	e.g. 53.401074548615924
Exchange Info	exchange_lng	e.g. -2.9767674932372756
Exchange Info	exchange_lat_near_1, exchange_lat_near_2, exchange_lat_near_3, exchange_lat_near_4	Latitude of next nearest four exchanges, useful for populating any locality map shown to visitors
Exchange Info	exchange_lng_near_1, exchange_lng_near_2, exchange_lng_near_3, exchange_lng_near_4	Longitude
Exchange Info	exchange_market	A or B, based on market grouping assigned to exchange by Ofcom
Coverage	avail_infra_virginmedia_cable	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_openreach_fttc	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_openreach_fttp	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_openreach_gfast	Either AVAILABLE or NOT_AVAILABLE NOTE: Postcodes too far from a live pod will return NOT_AVAILABLE
Coverage	avail_infra_btwholesale_ipstream_max	Either AVAILABLE or NOT_AVAILABLE Some exchanges still don't have the basic ADSL service available
Coverage	avail_infra_btwholesale_adsl2plus_wbc	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_sky_llu_adsl2plus	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_talktalk_llu_adsl2plus	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_kc_adsl2plus	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_kc_fttp	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_hyperoptic_fttp	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_gigaclear_fttp	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_ifnl_fttp	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_b4rn_fttp	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_airband_wireless	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_vodafone_gigafast	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_community_fibre	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_truespeed	Either AVAILABLE or NOT_AVAILABLE
Coverage	avail_infra_trooli	Either AVAILABLE or NOT_AVAILABLE
Coverage with Show Retail	avail_retail_virginmedia	Either AVAILABLE or NOT_AVAILABLE
Coverage with Show Retail	avail_retail_bt_consumer	Either AVAILABLE or NOT_AVAILABLE
Coverage with Show Retail	avail_retail_ee	Either AVAILABLE or NOT_AVAILABLE
Coverage with Show Retail	avail_retail_plusnet	Either AVAILABLE or NOT_AVAILABLE
Coverage with Show Retail	avail_retail_sky	Either AVAILABLE or NOT_AVAILABLE
Coverage with Show Retail	avail_retail_talktalk	Either AVAILABLE or NOT_AVAILABLE
Coverage	best_download_sub_24	YES or NO, if the postcode is believed to only have a sub 24 Mbps service available will return YES. This is possible even when VDSL2 is available due to the line distance drop off.
Coverage	best_download_sub_10	YES or NO, is based on our assessment of the best download speed available. With some voucher schemes available suggesting those or referring to broadband USO pages is worthwhile when a YES is returned.
Coverage	best_download_sub_2	YES or NO, generally those postcodes a long way from the exchange and also their cabinet. Redirecting visitors to an alternative such as 4G or satellite might be worthwhile.
Coverage	openreach_waiter	UNKNOWN, OK or WAITING, reflecting if our tracking of cabinet capacity has the VDSL2 cabinet flagged as at a capacity limit. Do not use this field to hide VDSL2 based services, since capacity is very dynamic but by flagged a cautionary note to visitors you can avoid disappointment when the retailer does its live check as part of the order process.
Fastest	fastest	e.g. 1000 Mbps for those postcodes with Gigabit FTTP available, cable services return 200 Mbps and Openreach FTTP 300 Mbps. On ADSL close to the exchange sample is '6 to 8 Mbps'
Fastest	tech	Unknown, ADSL, ADSL2+, FTTC, FTTP or Cable. Field tells you which is expected to be the fastest fixed line speed, it is possible that ADSL2+ may be faster than FTTC in some limited number of scenarios.
Estimated Speeds	est_adsl2plus_download_postcode	UNKNOWN or formatted string e.g. '18 to 24 Mbps'. Strings may change so dont use the field for less than or more than decisions, for those decisions use the integer values of the est_raw_* fields
Estimated Speeds	est_fttcp_download_postcode	UNKNOWN or formatted string e.g. '45 to 76 Mbps'
Estimated Speeds	est_adsl2plus_download_within500m	As per _postcode field but covers postcodes with 500 metres. Included to give an idea of area performance rather than performance for a specific visitor
Estimated Speeds	est_fttcp_download_within500m	As per _postcode field but covers postcodes with 500 metres. Included to give an idea of area performance rather than performance for a specific visitor
Estimated Speeds	est_adsl2plus_download_within1000m	As per _postcode field but covers postcodes with 500 metres. Included to give an idea of area performance rather than performance for a specific visitor
Estimated Speeds	est_fttcp_download_within1000m	As per _postcode field but covers postcodes with 500 metres. Included to give an idea of area performance rather than performance for a specific visitor
Estimated Speeds	openreach_postcode_split	UNKNOWN, SINGLE or MULTIPLE, reflects whether postcode is served by multiple Openreach cabinets
Estimated Speeds	openreach_postcode_split_technology	UNKNOWN, SAME or DIFFERENT, useful when split field returns MULTIPLE. SAME means that all premises are just ASDL or just FTTC/FTTP based. DIFFERENT means a mixture of ADSL and FTTC/FTTP is present, the answers in all the coverage fields refer to the majority available. So if we say FTTC is not available, but you see a DIFFERENT entry this means a small number of premises may have access to FTTC or FTTP and the opposite if we say FTTC or FTTP is available.
Raw Speed Estimate	est_raw_adsl2plus_download_postcode	An integer estimate of the expected ADSL2+ download speed for the postcode area
Raw Speed Estimate	est_raw_fttcp_download_postcode	An integer estimate of the expected VDSL2 or FTTP download speed for the postcode area. VDSL2 figure is shown even if service is not available, so for presentation to a visitor you need to filter on the coverage fields
Raw Speed Estimate	est_raw_gfast_download_postcode	UNKNOWN or integer estimate for Gfast if service is available

Do you have any example code for using the API?

So that people can get up and running and using the API quickly we have a simple PHP and HTML file available that includes some basic logic to show information about the broadband packages available.

A snippet from the file is attached, but the full file can be downloaded from https://labs.thinkbroadband.com/sample.zip but to make use the file you will require your unique GUID to access the lookup system

function curl_get_contents($url)
{
	$ch = curl_init($url); 
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); 
	curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1); 
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); 
	curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); 
	$data = curl_exec($ch); 
	curl_close($ch); 
	return $data; 
} 

function accessAPI($postcode)
{ 
	$postcode=urlencode($postcode); 
	$html = curl_get_contents('https://api.thinkbroadband.com/inquiry.php?postcode='.$postcode.'&version=2.3&guid=[your unique guid]'); 
	$data = json_decode($html); 
	return $data; 
} 

function buildOutputRows($data)
{ 
	//Build an array of output rows 
	$rows = array(); 
	//As FTTP generally offers the fastest service look for those first 
	if ($data->avail_infra_b4rn_fttp == 'AVAILABLE') 
	{	 
		$row = 'BARN Gigabit FTTP is available and will be the fastest service available in this postcode.'; 
		$rows[] = $row; 
 	}
	
	//This mini code snippet is missing additional processing that shows filtering for FTTC speeds and more
	return $rows;
}