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:

GroupFieldExample 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; }