Broadband Map API

The Broadband Map API provides a simplified programmatic access to details of the availability of broadband access technologies at a specified map location.

GET availability

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://api-stage.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:

GET /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)"
}

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.

On-demand Plan

For those with varying query volumes where you are only billed for the queries that you use.

  • Dedicated API Key
  • Access to customer support during office hours
  • 200 free queries for initial testing and integration
  • Billed monthly in arrears for queries over that month (minimum $20 per month). Cancel with one month’s notice.
Plan Bundled queries Price
On-demand None 10c per query

All prices are exclusive of GST. Query rate limits apply


Business Plans

For businesses with a sustained query load and the flexibility of a monthly contract.

  • Dedicated API Key
  • Access to customer support during office hours
  • 1000 free queries for initial testing and integration
  • Billed monthly in advance. Cancel with one month’s notice.
Plan Bundled queries Price
Business 1 4,000 month $200 month (equivalent to 5c per query)
Business 2 10,000 month $300 month (equivalent to 3c per query)
Business 3 20,000 month $400 month (equivalent to 2c per query)
Business 4 50,000 month $500 month (equivalent to 1c per query)

All prices are exclusive of GST. Query rate limits apply


Enterprise Plans

For high volume users who want the lowest price possible.

  • Multiple dedicated API keys
  • Lookup data can be cached for up to 10 business days
  • Access to customer support including out of hours
  • 20,000 free queries for initial testing during integration
  • Billed annually in advance. Cancel with one month’s notice.
Plan Bundled queries Price
Enterprise 1 2,000,000 year $15,000 year (equivalent to 0.75c per query)
Enterprise 2 5,000,000 year $20,000 year (equivalent to 0.4c per query)
Enterprise 3 10,000,000 year $25,000 year (equivalent to 0.25c per query)
Enterprise 4 15,000,000 year $30,000 year (equivalent to 0.20c per query)

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 Business Plans we bill you the overage in the following month at the equivalent cost per query for your plan. For Enterprise Plans we automatically move you up a tier and bill accordingly

What is the maximum query rate?

For Business Plans it’s 2 queries per second with bursts up to 5 queries per second. For Enterprise Plans it’s 10 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: David Morrison david@internetnz.net.nz mbl:0274366182