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 support@nzrs.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)"
}