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