Background

We aim to provide price transparency around all 39 regions for all major energy provider. To stay true to the quality expectations we place upon ourselves we offer a summary of the entire coverage for New Zealand (without the prices themselves) to allow consumers to get a detailed appreciation of our price availability.

For example our own monitoring platform for generates a heatmap of price completeness across New Zealand using such data.

Making the Request

Using your language of choice, make a GET request to the https://api.ahiko.io/v1/coverage 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": 
    {
      "provider_plan_coverage": [
        {
          "provider_id": "provider_tmkykkpdcn2kglsy4ylxmzv7kf",
          "pricing_plans": [
            "plan_1"
          ]
        }
      ],
      "network_reporting_region_coverage": [
        {
          ...
        }
      ]
    }
}

Let's break this response down:

success is true. That means that the request was successful
data is the payload which contains 2 parts:
- provider_plan_coverage: object - array of provider and associated plans across the country
- network_reporting_region_coverage: object - array of coverage regions for every reporting region (in order) per provider

Electricity Provider Coverage (`provider_plan_coverage: array [object]`)

This captures the union of all electricity provider plan combinations available across New Zealand and they are represented in an array with the following:

provider_id : string - the unique identifier of the energy provider.
pricing_plans : array[string] - a list of named supported pricing plans.

Region Coverage (`network_reporting_region_coverage: array[object]`)

This is an ordered list (by network_reporting_region numerically) of the data quality of all the pricing plans within the respective region.

{
      ...,
      "network_reporting_region_coverage": [
        {
          "network_reporting_region": "1",
          "providers": [
            {
              "id": "provider_tmkykkpdcn2kglsy4ylxmzv7kf",
              "created_age_days": 3,
              "updated_age_days": 4,
              "pricing_plans": [
                {
                  "user_pricing": "standard",
                  "plan": "plan_1",
                  "daily_reference_price": 1.12
                }
              ]
            }
          ]
        }
      ]
}

network_reporting_region : string - the unique identifier of the network reporting region.
providers : array[providers] - a list of named supported pricing plans.
id : string - the unique identifier of the energy provider.
created_age_days : int - the number of days that have passed since the plan was first created
updated_age_days : int - the number of days that have passed since the plan was updated

Pricing Plan (`pricing_plans: array[object]`)

This is a list of pricing plans that contain some light-weight information referring to the plan. It is very high level, for more detail pricing plan information you need to query the https://api.ahiko.io/v1/plans endpoint. The attributes captured in here include:

user_pricing : string (enum: [low | standard]) - a simple enumeration of low or standard pricing which a user gets to chose for their household per ICP.
plan : string - a free form name provided by the Electricity Retailer that is used to describe their energy plan
daily_reference_price : float \ - this is the latest daily amount quoted by the Energy Provider, it's available to provide some insight as to the actual value of the data that was sampled in the coverage analysis