Broadband Map¶

Broadband Map APIs¶

The Broadband Map availability API provides a simplified programmatic access to details of the availability of broadband access technologies at a specified map location. Also providers API returns a list of data providers with some details about them.

Version 1.0¶

The Broadband Map API Version 1.0 will be deprecated on 1st February 2022.

If you are a Version 1.0 customer, please see our guide on Upgrading Availability API from v1 to v2.

For the current version of the BroadbandMap API and all new customers, please see the API documentation for Version 2.0.

Availability API¶

Returns the details of the availability of broadband access technologies at a specified map location.

Resource URLs¶

Environment	URL
production	https://api.broadbandmap.nz/api/1.0/availability/yx/<y>/<x>?api_key=<key>
staging	https://stage-api.broadbandmap.nz/api/1.0/availability/yx/<y>/<x>?api_key=<key>

Parameters¶

Parameter	Data Type	Presence	Rules	Description	Examples
<x>	numeric	required	Must be a number between 166.2 and 178.6 Can be integer or decimal up to 7 digits to the right of decimal point	The longitude of the point at which network availability should be calculated.	174.8075834
<y>	numeric	required	Must be a number between -47.5 and -34.2 Can be integer or decimal up to 7 digits to the right of decimal point	The latitude of the point at which network availability should be calculated.	-36.9026834
<key>	alphanumeric	required	Individually assigned per user	Each user gets one or multiple assigned api tokens to be used with each query as a way of identification / access control.	abc123

Response details¶

Field	Presence	Data Type	Valid Response Data
results	required	list of objects	A list of objects ordered by max download speed descending “fastest first”.
technology	required	text	The underlying technology of this layer. Note: A value is chosen here, rather than using technology as a key for an object to allow for more complex technology names in future. Currently either: “Fibre”, “Cable”, “VDSL”, “Wireless” or “ADSL”.
availability	required	text	Of the form “Not Available”, “Available”, “Planned” or “Underway”.
completion	optional	text	Completion date, if known and if availability is “Planned” or “Underway”.
set_id	required	numeric	The set ID of the map tile layer relating to this technology.
providers	optional	list of objects	This list is provided for all availability statuses except “Not Available”.
name	required	text	The name of this network provider.
wholesale_network	required	text	“Yes” if this network is only available as a wholesale product otherwise “No”, or “Both”
url	required	text	URL of this provider.
bandwidth_min_mbps	required	numeric	The lowest downstream speed that can be expected.
bandwidth_max_mbps	required	numeric	The highest downstream speed that can be expected.
bandwidth_up_min_mbps	required	numeric	The lowest upstream speed that can be expected.
bandwidth_up_max_mbps	required	numeric	The highest upstream speed that can be expected.
location	required	tuple of numerics	List with two numeric values, the latitude and longitude that this intersection belongs to.

HTTP Headers¶

Server-to-Client¶

The system will send the following headers to the client:

Header	Value	Comments
Content-Type	application/json	Send a standard Content-Type header for JSON.

Examples¶

Request:

curl --location --request GET 'https://api.broadbandmap.nz/api/1.0/availability/yx/-36.9026834/174.8075834?api_key=abc123'

Response:

{
  "location": [
    "174.8075834",
    "-36.9026834"
  ],
  "results": [
    {
      "availability": "Planned",
      "completion": "to complete by June 2018",
      "providers": [
        {
          "bandwidth_max_mbps": 1000.0,
          "bandwidth_min_mbps": 50.0,
          "bandwidth_up_max_mbps": 1000.0,
          "bandwidth_up_min_mbps": 10.0,
          "name": "Chorus",
          "timing_id": 2,
          "url": "https://www.chorus.co.nz/network-upgrade-map",
          "wholesale_network": "Yes"
        }
      ],
      "set_id": 1822,
      "technology": "Fibre"
    },
    {
      "availability": "Not Available",
      "set_id": 1874,
      "technology": "Cable"
    },
    {
      "availability": "Available",
      "providers": [
        {
          "bandwidth_max_mbps": 60.0,
          "bandwidth_min_mbps": 15.0,
          "bandwidth_up_max_mbps": 18.0,
          "bandwidth_up_min_mbps": 5.0,
          "name": "Chorus",
          "timing_id": 0,
          "url": "https://www.chorus.co.nz/network-upgrade-map",
          "wholesale_network": "Yes"
        }
      ],
      "set_id": 1773,
      "technology": "VDSL"
    },
    {
      "availability": "Available",
      "providers": [
        {
          "bandwidth_max_mbps": 10.0,
          "bandwidth_min_mbps": 5.0,
          "bandwidth_up_max_mbps": 5.0,
          "bandwidth_up_min_mbps": 3.0,
          "name": "Compass",
          "timing_id": 0,
          "url": "http://www.compass.net.nz/",
          "wholesale_network": "No"
        }
      ],
      "set_id": 1816,
      "technology": "Wireless"
    },
    {
      "availability": "Available",
      "providers": [
        {
          "bandwidth_max_mbps": 21.0,
          "bandwidth_min_mbps": 10.0,
          "bandwidth_up_max_mbps": 1.4,
          "bandwidth_up_min_mbps": 1.0,
          "name": "Chorus",
          "timing_id": 0,
          "url": "https://www.chorus.co.nz/network-upgrade-map",
          "wholesale_network": "Yes"
        }
      ],
      "set_id": 1772,
      "technology": "ADSL"
    }
  ]
}

Error codes¶

The broadband map API returns both HTTP status codes and a simplified JSON response on errors.

HTTP status code	Application error code	Comments
400 BAD REQUEST	400	The request was invalid. For example you may have provided coordinates outside of New Zealand.
401 UNAUTHORIZED	401	Your api_key is invalid.
500 INTERNAL SERVER ERROR	500	The server encountered an error processing your request. This may be a transient error, however if problems persist please contact registry@internetnz.net.nz

Examples:

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
Date: Tue, 12 Jul 2016 00:39:49 GMT
Server: Apache/2.4.16 (Amazon) mod_wsgi/3.5 Python/2.7.10
Vary: Accept-Encoding
Content-Length: 78
Connection: keep-alive

{
  "code": 400,
  "error": "Coordinates are out of service coverage area."
}

HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json
Date: Mon, 11 Jul 2016 23:14:20 GMT
Server: Apache/2.4.16 (Amazon) mod_wsgi/3.5 Python/2.7.10
Vary: Accept-Encoding
Content-Length: 254
Connection: keep-alive

{
  "code": 401,
  "error": "The server could not verify that you are authorized to access the URL requested.  You either supplied the wrong credentials (e.g. a bad password), or your browser doesn't understand how to supply the credentials required."
}

HTTP/1.0 500 INTERNAL SERVER ERROR
Content-Type: application/json
Date: Tue, 12 Jul 2016 00:39:49 GMT
Server: Apache/2.4.16 (Amazon) mod_wsgi/3.5 Python/2.7.10
Vary: Accept-Encoding
Date: Thu, 07 Jul 2016 04:59:44 GMT

{
  "code": 500,
  "error": "Error getting data from koordinates. (Error code: 403)"
}

Version 2.0¶

Availability API¶

Returns the details of the availability of broadband access technologies at a specified map location.

Resource URLs¶

Environment	URL
production	https://api.broadbandmap.nz/api/2.0/availability/<lat>/<lng>

Authentication¶

Your API key must be provided as the value to the ‘x-api-key’ header in the request.

Parameters¶

Parameter	Data Type	Presence	Rules	Description	Examples
<lat>	numeric	required in url	Must be a number between -47.5 and -34.2 Can be integer or decimal up to 7 digits to the right of decimal point	The latitude of the point at which network availability should be calculated.	-36.9026834
<lng>	numeric	required in url	Must be a number between 166.2 and 178.6 Can be integer or decimal up to 7 digits to the right of decimal point	The longitude of the point at which network availability should be calculated.	174.8075834
<x-api-key>	alphanumeric	required in header	Individually assigned per user	Each user gets one or multiple assigned api tokens to be used with each query as a way of identification / access control.	abc123

Response details¶

The response is a JSON encoded object.

Field	Presence	Data Type	Valid Response Data
results	required	list of objects	A list of objects ordered by max download speed descending “fastest first”.
technology	required	text	The underlying technology of this layer. Currently either: “fibre”, “cable”, “vdsl”, “wireless” or “adsl”.
availability	required	text	Of the form “unavailable”, “available” or “planned”.
planned_date	optional	text	Completion date, if known and if availability is “planned”.
providers	optional	list of objects	This list is provided for all availability statuses except “Not Available”.
name	required	text	The name of this network provider.
wholesale_network	required	text	“Yes” if this network is only available as a wholesale product otherwise “No”, or “Both”
url	required	text	URL of this provider.
bandwidth_min_mbps	required	numeric	The lowest downstream speed that can be expected.
bandwidth_max_mbps	required	numeric	The highest downstream speed that can be expected.
bandwidth_up_min_mbps	required	numeric	The lowest upstream speed that can be expected.
bandwidth_up_max_mbps	required	numeric	The highest upstream speed that can be expected.
location	required	object of numerics	Object with two numeric values, the latitude (value of “lat”) and longitude (value of “lng”) of the request.

Examples¶

Request:

curl --location \
--request GET 'https://api.broadbandmap.nz/api/2.0/availability/-41.2908663/174.7703795' \
--header 'x-api-key: abc123'

Response:

{
  "location": {
    "lat": "-41.2908663",
    "lng": "174.7703795"
  },
  "results": [
    {
      "availability": "planned",
      "providers": [
        {
          "bandwidth_max_mbps": 1000.0,
          "bandwidth_min_mbps": 50.0,
          "bandwidth_up_max_mbps": 1000.0,
          "bandwidth_up_min_mbps": 10.0,
          "name": "Chorus",
          "planned_date": "Fri, 30 Dec 2022 00:00:00 GMT",
          "url": "https://www.chorus.co.nz/network-upgrade-map",
          "wholesale_network": "Yes"
        }
      ],
      "technology": "fibre"
    },
    {
      "availability": "available",
      "providers": [
        {
          "bandwidth_max_mbps": 1000.0,
          "bandwidth_min_mbps": 200.0,
          "bandwidth_up_max_mbps": 100.0,
          "bandwidth_up_min_mbps": 20.0,
          "name": "Vodafone",
          "planned_date": null,
          "url": "https://www.vodafone.co.nz/broadband/",
          "wholesale_network": "No"
        }
      ],
      "technology": "cable"
    },
    {
      "availability": "unavailable",
      "technology": "vdsl"
    },
    {
      "availability": "available",
      "providers": [
        {
          "bandwidth_max_mbps": 100.0,
          "bandwidth_min_mbps": 10.0,
          "bandwidth_up_max_mbps": 40.0,
          "bandwidth_up_min_mbps": 5.0,
          "name": "Spark",
          "planned_date": null,
          "url": "https://www.spark.co.nz/shop/internet/wirelessbroadband/",
          "wholesale_network": "No"
        }
      ],
      "technology": "wireless"
    },
    {
      "availability": "available",
      "providers": [
        {
          "bandwidth_max_mbps": 21.0,
          "bandwidth_min_mbps": 10.0,
          "bandwidth_up_max_mbps": 1.4,
          "bandwidth_up_min_mbps": 1.0,
          "name": "Chorus",
          "planned_date": null,
          "url": "https://www.chorus.co.nz/network-upgrade-map",
          "wholesale_network": "Yes"
        }
      ],
      "technology": "adsl"
    }
  ]
}

Error codes¶

The broadband map API returns both HTTP status codes and a simplified JSON response on errors.

HTTP status code	Application error code	Comments
400 BAD REQUEST	400	The request was invalid. For example you may have provided coordinates outside of New Zealand.
403 FORBIDDEN	401	Your API key is invalid or missing in the “x-api-key” header.
500 INTERNAL SERVER ERROR	500	The server encountered an error processing your request. This may be a transient error, however if problems persist please contact registry@internetnz.net.nz

Examples:

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
  "code": 400,
  "error": "Given coordinates are not valid."
}

HTTP/1.1 403 FORBIDDEN
Content-Type: application/json

{
  "message": "Forbidden"
}

HTTP/1.0 500 INTERNAL SERVER ERROR
Content-Type: application/json

{
  "code": 500,
  "error": "Internal Server Error"
}

Data Providers list API¶

This API returns a list of Broadband Map data providers with some details about them.

Resource URLs¶

Environment	URL
production	https://api.broadbandmap.nz/api/2.0/providers

Response details¶

The response is a JSON encoded object. Each provider presents as an object.

Field	Presence	Data Type	Valid Response Data
results	required	list of objects	A list of objects contain providers details.
name	required	text	Data provider’s organization name
description	required	text	A short description about the provider.
areaServed	required	list of text	List of regions served by the provider.
technologies	required	list of text	List of broadband technologies offered by the provider.
url	required	text	An URL to the provider’s website.

Examples¶

Request:

curl --location \
--request GET 'https://api.broadbandmap.nz/api/2.0/providers' \
--header 'x-api-key: abc123'

Response (shortened):

{
  "results": [
    {
      "areaServed": [
        "Canterbury"
      ],
      "description": "",
      "name": "Amuri.net",
      "technologies": [
        "Wireless"
      ],
      "url": "https://www.amuri.net/"
    },
    {
      "areaServed": [
        "Canterbury"
      ],
      "description": "",
      "name": "WiFi Guys",
      "technologies": [
        "Wireless"
      ],
      "url": "http://www.wifiguys.co.nz/"
    },
    {
      "areaServed": [
        "Gisborne",
        "Hawke's Bay"
      ],
      "description": "",
      "name": "Gisborne.net",
      "technologies": [
        "Wireless"
      ],
      "url": "http://gisborne.net/"
    },
    {
      "areaServed": [
        "Canterbury"
      ],
      "description": "",
      "name": "Altra Internet",
      "technologies": [
        "Wireless"
      ],
      "url": "https://www.altra.co.nz/"
    }
  ]
}

Error codes¶

The broadband map API returns both HTTP status codes and a simplified JSON response on errors.

HTTP status code	Application error code	Comments
403 FORBIDDEN	-	Your API key is invalid or missing in the “x-api-key” header.
500 INTERNAL SERVER ERROR	500	The server encountered an error processing your request. This may be a transient error, however if problems persist please contact registry@internetnz.net.nz

Examples:

HTTP/1.1 403 FORBIDDEN
Content-Type: application/json

{
  "message": "Forbidden"
}

HTTP/1.0 500 INTERNAL SERVER ERROR
Content-Type: application/json

{
  "code": 500,
  "error": "Internal Server Error"
}

Upgrading Availability API from v1 to v2¶

Changes are related to authentication method and expected response structure.

Authentication:

Your API key must be provided as the value to the ‘x-api-key’ header in the request.
Providing an incorrect API key returns 403 rather than 401. Check V2 Error codes

Example: Difference in accessing the Version 1.0 vs. Version 2.0 on the Broadband Map API

Version 1.0:

curl --location --request GET 'https://api.broadbandmap.nz/api/1.0/availability/yx/-36.9026834/174.8075834?api_key=abc123'

Version 2.0:

curl --location \
--request GET 'https://api.broadbandmap.nz/api/2.0/availability/-41.2908663/174.7703795' \
--header 'x-api-key: abc123'

Response:

‘set_id’ and ‘timing_id’ are removed.
‘completion’ becomes ‘planned_date’ and moves into the provider object.
‘technology’ and ‘availability’ are lower case.
‘availability’ no longer has “Underway” as a possible result and “Not Available” becomes “unavailable”.
‘location’ changes from a list to an object, with descriptive keys.

Broadband Map Availability API Plans and Prices¶

The Availability API of the National Broadband Map is intended for the following purpose:

To enable current owners and occupiers or potential owners and occupiers to find out what broadband is available at that location.

This purpose enables a wide range of uses both for companies looking at their own locations and for those looking for information on behalf of their customers.

Unfortunately, due to licensing restrictions this API cannot be used for any form of research whether market research or more general public benefit research.

Monthly Plans¶

We have three simple plans for organisations with a sustained query load and the flexibility of a monthly contract.

Dedicated API Key
Access to customer support during office hours
Lookup data can be cached for up to 10 business days
1000 free queries for initial testing and integration
Billed monthly in advance. Cancel with one month’s notice.
Over plan usage billed monthly in arrears

Plan	Bundled queries	Price
Low usage plan	75,000 per month (Additional queries charged at 1c per query)	$500 month
Medium usage plan	150,000 per month (Additional queries charged at 1c per query)	$750 month
High usage plan	300,000 per month (Additional queries charged at 1c per query)	$1,500 month

All prices are exclusive of GST. Query rate limits apply

What counts as a query?

Any call made to the Availability API, which receives a complete (non-error) response.

How can I track my usage?

We send out monthly invoices with your usage.

What are your standard office hours?

9am to 5pm Monday to Friday. Out of hours support is 24x7x365 initially through an answer service who escalate to our on call team of engineers.

What happens if I exceed my chosen volume of queries?

For Monthly Plans we bill you the overage in the following month at the equivalent cost per query for your plan.

What is the maximum query rate?

For Monthly Plans it’s 2 queries per second with bursts up to 20 queries per second.

Where do I find documentation on the API?

Visit our documentation site https://docs.nzrs.net.nz/broadbandmap/

How do I purchase API access?

Contact us at bbmap@nzrs.net.nz and we’ll be happy to help.

Note

For further information contact: Sonya Trompetter bbmap@internetnz.net.nz

Guide to generate radio prediction outputs¶

What file formats are accepted for the Broadband Map

A GIS format such as shapefile or Geodatabase of the radio prediction output. A KML with an embedded raster of the radio prediction output A KML with a polygon of the radio prediction output For reference here is the powerpoint slides from the breakfast session

DIY - Radio Prediction Modelling¶

The following steps are for organisations that wish to generate their own coverage maps using the CloudRF.com web interface.

Step 1:

Use this template spreadsheet to help you get the right data in one place. Fill out the data for each of your towers (note this is also the format we use if you would like us to do the work for you).
If you need help working out or converting the the coordinates of your tower, this LINZ website may be of use.

Step 2:

For this step visit CloudRF.com and complete the following steps:
Create a free account at https://cloudrf.com Get familiar with the web interface with online support on the interface here Upload your data Magic happens ;-)

Step 3:

Export coverage as files for the BBMap - preference for KML or Shapefile

Step 4:

Submit coverage files to bbmap@internetnz.net.nz

InternetNZ Processed - Radio Prediction Modelling¶

If your preference is to have someone else do the work, InternetNZ are happy to process your tower data on a cost recovery basis. These are the steps required for this process.

Step 1:

Use this template spreadsheet to help you get the right data in one place. Fill out the data for each of your towers.
Submit the data to bbmap@internetnz.net.nz

Step 2:

InternetNZ use Cloud RF’s API to process the data and setup FME (Feature Manipulation Engine) to automate the data transformation.

Step 3:

InternetNZ generated coverage maps are confirmed with you to make sure the coverage files represent reality.

Step 4:

InternetNZ loads coverage maps onto the BBMap
This process is charged on a cost recovery basis with two parts.
First time setup for your organisation. Fixed setup fee of $1,000 + GST Subsequent coverage updates. Fixed fee of $250 +GST per update

Support¶

Should you need any support or guidance please do not hesitate to contact the team at bbmap@internetnz.net.nz