You are viewing the documentation for the BroadbandUK Widget API v1. If you are looking for the latest version, please refer to the latest documentation.

Widget v1 Documentation

Welcome to BroadbandUK’s Availability widget API v1. This document serves as a guide to help you integrate our service into your website.

Make a Request
Include Script
Displaying the Data
- Method 1
- Method 2
Lead Generation
Branding
Add a Backlink

Make a Request

Make a call from your back-end to: https://api.broadbandavailability.uk/request/v1/ on each page load.

A cURL example request:

curl --location --request POST 'https://api.broadbandavailability.uk/request/v1/' \
--header 'Authorization: bbuk-u-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

A working example written in PHP:

<?php

// Make a curl request to get a request token:
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.broadbandavailability.uk/request/v1/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => array(
    'Authorization: bbuk-u-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  ),
));

$response = curl_exec($curl);
$response = json_decode( $response );

curl_close($curl);

?>

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Broadband Availability Checker</title>
</head>
<body><?php

  if( $response->success ){ ?>

    <script async defer
      src="https://api.broadbandavailability.uk/js/v1/?v=1"
      data-postcode="XXXXXXX"
      data-uprn="XXXXXXXXXXXX"
      data-token="bbuk-u-xxxxxxxxxx"
      data-address="ADDRESS"
      data-request="<?php print $response->token; ?>"
    ></script>

    <div onclick="bbukHandleOnClick();">

      <label>BroadbandUK Availability</label>
      <img src="https://api.broadbandavailability.uk/assets/logo/blue" style="width: 24px;height: 24px;" />

    </div>

  <?php } else { ?>

    <p>Error: <?php print $response->error; ?></p>

  <?php } ?>

</body>
</html>

Include your secret key as an authorisation header. You can get this from https://dash.broadbandavailability.uk/ if you’ve forgotten it or don’t have one yet.

This will return JSON.

A successful response looks like

{
  "success": true,
  "token": "XXXXXXXXXX"
}

A failed response looks like

{
  "success": false,
  "error": "Bad request."
}

If the success value is true you are good to go. Use the token value in the next step, replacing REQUEST_TOKEN.

Include Script

Insert the following snippet onto any page you would like this service to exist on.

<script
  src="https://api.broadbandavailability.uk/js/v1/"
  data-token="bbuk-u-xxxxxxxxxx"
  data-request="REQUEST_TOKEN"
  data-postcode="ADDRESS_POSTCODE"
  data-uprn="ADDRESS_UPRN"
  data-address="ADDRESS"
  async
  defer
></script>

Understanding the parameters:

Parameter	Optional	Description	Example
data-token	false	Your user ID. You can find yours or get one at: https://dashboard.broadbandavailability.com	data-user=”bbuk-u-XXXXXXXXXX”
data-request	false	A one time request token, authorising your request. Generate a new token on page load.	data-request=”XXXXXXXXXX”
data-postcode	false	The postcode for the property you would like broadband information for.	data-postcode=”NG11 6SL”
data-uprn	true	The Unique Property Reference Number (UPRN) for the property.	data-uprn=”XXXXXXXXX”
data-address	true	The property address	data-address="9 Harebell Avenue"
data-element	true	Allows for a custom front-end display to be created. Set this to a custom element’s Id and this element will be used to house the frame. See “Method 2” for more on how this is used.	data-element=”custom-element-id”

If you don’t know what the property UPRN is or where to find it, you can use our tool at: https://dash.broadbandavailability.uk/uprn

Displaying the Data

There are two different methods from here. You can either use our plug-and-play method, described as Method 1, or you can create your own front-end popup, with Method 2.

Method 1

The plug-in-and-play approach. By adding this function call on button click, our pre-styled pop-up will display the property’s data. Here are three options to choose from:

<!-- Plain button with no logo  -->
<button onclick="bbukHandleOnClick();">BroadbandUK Availability</button>

<!-- Button with logo -->
<!--   you can change the colour of the logo by changing the URL. For all options, see the customisation tab -->
<button onclick="bbukHandleOnClick();">
  <img
    src="https://api.broadbandavailability.uk/assets/logo/blue"
    alt="BroadbandUK logo"
  />
</button>

<!-- Button with dynamic colour -->
<!--   replace "bbuk-u-xxxxxxxxxx" with your user token -->
<!--   you can control the colour of this logo from within the customisation tab -->
<button onclick="bbukHandleOnClick();">
  <img
    src="https://api.broadbandavailability.uk/assets/logo/u/bbuk-u-xxxxxxxxxx"
    alt="BroadbandUK logo"
  />
</button>

Method 2

If you would like to control the look and feel of the wrapper, you can simply include the element parameter to your script include tag. You can then control how the wrapper opens as well as what it looks like. You may include it as shown here:

<script
  src="https://api.broadbandavailability.uk/js/v1/"
  data-element="custom-element-id"
  data-token="bbuk-u-xxxxxxxxxx"
  data-request="REQUEST_TOKEN"
  data-postcode="ADDRESS_POSTCODE"
  data-uprn="ADDRESS_UPRN"
  data-address="ADDRESS"
  async
  defer
></script>
<!-- set data-element to the id of an element you would like our frame to sit within -->

If an element with the provided Id doesn’t exist, we revert back to Method 1.

Lead Generation

To support the ongoing costs of the service, we include a lead generation section within the Widget. This can be removed by subscribing to our Premium tier.

By default, the widget displays a "More Info" button within the table of providers and speeds.

Clicking the “More Info” button will redirect users to the relevant ISP website, where they will have the option to express their interest by entering their details.

Branding

To keep our service looking consistent across our partner sites, we ask that you respect our brand guidelines and use our icon as part of the button.

<img
  src="https://api.broadbandavailability.uk/assets/logo/white"
  style="width: 24px;height: 24px;"
/>

You can choose either blue or white, currently, although we will be adding more options shortly.

We suggest you use the text “Broadband Availability” or similar for the button although this is up to you.

Add a Backlink

BroadbandUK's API and data widget are licensed under the Creative Commons Attribution Licence (CC BY 4.0), which allows others to share and adapt the provided data while requiring appropriate attribution. In addition to the CC BY 4.0 licence, we kindly request that you include a backlink to BroadbandUK's website (https://www.broadbandproviders.co.uk) in the footer section of your estate agency website.

By utilising BroadbandUK's data, you agree to the following licensing terms:

Attribution: When displaying or using the data obtained through the API or widget, you must provide clear and appropriate credit to BroadbandUK as the data source.
Backlink Requirement: In order to acknowledge our data contribution and support our mission, we request that you include a backlink to BroadbandUK's website in the footer of your estate agency website.

Complying with both the attribution and backlink requirements ensures proper acknowledgement of the data source and supports the availability of valuable broadband information for users.

If you have any questions regarding the licensing terms or the implementation of the CC BY 4.0 licence, please contact our team at [email protected].

The preferred backlink formats are listed below (with a hyperlink to https://www.broadbandproviders.co.uk):

<!-- our recommended way -->
<div data-site="bbuk" style="display: inline-block; text-align: center;">
  <a href="https://www.broadbandproviders.co.uk" target="_blank">
    <img
      style="display: block; width: 439px; height: 115px;"
      src="https://api.broadbandavailability.uk/assets/badges/webp/data-partner-1-black.webp"
      alt="BroadbandUK logo"
    />
  </a>
</div>

<!-- if you'd like something a little smaller -->
<div data-site="bbuk">
  <a href="https://www.broadbandproviders.co.uk" target="_blank">
    <img
      style="display: block; width: 300px; height: 300px;"
      src="https://api.broadbandavailability.uk/assets/badges/webp/data-partner-2-black.webp"
      alt="BroadbandUK logo"
    />
  </a>
</div>

Here is a full list of our available assets:

SVG (rectangular)

SVG (square)

WEBP (rectangular)

WEBP (square)

PNG (rectangular)

PNG (square)