Background

The Installation Control Point (ICP) tells you how a property is connected to the electricity network in New Zealand. Each residence has a unique ICP number that identifies it as an individual power connection. We provide some light insights regarding an ICP most importantly providing the Network Reporting Region that the given ICP is associated with.

Making the Request

Using your language of choice, make a GET request to the https://api.ahiko.io/v1/icp-details 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": {
    "icp_number": "0005834930RN094",
    "flow_directions": ["injection","extraction"],
    "network_reporting_region": "17",
    "active": true,
    "smart_meter": true
  }
}

Let's break this response down:

success is true. That means that the request was successful
data is the payload which contains 5 fields
- icp_number: string - the original ICP number provided
- flow_directions : array[string (enum: [injection | extraction])] - a simple list enumerating the type of flow directions available at the ICP, injection is equivalent to a flow provided by solar when you are exporting to the grid, whereas extraction is equivalent to a flow consumption when you are consuming from the grid.
- network_reporting_region: string - the Network Reporting Region for the given ICP, necessary when wanting to understand the unique prices for a given ICP address
- active: boolean - whether or not the ICP address is presently actively consuming or exporting to the grid
- smart_meter: boolean - whether or not 30 min interval level smart meter is available at the ICP address