The Broadband Map API provides a simplified programmatic access to details of the availability of broadband access technologies at a specified map location.
Returns the details of the availability of broadband access technologies at a specified map location.
| 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> |
| Parameter | Data Type | Presence | Rules | Description | Examples |
|---|---|---|---|---|---|
| <x> | numeric | required |
|
The longitude of the point at which network availability should be calculated. | 174.8075834 |
| <y> | numeric | required |
|
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 |
| 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. |
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. |
Request:
DocumentationGET /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"
}
]
}
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)"
}