Widget v2 Documentation

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

Include Script
Important Note on URL Usage
Important Note on Token Usage
Displaying the Data
Lead Generation
Branding
Add a Badge
Moving to Production

Include Script

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

<script
  src="https://test-app.broadbandavailability.com/widget.js"
  data-token="YOUR_TOKEN"
  data-postcode="POSTCODE"
  data-uprn="UPRN"
  data-address="ADDRESS"
  defer
></script>

Understanding the parameters:

Parameter	Optional	Description	Example
data-token	false	Your token. Ask your account manager for more info.	data-token=”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”

The script URL used in the example above (https://test-app.broadbandavailability.com/widget.js) is for the test environment. When moving to a production environment, you will need to update this URL. See the "Moving to Production" section at the end of this document for details on how to switch to the production URL.

Important Note on Token Usage

When you receive your token, it will be in the format bbuk-u-tDMERRbYOt. For the data-token parameter, you should use only the last 10 characters of this token. In this example, you would use tDMERRbYOt.

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://test-app.broadbandavailability.com/assets/logo/blue.svg"
    alt="BroadbandUK logo"
  />
</button>

<!-- Button with dynamic colour -->
<!--   replace "xxxxxxxxxx" with your user token -->
<!--   you can control the colour of this logo from within the customisation tab -->
<button onclick="bbukHandleOnClick();">
  <img
    src="https://test-app.broadbandavailability.com/assets/logo/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://test-app.broadbandavailability.com/widget.js"
  data-element="custom-element-id"
  data-token="YOUR_TOKEN"
  data-postcode="POSTCODE"
  data-uprn="UPRN"
  data-address="ADDRESS"
  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://test-app.broadbandavailability.com/assets/logo/white.svg"
  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 Badge

BroadbandUK is proud to partner with estate agents who share our commitment to providing accurate and reliable broadband information to potential buyers and renters. Our API and data widget are licensed under the Creative Commons Attribution Licence (CC BY 4.0).

By using BroadbandUK's data, you agree to:

Attribution: Provide clear and appropriate credit to BroadbandUK as the data source when displaying or using data from our API or widget.
Backlink Requirement: Include a dofollow backlink to BroadbandUK's website in your estate agency website footer.

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].

Badge Formats

The preferred badge formats are listed below (with a dofollow link to https://www.broadbandproviders.co.uk):

Primary Badge (Recommended)

Display the blue and white BroadbandUK Data Partner badge on your website and marketing materials to highlight your use of our broadband data. This badge should be your first choice in most situations.

Secondary Badge

In cases where the primary badge doesn't fit your existing design aesthetic, you may use the all-white version of the badge. This option provides flexibility when you need the badge to blend seamlessly with your existing design.

Badge implementation

<!-- Primary Badge -->
<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: 205px; height: 71px;"
      src="https://app.broadbandavailability.com/assets/v2/broadbanduk-primary-badge.png"
      alt="BroadbandUK logo"
    />
  </a>
</div>

<!-- Secondary Badge -->
<div data-site="bbuk">
  <a href="https://www.broadbandproviders.co.uk" target="_blank">
    <img
      style="display: block; width: 270px; height: 61.5px;"
      src="https://app.broadbandavailability.com/assets/v2/broadbanduk-secondary-badge.png"
      alt="BroadbandUK logo"
    />
  </a>
</div>

(Primary Badge PNG) https://app.broadbandavailability.com/assets/v2/broadbanduk-primary-badge.png
(Secondary Badge PNG) https://app.broadbandavailability.com/assets/v2/broadbanduk-secondary-badge.png
(Primary Badge SVG) https://app.broadbandavailability.com/assets/v2/broadbanduk-primary-badge.svg
(Secondary Badge SVG) https://app.broadbandavailability.com/assets/v2/broadbanduk-secondary-badge.svg

Badge Use

Position the badge in a visible location within your website footer.
Link the badge to www.broadbandproviders.co.uk with a dofollow link.
Minimum badge height: 40px
Always maintain the original aspect ratio when resizing.
Do not rotate or animate the badge.

Badge Space

Standard: Maintain a minimum clear area equal to one-quarter the height of the badge.

Limited space: Maintain a minimum clear area equal to one-tenth the height of the badge.

Moving to Production

Once you have thoroughly tested the widget in the test environment and are ready to go live, follow these steps to move to production:

Sign Terms and Conditions Before using the widget in a production environment, you must sign our terms and conditions. This can be done through our dashboard at:

https://dashboard.broadbandavailability.com
Update the Script URL After signing the terms and conditions, update your script tag to use the production URL.

<script
  src="https://app.broadbandavailability.com/widget.js"
  data-token="YOUR_TOKEN"
  data-postcode="POSTCODE"
  data-uprn="UPRN"
  data-address="ADDRESS"
  defer
></script>