Address & Meter Point Migration

Background
address Query
meterpoint Query
REL Address

Previously clients used the addresses GraphQL query to obtain a list of addresses for a given postcode and the corresponding electric and gas meter points associated with each address.

This query uses an internal Kraken database as it's data source. This database is outdated. We are unable to directly replace the data source with the ECOES and Xoserve APIs due to limitations with the API's.

Therefore, we have split the existing address query into two new queries: addressUprns and addressMeterpoints.

We are unable to determine if an address is domestic or business until we get the response from the second query, after a consumer has selected their address. Once the consumer has selected an address, and you perform the addressMeterpoints query, you can calculate the consumer type from meterpoint data that is returned. If you wish to have separate onboarding journeys for domestic & business, this is where you will need to diverge the logic or redirect the user.

Given a postcode, this will return a list of unique addresses obtained from both ECOES and Xoserve.

Schema

Query: addressUprns

Arguments

postcode - String

Output

A UniqueRELAddressType object is returned for each unique address that belongs to the postcode. This uses the new address format RELAddress. See the REL Address section for more information.

The addresses are returned unordered/unsorted.

Example Query

query getAddresses ($postcode: String!) {
    addressUprns(postcode: $postcode) {
        totalCount
        edgeCount
        edges {
            node {
                uprn
                display
                primaryName
                secondaryName
                street1
                street2
                locality1
                locality2
                town
                postcode
            }
        }
    }
}

Example Response

{
  "data": {
    "addressUprns": {
      "totalCount": 1,
      "edgeCount": 1,
      "edges": [
        {
          "node": {
            "uprn": "123456789012",
            "display": "10, Road, TOWN",
            "primaryName": "10",
            "secondaryName": null,
            "street1": "Road",
            "street2": null,
            "locality1": null,
            "locality2": null,
            "town": "TOWN",
            "postcode": "AB12 3CD"
          }
        }
      ]
    }
  }
}

Errors

KT-GB-6620 - Invalid postcode has been entered.
KT-GB-6630 - Either of the ECOES or Xoserve API's return an error.
KT-GB-6611 - No addresses exist for the postcode.

Limitations

This query will make 1 API call to ECOES EES API and 1 API call to the Xoserve GES Supply Point Switching API.

Clients should ensure usage will fall within their contracted limits with ECOES & Xoserve.

Caching

All ECOES & Xoserve requests will be cached for 1 month. This will lower the number of requests made to each external API, to speed up our response time and reduce reliance on 3rd party systems.

Given a postcode and the UPRN obtained from the previous step, this will return a list of the electric and gas meter points registered at the address.

Schema

Query: addressMeterpoints

Arguments

uprn - String

postcode - String

Output

An AddressMeterPointsType object is returned for the input unique address - this contains a list of electricityMeterPoints and a list of gasMeterPoints. One address could contain multiple meter points, with a mix of domestic and business.

Unlike the old addresses query, you are able to retrieve the full technical details about the meter point, but you should only request the fields you need to build a quote for the consumer. See below for a suggested query.

`electricityMeterPoints`

- To work out if an address is Domestic, you can either use the profileClass and measurementClass, or domesticConsumerIndicator. Profile Class 1 or 2, or 0 with Measurement Class F is Domestic.

In approx 0.6% of cases, the domesticConsumerIndicator doesn't match the profileClass. Onboarding validation is currently based on the profileClass, so you will get some failed enrolments if you use the domesticConsumerIndicator

- meterType of K, S or T are traditional pre-pay meters

`gasMeterPoints`

- You can use marketSectorCode to determine if the MPRN is domestic. D = Domestic and I = Industrial and Commercial

- Gas meter point details contain the Annual Quantity mpaq, which you can use to build the quote.

- meterMechanismCode of ET, PP, MT or CM are traditional pre-pay meters.

Example Query

query AddressMeterpoints($uprn: String!, $postcode: String!) {
  addressMeterpoints(uprn: $uprn, postcode: $postcode) {
        electricityMeterPoints {
            mpan
            gspGroupId
            profileClass
            meteredIndicator
            energyDirection
            meters {
                meterType
            }
        }
        gasMeterPoints {
            mprn
            ldzId
            mpaq
            marketSectorCode
            meterMechanismCode
        }
    }
}

Example Response

{
  "data": {
    "addressMeterpoints": {
      "electricityMeterPoints": [
        {
          "mpan": "1111110000000",
          "gspGroupId": "_J",
          "profileClass": 1,
          "energyDirection": "I",
          "meters": [
            {
              "meterType": "S2A",
            }
          ]
        }
      ],
      "gasMeterPoints": [
        {
          "mprn": "1111100000",
          "ldzId": "SE",
          "mpaq": "34203.0",
          "marketSectorCode": "D",
          "meterMechanismCode": "S2",
        }
      ]
    }
  }
}

Errors

KT-GB-6620 - Invalid postcode has been entered.
KT-GB-6631 - Invalid UPRN has been entered.
KT-GB-6630 - Either of the ECOES or Xoserve API's return an error.
KT-GB-6632 - There was no address matching the UPRN, or the address had no meter points.

Limitations

This query will make an external API call for every meter point at the address, so this will usually be 1 ECOES and 1 Xoserve call - but it could be more.

Clients should ensure usage will fall within their contracted limits with ECOES & Xoserve.

Caching

All ECOES & Xoserve requests will be cached for 1 month. This will lower the number of requests made to each external API, to speed up our response time and reduce reliance on 3rd party systems.

REL Addresses (Retail Energy Location) are a new format for addresses that were introduced by Ofgem to reduce switching errors. There is more information here. It has created a standard format for the address:

Name	Description	Example
primaryName	This is the Primary Addressable Object description. This is normally the name and or number of the property	London House
secondaryName	This is the Secondary Addressable Object description, e.g. the “Flat 2” in the address “Flat 2, London House, Exeter”. This is only relevant for a child property. “London House” in this case will the Primary Name of the parent property.	Flat 2
street1	Street	Witton Grove
street2	Dependant Thoroughfare	Witton Grove East
locality1	Dependant Locality	Durham
locality2	Double Dependant Locality	Durham East
town		Pity Me
postcode		DH1 6AD

Notes

A display string is provided in the response for your convenience, but its usage is optional. You should note, as per the switching API specifications, that the logical display order for the REL Address Data Elements is: Secondary Name, Primary Name, Street 2, Street 1, Locality 2, Locality 1, Town

Address Mapping

The quote endpoint does not support the REL Address format, so you will need to convert the address to the old format before sending the quote mutation. A mapping is provided below:
numbered_address.uprn = rel_address.uprn
numbered_address.delivery_point_identifier = rel_address.secondary_name
numbered_address.line_1 = rel_address.primary_name + " " + rel_address.street_1
numbered_address.line_2 = rel_address.street_2
numbered_address.line_3 = rel_address.locality_2
numbered_address.town = rel_address.town
numbered_address.county = rel_address.locality_1
numbered_address.postcode = rel_address.postcode

Account Enrolment

The account enrolment validation logic will be able to simultaneously validate using the ECOES/DES cache and the live API's. When you have generated a quote using these new queries, you need to modify the enrolment data to ensure we perform the correct validation, otherwise the validation will likely fail leading to a failed enrolment. All you need to do is include the UPRN in the enrolment data. In the absense of a UPRN, the old validation logic will apply.

Octopus Energy

Address & Meter Point Migration

Table of contents

Background

Address Query

Schema

Arguments

Output

Example Query

Example Response

Errors

Limitations

Caching

Meterpoint Query

Schema

Arguments

Output

`electricityMeterPoints`

`gasMeterPoints`

Example Query

Example Response

Errors

Limitations

Caching

REL Address

Notes

Address Mapping

Account Enrolment