Background

Network reporting regions reflect how the country of New Zealand is divided into distinct priceable groups. The process of delivering electricity to a consumer starts with the generation and the unique mix of Generation, Transmission and Distribution is reflected by having a distinct network reporting region.

Source

New Zealand is currently broken up into 39 network reporting regions, each one represented by a geographical boundary driven by the energy generation. We provide a simple articulation of this list via an API call.

Prerequisites

Before you can follow this guide, you will need:

To be able to make a request in your programming language of choice, our API reference has example requests using multiple common languages and libraries, just look for the "Language" dropdown at the top of the page.
Your subscription key (32 alphanumerical combination key).

Making the Request

Using your language of choice, make a GET request to the https://api.ahiko.io/v1/network_reporting_regions endpoint, with the following headers:

ahiko-app-id {{application subscription key}}

Where the {{application subscription key}} is replaced with your application subscription key.

Handling Errors

The Ahiko API returns standard HTTP response codes.
Below are the most common error codes and their reasons:

200 Everything is OK. The response is included in the body.
404 The url does not exist. Check you have entered the url correctly.
403 You are not allowed to access this resource. Make sure you have a valid user access token with the correct permissions. Also make sure you have set the Authorization header correctly (note the American spelling).

You should treat any response code that is greater than 399 as an error.

Handling the Response

The Ahiko API uses JSON to encode responses. Most languages have libraries to encode and decode JSON.

The API response will look like:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Region ABC",
      "network_provider": "ABC Energy"
    }
  ]
}

Let's break this response down:

success is true. That means that the request was successful
data is a list. It contains a separate entry for every Network Reporting Region

Data (`data : list`)

Contains 3 attributes, namely:

id : int - the unique identity of the Network Reporting Region, it is an integer value
name : string - a human readable name of the Region
network_provider : string - a human readable name of theNetwork Provider