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 addresses 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.

Query: addressUprns

postcode - String

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.

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

{
  "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"
          }
        }
      ]
    }
  }
}

• 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.

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.

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.

Query: addressMeterpoints

uprn - String postcode - String

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.

• 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

• 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.

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
        }
    }
}

{
  "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",
        }
      ]
    }
  }
}

• 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.

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.

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:

We aren't allowed to use the REL address data in the switching API without a license from Ordinance Survey. Therefore, we actually use the MPL address data but use the REL address format.

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

The quote endpoint does not support the REL Address format, so you will need to convert the address from the old format before sending the quote mutation. A mapping is provided below:

The account enrolment validation logic will be able to simultaneously validate using the ECOES/DES cache and the live APIs. 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 account enrolment data. It should be provided in the address section of each electricity_meter_point and gas_meter_point. In the absense of a UPRN, the old validation logic will apply.